L_ReadFileTag

#include "l_bitmap.h"

L_LTFIL_API L_INT L_ReadFileTag(pFile, uTag, pType, pCount, pData, pLoadOptions)

L_TCHAR * pFile;	/* character string containing the input file name */
L_UINT16 uTag;	/* tag to identify the data in the TIFF file */
L_UINT16* pType;	/* address of the variable for the data type */
L_UINT* pCount;	/* address of the variable for the count */
L_VOID* pData;	/* pointer to the buffer for the data */
pLOADFILEOPTION pLoadOptions;	/* pointer to optional extended load options */

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

Parameter	Description
pFile	Character string containing the input file name.
uTag	Tag to identify the data in the TIFF file. Use the same tag that you specified in the L_SetTag function. Examples of registered tags are:
	Value	Meaning
	0x8298	Copyright comment
	0x8769	General Exif comments
	0x8825	Exif GPS comments
	0x80A4	Annotation TIFF tag defined as ANNTAG_TIFF.
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.
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.
pData	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.
pLoadOptions	Pointer to optional extended load options. Pass NULL to use the default load options.

Returns

>0	Length of the tagged data, in bytes.
<= 0	An error occurred. Refer to Return Codes.

Comments

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

1.	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.
2.	Allocate the buffer.
3.	Call the function the second time, passing a pointer to your buffer in the pData parameter.

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

This function will read the data for a tag whose data size is greater than 4 bytes. In certain situations, you might want to read the data offset instead of the data itself. This is useful in order to read tags contained in a MakerNote tag. Use L_ReadFileTags to read the tag's data offset.

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, Mobile.

See Also

Functions:	L_SetTag, L_GetTag, L_ReadFileTagMemory, L_DeleteTag, L_ReadFileTags
Topics:	Implementing TIFF Comments and Tags

Example

This example uses L_ReadFileTag to read a tag for the position of a company logo on an image. It reads the tag from the TIFF file that is created in the example for L_SetTag.

 L_INT ReadFileTagExample(L_VOID)
{
   L_INT nRet;
   L_TCHAR msgbuf[80];              /* buffer for the message string */
   L_UINT16 FillOrder = 0x010A;     /* Fill Order tag                */
   L_UINT16 TagType;                /* tagged data type              */
   L_UINT32 TagCount;               /* count of data items           */
   L_VOID * pTagData;               /* pointer to the buffer containing the data */
   HGLOBAL hBuf;                    /* handle to the buffer          */
   L_INT32 BufferSize;              /* required size of the buffer   */

   /* Get the required buffer size */
   BufferSize = L_ReadFileTag(MAKE_IMAGE_PATH(TEXT("OCR1.TIF")), FillOrder, &TagType, &TagCount, NULL, NULL);

   /* Allocate and lock the buffer */
   if ((TagType == TAG_SHORT) && (BufferSize > 0)) 
   {
    hBuf = GlobalAlloc(GMEM_MOVEABLE, BufferSize);
    pTagData = GlobalLock( hBuf );
   }
   else   
   {
      return BufferSize; 
   }

   /* Get the tagged data */
   nRet = L_ReadFileTag(MAKE_IMAGE_PATH(TEXT("OCR1.TIF")), FillOrder, &TagType, &TagCount, pTagData, NULL);
   if(nRet <= 0)
      return nRet;

   /* Display a message showing the data */
   if ((TagType == TAG_SHORT) && (TagCount == 1)) 
   {
    wsprintf(msgbuf, TEXT("FillOrder = 0x%02X"), (short)*(L_INT*)pTagData);
    MessageBox (NULL, msgbuf, TEXT("Fill Order"), MB_OK);   
   }

   /* Free memory that we no longer need */
   GlobalUnlock (hBuf);
   GlobalFree(hBuf); 

   return SUCCESS;
}