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


#include "l_bitmap.h"

L_INT pEXT_CALLBACK YourFunction(pszFileName, ppPassword, pUserData)


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.


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


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

  1. A decryption callback is provided in the FILEDECRYPTOPTIONS structure passed to L_SetDecryptOptions.
  2. 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:

  1. The callback provides the correct password (operation succeeds)
  2. 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

See Also




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

static L_INT EXT_CALLBACK 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 */ 
   L_GetDecryptOptions(&options, sizeof(FILEDECRYPTOPTIONS)); 
   options.pszPassword = L_TEXT("DefaultPassword"); 
   options.pfnCallback = GetPasswordProc; 
   options.pUserData = NULL; 
   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); 

Help Version 22.0.2023.7.11
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.