In This Topic ▼

LFile::ReadTag

Summary

Gets the specified tagged data from a TIFF file. This function is provided to support TIFF tags that you define.

Syntax

#include "ltwrappr.h"

virtual L_INT LFile::ReadTag(uTag, pType, pCount, pLBuffer, pLoadFileOption=NULL)

Parameters

L_UINT16 uTag

Tag to identify the data in the TIFF file. Use the same tag that you specified in the LFileSettings::SetTag function. Examples of registered tags are:

0x8298	Copyright comment
0x8769	General Exif comments
0x8825	Exif GPS comments
0x80A4	Annotation TIFF tag defined as ANNTAG_TIFF.

L_UINT16 * pType

Address of the variable to be updated with the tagged data type. The following are possible values:

Value	Meaning
TAG_BYTE	[1] Byte.
TAG_ASCII	[2] Byte in the range of 0 to 255.
TAG_SBYTE	[6] Byte used as signed number in the range of -128 to +127.
TAG_UNDEFINED	[7] Byte, with application-defined usage.
TAG_SHORT	[3] Two bytes, unsigned.
TAG_SSHORT	[8] Two bytes, signed.
TAG_LONG	[4] Four bytes, unsigned.
TAG_SLONG	[9] Four bytes, signed.
TAG_RATIONAL	[5] Eight bytes, used as a pair of unsigned long integers, where the first number is the numerator and the second is the denominator of a fraction.
TAG_SRATIONAL	[10] Eight bytes, used as a pair of signed long integers, where the first number is the numerator and the second is the denominator of a fraction.
TAG_FLOAT	[11] Four bytes used as a floating point number.
TAG_DOUBLE	[12] Eight bytes used as a double-precision floating point number.
TAG_IFD	[13] 32-bit IFD offset.
TAG_LONG8	[16] Unsigned 64-bit integer (valid only for BigTIFF formats).
TAG_SLONG8	[17] Signed 64-bit integer (valid only for BigTIFF formats).
TAG_IFD8	[18] 64-bit IFD offset (valid only for BigTIFF formats).

L_UINT * pCount

Address of the variable to be updated with the count of data items. The count is based on the tagged data type. For example, if the count is 2 and the data type is TAG_DOUBLE, the required buffer size is 16.

LBuffer * pLBuffer

Pointer to the buffer to be updated with the data. You can pass NULL if you want to use this function's return value to determine the required buffer size.

pLOADFILEOPTION pLoadFileOption

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

Returns

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

Comments

It is often convenient to call this function twice, as follows:

Call the function the first time, specifying NULL in the pData parameter, and using the return value to determine the required size of the buffer.
Allocate the buffer.
Call the function the second time, passing a pointer to your buffer in the pData parameter.

Initially, only TIFF files supported TIFF tags. But the Exif specification provided a mechanism for adding TIFF tags to JPEG files using the APP1 JPEG marker. Additionally, other formats are based on the TIFF specification (CALS, TIFX, KDC) or support Exif metadata (HEIF/HEIC and PNG), so they support TIFF tags. In other words, TIFF tags are supported in file formats other than TIFF.

For general information about TIFF tags, refer to Implementing TIFF Comments and Tags.

Required DLLs and Libraries

LTFIL
File format DLLs
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.

Example

L_INT LFile__ReadTagExample() 
{ 
   L_INT nRet; 
   L_UINT16 LogoPosition = 0x8001; // my private tag  
   L_UINT16 TagType; // tagged data type  
   L_UINT32 TagCount; // count of data items 
   L_INT32 BufferSize; // required size of the buffer  
   LFile   LeadFile; 
   LBuffer LeadBuffer; 
 
   LeadFile.SetFileName(MAKE_IMAGE_PATH(TEXT("clean.tif"))); 
 
   // Get the required buffer size  
   BufferSize = LeadFile.ReadTag( LogoPosition, &TagType, &TagCount, NULL);  
 
   // Allocate and lock the buffer  
   if ((TagType == TAG_SSHORT) && (BufferSize > 0))  
   { 
      nRet = LeadBuffer.Reallocate(BufferSize); 
      if(nRet != SUCCESS) 
         return nRet; 
   } 
   else  
      return FAILURE ; 
 
   // Get the tagged data  
   nRet = LeadFile.ReadTag( LogoPosition, &TagType, &TagCount, &LeadBuffer); 
   if(nRet < 1) 
      return nRet; 
 
   return SUCCESS; 
}