In This Topic ▼

LTwain::GetCapabilityFromFile

Summary

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

Syntax

#include "ltwrappr.h"

virtual L_INT LTwain::GetCapabilityFromFile (hFile, ppCapability, uIndex)

Parameters

HTWAINTEMPLATEFILE hFile

Handle to an existing template file.

pTW_CAPABILITY * ppCapability

Pointer to a pointer to a TW_CAPABILITY structure. This structure will be allocated internally.

L_UINT uIndex

Index of the capability to get from the file. This is a zero-based index.

Returns

Value	Meaning
SUCCESS	The function was successful.
< 1	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 LTwain::OpenTemplateFile 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:

Free the container of the TW_CAPABILITY structure by a calling LTwain::FreeContainer function.
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.

Example

// initialize session and call this function 
L_INT LTwain__GetCapabilityFromFileExample(CMyTwain *MyClass, HWND hWndParent) 
{ 
   OPENFILENAME         ofn; 
   L_INT                nRet; 
   HTWAINTEMPLATEFILE   hFile; 
   L_TCHAR              szFilePath [MAX_PATH]; 
 
   memset (&ofn, 0, sizeof(OPENFILENAME));  
   memset (szFilePath, 0, MAX_PATH);  
 
   ofn.lStructSize   = sizeof(OPENFILENAME);  
   ofn.hwndOwner     = hWndParent;  
   ofn.lpstrFile     = szFilePath;  
   ofn.nMaxFile      = MAX_PATH;  
   ofn.lpstrTitle    = TEXT("Load Template File"); 
 
   if (GetOpenFileName (&ofn))  
   { 
      nRet = MyClass->OpenTemplateFile(&hFile, szFilePath, LTWAIN_TEMPLATE_OPEN_READ);  
 
      if (nRet == SUCCESS)  
      { 
         L_UINT uIndex, uCapCount = 0;  
         pTW_CAPABILITY ptwCapability = NULL;  
         uCapCount = MyClass->GetNumOfCapsInFile(hFile);  
 
         if (uCapCount > 0)  
         { 
            for (uIndex = 0 ; uIndex < uCapCount ; uIndex ++) 
            { 
               nRet = MyClass->GetCapabilityFromFile(hFile, &ptwCapability, uIndex);  
 
               if (nRet == SUCCESS)  
               { 
                  nRet = MyClass->SetCapability(ptwCapability, LTWAIN_CAPABILITY_SET);  
               } 
               else 
                  return nRet; 
 
               if (ptwCapability)  
               { 
                  GlobalFree (ptwCapability->hContainer);  
                  GlobalFreePtr (ptwCapability);  
               } 
            } 
         } 
         MyClass->CloseTemplateFile(hFile);  
      } 
      else 
         return nRet; 
   } 
 
   return SUCCESS; 
}