L_TwainLoadTemplateFile

#include "lttwn.h"

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

HTWAINSESSION hSession;	/* handle to an existing TWAIN session */
L_TCHAR * lpszTemplateFile;	/* template file name */
LTWAINTEMPLATECALLBACK pfnCallBack;	/* callback function */
L_VOID * pUserData;	/* pointer to more parameters for the callback */

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

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 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.
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.
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

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.

See Also

Functions:	L_TwainStartCapsNeg, L_TwainEndCapsNeg, L_TwainSaveTemplateFile
Topics:	Handling Template Files
	TWAIN Functionality: Template File Functions

Example

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;
}
L_INT EXT_CALLBACK LoadTemplateCB(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_TwainLoadTemplateFile
   }	
   return TWAIN_SUCCESS;
}