In This Topic ▼

L_TwainLoadTemplateFile

Summary

Loads the TWAIN capability values stored in the specified template file and sets the selected TWAIN source using these values.

Syntax

#include "lttwn.h"

L_LTTWN_API L_INT L_TwainLoadTemplateFile (hSession, lpszTemplateFile, pfnCallBack, pUserData)

Parameters

HTWAINSESSION hSession

Handle to an existing TWAIN session. This handle is obtained by calling the L_TwainInitSession function.

L_TCHAR * lpszTemplateFile

Character string that contains the name of the template file in which the TWAIN source capability settings will be loaded. Once loaded the TWAIN source will be set with the current values found in the template file. For more information on determining or setting the capabilities for a TWAIN source, refer to Getting and Setting Capabilities.

LTWAINTEMPLATECALLBACK pfnCallBack

Optional callback function. This function is called for each capability found in the template file. If the capability can be set, this callback is called after an attempt was made to set the capability. If the capability is read only, then the callback is called with nStatus set to TWAIN_SUCCESS. If you provide a callback function, use the function pointer as the value of this parameter.

L_TwainLoadTemplateFile calls this callback function as it enumerates each capability. The callback function must adhere to the following function prototype: LTWAINTEMPLATECALLBACK.

L_VOID * pUserData

Void pointer that you can use to pass one or more additional parameters that the callback function needs.

To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure. If the additional parameters are not needed, you can pass NULL in this parameter.

Returns

Value	Meaning
SUCCESS	The function was successful.
! = SUCCESS	An error occurred. Refer to Return Codes.

Comments

To load the TWAIN capability values stored in the specified template file and set the selected TWAIN source using these values, call the L_TwainLoadTemplateFile function.

To save the values from the TWAIN Driver to disk use the L_TwainSaveTemplateFile function.

This function should be called after calling the L_TwainStartCapsNeg function and before calling the L_TwainEndCapsNeg function.

Required DLLs and Libraries

LTTWN
For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files to be Included with your Application.

Example

L_INT EXT_CALLBACK LoadTemplateCB(HTWAINSESSION hSession, pTW_CAPABILITY pCapability, L_INT nStatus, L_VOID* pUserData) 
{ 
   UNREFERENCED_PARAMETER(hSession); 
   UNREFERENCED_PARAMETER(pUserData); 
 
   if(nStatus != TWAIN_SUCCESS) 
   { 
      L_TCHAR msg[2048] = {0}; 
      wsprintf(msg, TEXT("Capability %d errored with %d"), pCapability->Cap, nStatus); 
      MessageBox (NULL, msg, TEXT("ERROR"), MB_OK); 
 
      if(pCapability->Cap == ICAP_XRESOLUTION) 
         return TWAIN_SUCCESS_ABORT;  // Ends L_TwainLoadTemplateFile 
   } 
   return TWAIN_SUCCESS; 
} 
 
L_INT TwainLoadTemplateFileExample(HTWAINSESSION hSession, L_TCHAR * pszFileName) 
{ 
   L_TwainStartCapsNeg(hSession); 
   L_INT nRet; 
 
   nRet = L_TwainLoadTemplateFile(hSession, pszFileName, LoadTemplateCB, NULL); 
   if (nRet != SUCCESS)  
   { 
      MessageBox (NULL, TEXT("Failed to load template file"), TEXT("ERROR"), MB_OK); 
      return nRet; 
   } 
   L_TwainEndCapsNeg(hSession); 
   return SUCCESS; 
}