LEADTOOLS Raster Imaging C DLL Help > Function References > 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
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_SetTag, L_GetTag, L_ReadFileTagMemory, L_DeleteTag, L_ReadFileTags |
Topics: |
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.
#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 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; }