Home › Forums › TWAIN Classic › TW_CUSTOMDSDATA question › Re: TW_CUSTOMDSDATA
OK, this is really weird – my copy of the twain.h file (version 1.9 March 2000) declares the TW_CUSTOMDSDATA structure as
typedef struct {
TW_UINT32 InfoLength; /* Length of Information in bytes. */
TW_HANDLE hData; /* Place holder for data, DS Allocates */
} TW_CUSTOMDSDATA, FAR *pTW_CUSTOMDSDATA;
This is the original declaration introduced in the TWAIN 1.7 spec! On Windows, a TW_HANDLE is a global handle, the kind you use GlobalAlloc, GlobalFree, GlobalLock and GlobalUnlock on. In my experience, data sources (Fujitsu, Canon, HP) follow this declaration – the 2nd field is a (4-byte) HANDLE to global memory, or HGLOBAL.
The TWAIN spec seems to be FUMTU on this subject: Not only do later revisions contain an incompatible and confusing declaration of TW_CUSTOMDSDATA, but different sections make contradictory claims about this feature. Under DG_CONTROL/DAT_CUSTOMDSDATA/MSG_GET it says
This operation is used by the application to query the data source for its current settings, e.g.
DPI, paper size, color format. The sources settings will be returned in a
TW_CUSTOMDSDATA structure. The actual format of the data in this structure is data source
dependent and not defined by TWAIN.
Of course, TWAIN does define the format of the data in that structure. I suppose the author meant to say ‘…the format of the data referenced by the InfoData field is data source dependent…’. Here’s the definition of that structure, except that in my experience the declaration is tragically misleading about the InfoData field:
typedef struct {
TW_UINT32 InfoLength; /* Length (in bytes) of data */
TW_UINT8 InfoData[1]; /* Array (Length) bytes long */
} TW_CUSTOMDSDATA, FAR *pTW_CUSTOMDSDATA;
…
The format of the data contained in InfoData will be data source specific and will not be
defined by the TWAIN API. This structure will be used by an application to query the data
source for it’s current settings, and to archive them to disk. Although the format for this
custom data is not defined by TWAIN, source implementers are encouraged to use a ASCII
representation for the custom data to be used for settings archival. A Windows INI style
format would be easy to implement and allow for additional features to be added without
breaking backwards compatibility.
In my experience, several major vendors have implemented the original (1.7) spec – the 2nd field of the TW_CUSTOMDSDATA structure is a 4-byte Windows HGLOBAL. Those same vendors have also followed that advice about making their custom DS data a string of ASCII text in INI-file format or something like it. Note that the spec calls for the custom data to contain the entire settings of the DataSource: I just encountered a DS whose authors missed that part…
Why does it take 10 years to correct things like this in the spec? I volunteer to edit this part of the spec…