L_TwainSaveTemplateFile

#include "lttwn.h"

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

HTWAINSESSION hSession;

handle to an existing TWAIN session

L_TCHAR* lpszTemplateFile;

pointer to a character string

L_UINT uFlags;

optional flags

L_UINT* puCapabilities;

array of capabilities

L_UINT uCount;

number of elements in puCapabilities array

LTWAINTEMPLATECALLBACK pfnCallBack;

optional callback function

L_VOID * pUserData;

pointer to more parameters for the callback

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.

Parameter Description
hSession Handle to an existing TWAIN session. This handle is obtained by calling the L_TwainInitSession or L_TwainInitSession2 function.
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.
uFlags Flag that specifies whether to save the current values, the default values, or all possible values.  Possible values are:
  Value Meaning
  LTWAIN_CAPABILITY_GETCURRENT [3] Gets the current value.
  LTWAIN_CAPABILITY_GETDEFAULT [4] Gets the default value.
  LTWAIN_CAPABILITY_GETVALUES [5] Gets all available values.
puCapabilities The array of capabilities to save to disk. Pass NULL to save all capabilities supported by the TWAIN driver.
uCount The number of elements in puCapabilities the array.  Pass 0 to save all capabilities support by the TWAIN driver.
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.
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

SUCCESS

The function was successful.

! = SUCCESS

An error occurred. Refer to Return Codes.

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; 
} 

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS TWAIN C API Help