Low Level TWAIN Functions

Note: This section is designed for advanced TWAIN programmers.

For almost all applications written using DTWAIN, there is no need to be concerned with the internals of the TWAIN API.  However, there may be certain times when it may be necessary to call the TWAIN Data Source Manager (DSM) directly.  Usually, this is done by C and C++ programmers who have experience with the TWAIN API, and would like to make the call to the DSM directly.  Even though DTWAIN covers most aspects of TWAIN, there are may be some aspects of the API that DTWAIN will not have covered completely.

To overcome these problems, DTWAIN has made available a gateway to the "raw" TWAIN API by providing the function DTWAIN_CallDSMProc.  For the DTWAIN_CallDSMProc to work, the application must call DTWAIN_SysInitialize prior to interfacing with the TWAIN DSM.

A call to DTWAIN_CallDSMProc has the form of the following:

Return Value = DTWAIN_CallDSMProc(TW_IDENTITY1, TW_IDENTITY2, DG, DAT, MSG, Data )

The TW_IDENTITY1 and TW_IDENTITY2 components represent the Origin and Destination DTWAIN_IDENTITY types, respectively, that are passed to the DSM.  A DTWAIN_IDENTITY data type is actually the address of the TWAIN Data Type called TW_IDENTITY.

The first DTWAIN_IDENTITY in the call to DTWAIN_CallDSMProc is usually the DTWAIN_IDENTITY of the application.  To retrieve  this value, the application must call DTWAIN_GetTwainAppID.

The second DTWAIN_IDENTITY in the call to DTWAIN_CallDSMProc is the DTWAIN_IDENTITY of the Source.  Sometimes, this value can be NULL, depending on the call being made to the DSM.  However, if a value is required for the second DTWAIN_IDENTITY, the DTWAIN_GetSourceID function returns the DTWAIN_IDENTITY of the Source.

The third, fourth, and fifth parameters to DTWAIN_CallDSMProc are the real major players in interfacing to the TWAIN API.  These parameters make up the Twain triplet that determine exactly what action the DSM will do.  If you have the Twain specification, the triplet is made up of three values; the DG or Data Group, the DAT or Data parameter, and the MSG or message parameter.  This is usually abbreviated as DG / DAT / MSG.  Consult the Twain specification for the various triplets and their usage.

The last parameter, Data,  is the Twain type called a TW_MEMREF.  This is actually a pointer to a void.  The reason for the pointer to a void is that the actual value placed here will depend on the triplet (the DG / DAT / MSG values) given.  Sometimes this can be a pointer to a TW_GRAYRESPONSE structure, a TW_CAPABILITY structure, etc.  These types are described in the TWAIN.H file provided by  Twain and details as to what type to supply is described in the Twain Specification.

The Return Value for DTWAIN_CallDSMProc will be one of the TWAIN values that are designated as the viable return types when a call to the DSM is made.  These return types are the TWRC_xxx constants defined in the TWAIN.H file.  For example, TWRC_SUCCESS, TWRC_FAILURE, TWRC_CHECKSTATUS, etc. are examples of these values.

Given the DTWAIN_CallDSMProc, DTWAIN is viable not only for easily integrating with the TWAIN API, but also can be used for those that are advanced TWAIN programmers who like to take control over the entire TWAIN session.