LFile::ReadFileAttachments

Summary

Reads the properties of the attachments embedded in the specified file.

Syntax

L_INT LFile::ReadFileAttachments(pszFile, ppAttachments, pLoadOptions, pInfo)

Parameters

L_TCHAR *pszFile

Character string containing the name of the owner file that may contain embedded attachments.

L_FILEATTACHMENTS **ppAttachments

Pointer to a variable that will be populated with the properties of any attachments found.

LOADFILEOPTION *pLoadOptions

Pointer to optional extended load options. Pass NULL to use the default load options. Refer to LFile::LoadFile for more information.

FILEINFO *pInfo

Pointer to a FILEINFO structure. This structure may contain file information used in loading an image, or it may be updated with information about the file being loaded.

This value can be NULL.

Refer to LFile::LoadFile for more information.

Returns

Comments

Applications can read the properties of the attachments included in a file by performing the following steps:

1. Declare a pointer of type L_FILEATTACHMENTS and set its value to NULL.
2. Call LFile::ReadFileAttachments on the owner file containing attachments, passing the address of the L_FILEATTACHMENTS pointer.
3. Process the attachments. An example of processing the attachments would be calling LFile::ExtractAttachment to extract the attachment's file data.
4. When the data is no longer needed, call LFile::FreeAttachments on the pointer to free the memory used by *ppAttachments (the L_FILEATTACHMENTS pointer).

[LFile:ReadFileAttachments returns the following values:

• SUCCESS: If the format of the owner file supports attachments (such as PDF), and the file contains one or more embedded attachments, ppAttachments will define a pointer to the structure containing the attachment's properties. Be sure the application calls LFile::FreeAttachments when the data is no longer needed.

• ERROR_NO_ATTACHMENTS: If the file is a format that supports attachments (such as PDF), but no attachments were found, ppAttachments will be set to NULL.

• ERROR_FEATURE_NOT_SUPPORTED: If the file is a format that does not support attachments (such as PNG or BMP), or LEADTOOLS does not support reading attachments of this type of format, ppAttachments will be set to NULL.

• ERROR_PDF_INVALID_PASSWORD: The owner file is protected with a password. You must supply the correct password using LFileSettings::SetPDFOptions before you can extract the attachment. Note that the attachment might have a password as well. When you call this function, you need to submit the password for the owner file.

The number of attachment items returned by this method is the same as the FILEINFO.nAttachmentCount value of the object returned by LFile::GetInfo.

Each L_FILEATTACHMENT contains properties of the attachment such as its pszFileName, uFileLength, and other information provided by the owner document.

Use LFile::ExtractAttachment to extract the binary content of the attachment file into an output disk file or stream for further processing (for example, by calling LFile::GetInfo or LFile::Load).

LEADTOOLS supports reading the attachments embedded in the following file format:

PDF

PDF files support embedded attachments of any number and file format (such as PDF, TIFF, XML, etc). PDF files can also be created as a portfolio which contains multiple files assembled into an integrated unit. In these types of documents, the file contains a single generic help page with text such as "For the best experience, open this PDF portfolio in a compatible viewer", as well as any number of attachments and a schema to control how to view the document. The value of FILEINFO.uFlags will contain FILEINFO_PORTFOLIO if the file is a PDF portfolio, and it is up to the application to specify any further handling of the file.

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

• LFile::FreeAttachments
• LFile::ExtractAttachment

Topics

• PDF Portfolio

Example

This example will do the following :

• Show information on all the attachments embedded in the file
• Extract the attachment files into an output directory
• Show the file format and page count of each attachment
• Please refer to the example for LFile::ExtractAttachment to see how to handle files protected with a password
  

  #include <stdio.h> 
   
  L_INT ReadFileAttachmentsExample(L_TCHAR* fileName, L_TCHAR* outputDir) 
  { 
  	L_UINT attachmentCount; 
   
  	// Get information on the owner file  
  	// This step is optional if we are not interested in determining whether the owner file format  
  	// or whether it is a PDF portfolio.  
  	FILEINFO fileInfo; 
  	LFile file; 
  	file.SetFileName(fileName); 
  	L_INT ret = file.GetInfo(&fileInfo, sizeof(FILEINFO), FILEINFO_TOTALPAGES, NULL); 
  	if (ret != SUCCESS) 
  		return ret; 
   
  	printf("Information\n"); 
  	printf("Format:%d\n", fileInfo.Format); 
  	// If PDF, check if it is portfolio  
  	if (fileInfo.Format == FILE_RAS_PDF) 
  		printf("IsPortfolio:%d\n", (fileInfo.Flags & FILEINFO_PORTFOLIO) == FILEINFO_PORTFOLIO); 
  	attachmentCount = fileInfo.nAttachmentCount; 
  	printf("Attachments:%d\n", fileInfo.nAttachmentCount); 
   
  	// Read the properties of the attachments embedded in this file  
  	L_FILEATTACHMENTS* attachments = NULL; 
  	ret = file.ReadFileAttachments(fileName, &attachments, NULL, NULL); 
  	if (ret == ERROR_FEATURE_NOT_SUPPORTED) 
  	{ 
  		// This means the format of the file does not support attachments  
  		printf("WARNING: attachments is not supported by this file format\n"); 
  		return SUCCESS; 
  	} 
  	else if (ret == ERROR_NO_ATTACHMENTS) 
  	{ 
  		// This means the format of the file supports attachments but none were found in the file  
  		printf("WARNING: file has no attachments\n"); 
  		return SUCCESS; 
  	} 
  	else if (ret != SUCCESS) 
  	{ 
  		// Any other error is not expected  
  		printf("ERROR: %d\n", ret); 
  		return ret; 
  	} 
   
  	// Sanity check  
  	assert(attachments->uItemCount == attachmentCount); 
   
  	// Create the output directory if it does not exist  
  	CreateDirectory(outputDir, NULL); 
   
  	LOADFILEOPTION loadFileOption; 
  	file.GetDefaultLoadFileOption(&loadFileOption, sizeof(LOADFILEOPTION)); 
   
  	// Extract the attachments  
  	for (L_UINT attachmentIndex = 0; attachmentIndex < attachments->uItemCount && ret == SUCCESS; attachmentIndex++) 
  	{ 
  		// Get the current attachment  
  		const L_FILEATTACHMENT* attachment = (const L_FILEATTACHMENT*)((const L_UCHAR*)attachments->pItems + (attachments->uItemStructSize * attachmentIndex)); 
   
  		// Get the output file name  
  		L_TCHAR outputFileName[MAX_PATH] = { 0 }; 
  		wcscat_s(outputFileName, _countof(outputFileName), outputDir); 
  		size_t len = wcslen(outputFileName); 
  		if (outputFileName[len - 1] != '\\') 
  		{ 
  			outputFileName[len] = '\\'; 
  			outputFileName[len + 1] = 0; 
  		} 
   
  		wcscat_s(outputFileName, _countof(outputFileName), attachment->pszFileName); 
  		wprintf(L_TEXT("Extracting attachment to output file: %s\n"), outputFileName); 
   
  		// Set the attachment number to extract  
  		loadFileOption.nAttachment = (L_INT)attachment->uAttachmentNumber; 
   
  		// Extract it  
  		ret = file.ExtractAttachment(fileName, NULL, &loadFileOption, NULL, 0, outputFileName, NULL); 
   
  		if (ret == SUCCESS) 
  		{ 
  			// Show information on this attachment. Notice that this might fail if the attachment  
  			// is not a valid image file format.  
  			memset(&fileInfo, 0, sizeof(FILEINFO)); 
  			file.SetFileName(outputFileName); 
  			ret = file.GetInfo(&fileInfo, sizeof(FILEINFO), FILEINFO_TOTALPAGES, NULL); 
  			if (ret == SUCCESS) 
  			{ 
  				printf(" attachment format is %d and has %d pages\n", fileInfo.Format, fileInfo.TotalPages); 
  			} 
  			else 
  			{ 
  				printf(" attachment format could not be obtained, error %d\n", ret); 
  				ret = SUCCESS; // Swallow this error  
  			} 
  		} 
  	} 
   
  	// Free the attachments  
  	file.FreeAttachments(attachments); 
   
  	return ret; 
  }