L_TwainGetCapabilityFromFile

#include "lttw2.h"

L_INT EXT_FUNCTION L_TwainGetCapabilityFromFile (hSession, hFile, pptwCapability, uIndex)

HTWAINSESSION hSession;	/* handle to an existing TWAIN session */
HTWAINTEMPLATEFILE hFile;	/* handle to an existing template file */
pTW_CAPABILITY * pptwCapability;	/* pointer to a pointer to a structure */
L_UINT uIndex;	/* capability index */

Gets the capability, at the specified index, in the specified file.

Parameter	Description
hSession	Handle to an existing TWAIN session. This handle is obtained by calling the L_TwainInitSession function.
hFile	Handle to an existing template file.
pptwCapability	Pointer to a pointer to a TW_CAPABILITY structure. This structure will be allocated internally.
uIndex	Index of the capability to get from the file. This is a zero-based index.

Returns

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

Comments

To get a capability stored in a file; the file must be opened for reading by calling L_TwainOpenTemplateFile function. The user must declare a variable of type pTW_CAPABILITY and pass the address of this to the function. This parameter will be updated with a pointer to the capability at the specified index.

Note:

If the function is successful, the user must:

$image\sqrblit.gif$ Free the container of the TW_CAPABILITY structure by a calling L_TwainFreeContainer function.

$image\sqrblit.gif$ Free the value referenced by the contents of the pptwCapability using GlobalUnlock and GlobalFree.

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_TwainOpenTemplateFile, L_TwainAddCapabilityToFile, L_TwainTemplateDlg, L_TwainGetNumOfCapsInFile, L_TwainCloseTemplateFile, L_TwainInitSession, L_TwainEndSession.
Topics:	Handling Template Files
	TWAIN Functionality: Capability Functions.

Example

HTWAINSESSION g_hSession;
OPENFILENAME ofn;
L_INT nRet;
HTWAINTEMPLATEFILE hFile;
L_TCHAR szFilePath [MAX_PATH];
HWND hDlg; // Parent dialog handle

memset (&ofn, 0, sizeof(OPENFILENAME));
memset (szFilePath, 0, MAX_PATH);

ofn.lStructSize = sizeof(OPENFILENAME);
ofn.hwndOwner = hDlg;
ofn.lpstrFile = szFilePath;
ofn.nMaxFile = MAX_PATH;
ofn.lpstrTitle = TEXT("Load Template File");

if (GetOpenFileName (&ofn))
{
   nRet = L_TwainOpenTemplateFile (g_hSession, &hFile, szFilePath, LTWAIN_TEMPLATE_OPEN_READ);

   if (nRet == SUCCESS)
   {
      L_UINT uIndex, uCapCount = 0;
      pTW_CAPABILITY ptwCapability = NULL;
      nRet = L_TwainGetNumOfCapsInFile (g_hSession, hFile, &uCapCount);

      if (nRet == SUCCESS)
      {
         for (uIndex = 0 ; uIndex < uCapCount ; uIndex ++)
         {
            nRet = L_TwainGetCapabilityFromFile (g_hSession, hFile, &ptwCapability, uIndex);

            if (nRet == SUCCESS)
            {
               nRet = L_TwainSetCapability (g_hSession, ptwCapability, LTWAIN_CAPABILITY_SET);
             }

            if (ptwCapability)
            {
               GlobalFree (ptwCapability->hContainer);
               GlobalUnlock(ptwCapability);
               GlobalFree (ptwCapability);
            }
         }
      }
   L_TwainCloseTemplateFile (g_hSession, hFile);
   }
}