D_GETSTRING

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

D_GETSTRING Selector

Parameter: PluginStringQuery * dcselectioncontents

If the dialog currently on display contains any Doobri structures of class dcSelection (see Doobri classes ), the RIP requires strings to fill in the associated selection element. (Be it a combo box, option list, or whatever.)

The RIP obtains these strings by making repeated calls to D_GETSTRING . Upon each call, the plugin should return the next string. To indicate that the last string has been sent, D_GETSTRING return a string of length zero.

Each string returned can be up to 64 bytes in length, or the size of the associated DICTSTRUCTION string element, or the value supplied in the cb parameter, whichever is the smaller. Note that the example plugins define ShortString as 32 bytes, not 64. You may wish to change this.

Note: Earlier RIPs had a bug which caused memory corruption if a string was more than 36 chars long (including terminal NUL ).

The PluginStringQuery structure is defined in the header file gdevdlg.h :

      typedef struct PluginStringQuery { int32 doobriID;
      int32 n;
      int32 cb;
      uint8 *psz;
    } PluginStringQuery;

Note: Because D_GETSTRING is not passed the dialogID in instances of PluginStringQuery , it relies on doobriID s being unique across all dialogs. If they are not, the plugin will not know which dialog is being displayed and therefore which strings to return.

doobriID

This is the identifier of the dcSelection Doobri for which strings are being requested.

n

This is the index of the string in the list currently being requested. It is set to zero by the RIP before the first call, and incremented before each subsequent call for this menu.

cb

The Rip sets this to the maximum permitted length of the string returned, including the null‐terminator.

The plugin should check that the strings it assigns to psz are no longer than this, otherwise it will overwrite memory.

psz

This is a pointer to a region of memory in which the plugin should place the appropriate null‐terminated string.

Copy the characters into the string do not assign to the pointer psz . Do not exceed the 64-byte limit, which includes the NULL terminator.

To indicate the end of the list, set this to an empty string. That is, set the first character to 0 do not set psz to the NULL pointer.