L_FileInfo

Summary

Gets information about the specified file and fills the specified FILEINFO structure with the information.

Syntax

L_LTFIL_API L_INT L_FileInfo(pszFile, pFileInfo, uStructSize, uFlags, pLoadOptions)

Parameters

L_TCHAR* pszFile

Character string containing the input file name to query.

pFILEINFO pFileInfo

Pointer to the FILEINFO structure to be filled.

Note

Never pass an uninitialized FILEINFO structure to L_FileInfo.

L_UINT uStructSize

Size in bytes, of the structure pointed to by pFileInfo, for versioning. Use sizeof(FILEINFO).

L_UINT uFlags

Flag indicating which members to update in the FILEINFO structure, if any. The FILEINFO_TOTALPAGES and FILEINFO_USEFILTERDATA values can be OR-ed together, in which case both values are retrieved. Possible values are:

pLOADFILEOPTION pLoadOptions

Pointer to optional extended load options. Pass NULL to use the default load options.

Returns

Comments

To use this function, perform the following steps:

1. Declare a variable with the datatype of FILEINFO.

2. Declare and assign a character string variable for the file name.

3. If you are getting information about a multipage file (which can contain more than one image), use the LOADFILEOPTION structure to specify the page number. The information that you get will be for the image on the specified page. L_FileInfo treats an entire page as one image (although a page can contain multiple embedded images).

4. Initialize the FILEINFO structure to zero values and set the structure size to sizeof(FILEINFO).

5. If you know the file format, set FILEINFO.Flags to FILEINFO_FORMATVALID and FILEINFO.Format to the file format. This can speed up L_FileInfo because LEADTOOLS will not have to try various filters to find out which filter can handle the file.

   If you do not know the file format but do know the original filename, set FILEINFO.Flags to FILEINFO_NAMEVALID and set the original file name in FILEINFO.Name. LEADTOOLS will use this as a hint and try the file formats commonly associated with that particular file extension first.

6. Call the L_FileInfo function, passing the file name, the address of the FILEINFO variable, and the size of the FILEINFO structure as parameters.

7. Get the image information from the fields described in the FILEINFO structure.

If the FILEINFO_USEFILTERDATA flag is passed to L_FileInfo, it is possible that the function will return filter data values that can be used to speed up other Load or Convert functions. See Using Filter Data to Speed up Loading Large Files for more information.

The FILEINFO_TOTALPAGES and FILEINFO_USEFILTERDATA flags can be OR-ed together. Passing both flags indicate that both the total number of pages and the filter data are to be retrieved.

Notes:

• More options are available in the LOADFILEOPTION structure.

• For information about loading and saving large TIFF files faster, refer to Loading and Saving Large TIFF/BigTIFF Files.

• For a summary of file information functions, refer to Getting and Setting File Information.

• Never pass an uninitialized FILEINFO structure to this function. It is important to initialize at least the FILEINFO.uStructSize and FILEINFO.Flags. If FILEINFO.Flags is zero, the other structure members are ignored. But if FILEINFO.Flags is not zero, one or more of the other members of the FILEINFO structure must be initialized properly.

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.

Platforms

Win32, x64, Linux.

See Also

Functions

• L_FileInfoMemory
• L_ReadFileComment
• L_GetPCDResolution
• L_SetPCDResolution
• L_SetPDFOptions
• L_GetWMFResolution
• L_SetWMFResolution
• L_SetLoadInfoCallback
• L_GetComment
• L_GetDefaultLoadFileOption
• L_SetComment
• L_DeleteComment
• L_SetFilterInfo
• L_GetFilterListInfo
• L_FreeFilterInfo
• L_GetFilterInfo
• L_ReadFileComments
• L_Setlocale
• L_SetlocaleW
• L_SetDecryptOptions

Topics

• Raster Image Functions: Input and Output
• Loading and Saving Images
• Using Filter Data to Speed up Loading Large Files
• Loading Encrypted Files
• For a list of functions that utilize the LOADFILEOPTION or SAVEFILEOPTION structures, refer to the Usage section of their documentation.

Example

For complete sample code, refer to the INFO example.
This example gets file information and displays it in a message box.

L_INT FileInfoExample(L_VOID) 
{ 
   L_INT nRet; 
   FILEINFO FileInfo;        /* LEAD File Information structure. */ 
   L_TCHAR szMessage[1024];  /* Buffer to hold information for display. */ 
 
   /* Get the file information */ 
   memset(&FileInfo, 0, sizeof(FILEINFO)); 
   FileInfo.uStructSize = sizeof(FileInfo); 
   // for fast file info only, use the following: 
   L_EnableFastFileInfo(TRUE); 
   nRet = L_FileInfo(MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image3.cmp")), &FileInfo, sizeof(FILEINFO), 0, NULL); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   /* Format the message string with data from the FILEINFO structure */ 
   wsprintf(szMessage, TEXT("Filename:   %s\n\n") 
                  TEXT("Format:   %d\n\n") 
                  TEXT("Width:   %d\n\n") 
                  TEXT("Height:   %d\n\n") 
                  TEXT("BitsPerPixel:   %d\n\n") 
                  TEXT("Size On Disk:   %ld\n\n") 
                  TEXT("Size In Memory:   %ld\n\n") 
                  TEXT("Compression:   %s"), 
                  (L_TCHAR  *) FileInfo.Name, 
                  FileInfo.Format, 
                  FileInfo.Width, 
                  FileInfo.Height, 
                  FileInfo.BitsPerPixel, 
                  (long)FileInfo.SizeDisk, 
                  (long)FileInfo.SizeMem, 
                  (L_TCHAR  *) FileInfo.Compression ); 
   /* Display the message string */ 
   MessageBox( NULL, szMessage, TEXT("File Information"), MB_OK ); 
   return SUCCESS; 
}