LTwain::GetCapabilityFromFile

#include "ltwrappr.h"

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

HTWAINTEMPLATEFILE hFile;	/* handle to an existing template file */
pTW_CAPABILITY * ppCapability;	/* 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
hFile	Handle to an existing template file.
ppCapability	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.
< 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.

See Also

Functions:	LTwain::OpenTemplateFile, LTwain::AddCapabilityToFile, LTwain::TemplateDlg, LTwain::GetNumOfCapsInFile, LTwain::CloseTemplateFile, LTwain::InitSession, LTwain::EndSession.
Topics:	Handling Template Files
	TWAIN Functionality: Capability Functions.

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