L_TwainSaveTemplateFile

Summary

Enumerates all supported or specified capabilities, and the current or default values, for the currently selected TWAIN source and saves them to the specified template file.

Syntax

L_LTTWN_API L_INT L_TwainSaveTemplateFile (hSession, lpszTemplateFile, uFlags, puCapabilities, uCount, pfnCallBack, pUserData)

Parameters

HTWAINSESSION hSession

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

L_TCHAR* lpszTemplateFile

Character string that contains the name of the template file in which the TWAIN source capability settings will be saved. The extension for LEADTOOLS template files is .ltt.

L_UINT uFlags

Flag that specifies whether to save the current values, the default values, or all possible values. Possible values are:

L_UINT* puCapabilities

The array of capabilities to save to disk. Pass NULL to save all capabilities supported by the TWAIN driver.

L_UINT uCount

The number of elements in puCapabilities the array.  Pass 0 to save all capabilities support by the TWAIN driver.

LTWAINTEMPLATECALLBACK pfnCallBack

Optional callback function. This function is called after enumerating the capability from the TWAIN source, but before the capability value has been saved to the template file. If you provide a callback function, use the function pointer as the value of this parameter.

L_TwainSaveTemplateFile 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

Comments

Call this function to save a specified array of capabilities to disk. Or pass NULL to save all capabilities to disk. The values saved to disk can be altered using the flags.

To load the saved values from disk and apply those to the TWAIN Driver, use the L_TwainLoadTemplateFile 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.

See Also

Functions

• L_TwainStartCapsNeg
• L_TwainEndCapsNeg
• L_TwainLoadTemplateFile

Topics

• Handling Template Files
• TWAIN Functionality: Template File Functions

Example

L_INT EXT_CALLBACK SaveTemplateCB(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_TwainSaveTemplateFile 
   } 
 
   return TWAIN_SUCCESS; 
} 
 
L_INT TwainSaveTemplateFileExample(HTWAINSESSION hSession, L_TCHAR * pszFileName) 
{ 
   L_INT nRet; 
   L_UINT capabilities[] = {ICAP_PIXELTYPE, ICAP_BITDEPTH, ICAP_XFERMECH, ICAP_XRESOLUTION, ICAP_YRESOLUTION}; 
   L_UINT count = sizeof(capabilities) / sizeof(L_UINT); 
 
   L_TwainStartCapsNeg(hSession); 
 
   nRet = L_TwainSaveTemplateFile(hSession, pszFileName, LTWAIN_CAPABILITY_GETCURRENT, capabilities, count, SaveTemplateCB, NULL); 
   if (nRet != SUCCESS)  
   { 
      MessageBox (NULL, TEXT("Failed to save template file"), TEXT("ERROR"), MB_OK); 
      return nRet; 
   } 
 
   L_TwainEndCapsNeg(hSession); 
   return SUCCESS; 
}