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

L_INT EXT_CALLBACK SaveTemplateCB(HTWAINSESSION hSession, pTW_CAPABILITY pCapability, L_INT nStatus, L_VOID* pUserData)
{
   if(nStatus != TWAIN_SUCCESS)
   {
      CString cs;
      cs.Format(_T("Capability %d errored with %d"), pCapability->Cap, nStatus);		
      MessageBox (NULL, (LPCTSTR)cs, TEXT("ERROR"), MB_OK);

      if(pCapability->Cap == ICAP_XRESOLUTION)
         return TWAIN_SUCCESS_ABORT;  // Ends L_TwainSaveTemplateFile
   }	

   return TWAIN_SUCCESS;
}