In This Topic ▼

FILEDECRYPTCALLBACK

Summary

This function is called to provide a decryption password when you try to load or get information about a file which uses encryption.

Syntax

#include "l_bitmap.h"

L_INT pEXT_CALLBACK YourFunction(pszFileName, ppPassword, pUserData)

Parameters

const L_TCHAR *pszFileName

Pointer to the name of the encrypted file.

L_TCHAR **ppPassword

Pointer to a pointer to a buffer that will contain the password. The password in *ppPassword should be NULL-terminated and in Unicode format (UTF16 format in Windows applications, UTF8 on Unix platforms). Your callback should allocate this buffer using L_AllocBuffer and store the password in it (make sure you to allocate space for the null terminator). LEADTOOLS automatically frees this buffer, so you do not need to free it.

L_VOID *pUserData

A void pointer that you can use to access a variable or structure containing data that your callback function needs. This gives you a way to receive data indirectly from the function that uses this callback function. This is equal to the FILEDECRYPTOPTIONS.pUserData value from the structure that was passed to the L_SetDecryptOptions function.

Keep in mind that this is a void pointer, which must be cast to the appropriate data type within your callback function.

Returns

Value	Meaning
SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

This function will be called if one of the conditions below is met:

A decryption callback is provided in the FILEDECRYPTOPTIONS structure passed to L_SetDecryptOptions.
LEADTOOLS is trying to load or get information about an encrypted file and the current decryption password is invalid for the current file.

LEADTOOLS will call this function repeatedly until:

The callback provides the correct password (operation succeeds)
The callback returns operation fails error code

You should be careful to avoid infinite loops. If the callback returns each time the same incorrect password, the application will go into an infinite loop. That is because when FILEDECRYPTCALLBACK returns an invalid password, LEADTOOLS will call it again. And if FILEDECRYPTCALLBACK provides the same bad password each time, the process would never end, consuming a lot of CPU time until you kill the application.

Required DLLs and Libraries

LTFIL
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

This example loads a file encrypted with the password "Excel"

L_INT GetPasswordProc(const L_TCHAR* pszFileName, L_TCHAR** ppszPassword, L_VOID* pUserData) 
{ 
   /* A proper implementation would bring up a message box asking the user "please provide a password for the file 'pszFileName'" */ 
   /* We will keep it simple and hardcode a password, but we will need to prevent an infinite loop. So we will not provide the same password more than once for the same file */ 
   static L_TCHAR szOldFileName[L_MAXPATH]; 
   if (!_tcscmp(pszFileName, szOldFileName)) 
      return ERROR_INV_PASSWORD; /* I already tried this password for this file */ 
   L_TCHAR* pszMyPassword = L_TEXT("Excel"); 
   L_INT nRet = L_AllocBuffer((_tcslen(pszMyPassword) + 1) * sizeof(L_TCHAR), (L_VOID**)ppszPassword); 
   if (nRet == SUCCESS) 
   { 
      memcpy(*ppszPassword, pszMyPassword, (_tcslen(pszMyPassword) + 1) * sizeof(L_TCHAR)); 
      _tcscpy_s(szOldFileName, _countof(szOldFileName), pszFileName); /* store the filename to indicate that we already provided the password for this filename */ 
   } 
   return nRet; 
} 
 
L_INT TestLoadEncrypted(pBITMAPHANDLE pBitmap) 
{ 
   L_TCHAR* pszFileName = L_TEXT("Encrypted - Encrypted Excel.xlsx"); 
 
   /* Provide a default password 'DefaultPassword'. If this is not valid, call the GetPasswordProc function */ 
   FILEDECRYPTOPTIONS options; 
   L_GetDecryptOptions(&options, sizeof(FILEDECRYPTOPTIONS)); 
   options.pszPassword = L_TEXT("DefaultPassword"); 
   options.pfnCallback = GetPasswordProc; 
   options.pUserData = NULL; 
 
   L_SetDecryptOptions(&options); 
 
   FILEINFO fileInfo = { sizeof(FILEINFO) }; 
   L_INT nRet; 
   if ((nRet = L_FileInfo(pszFileName, &fileInfo, sizeof(FILEINFO), 0, NULL)) != SUCCESS) 
      return nRet; 
 
   return L_LoadBitmap(pszFileName, pBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGRORGRAY, NULL, &fileInfo); 
}