L_SetComment
#include "l_bitmap.h"
L_LTFIL_API L_INT L_SetComment(uType, pComment, uLength)
|
L_UINT uType; |
/* type of comment */ |
|
L_UCHAR* pComment; |
/* pointer to the buffer for the comment field */ |
|
L_UINT uLength; |
/* size of the buffer that contains the comment field */ |
Specifies a field to be saved as a comment in a file.
|
Parameter |
Description |
|
|
uType |
The type of comment. Valid values are: |
|
|
|
Value |
Meaning |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
CMNT_LAST |
Last defined number for comments. To clear all fields, you can use the type constant as a loop counter. The first constant is 0 and the last is CMNT_LAST. |
|
pComment |
Pointer to the buffer containing the comment field that you want to set. You can pass NULL to clear the current field. |
|
|
uLength |
The size of your buffer that contains the comment field. (If the buffer is actually a single string, this is the string length + 1.) |
|
Returns
|
>=0 |
Length of the comment field. |
|
< 0 |
An error occurred. Refer to Return Codes. |
Comments
Some file formats can contain comments, and some cannot, and each file format has its own set of comment types. When you save a file, the comments, which LEADTOOLS maintains in a global array, are saved in the file. The index into the array (specified using a constant) determines the type of comment, as described in Types of File Comments.
|
Note: |
When LEADTOOLS saves a TIFF/Exif image that contains comments and tags, the comments and tags will be written first, followed by the image data. This order is not configurable. |
This function works with related functions. For example, consider the following possible sequence:
|
1. |
Use the L_SetComment function to specify any of the comments that you want to save in a file header. |
|
2. |
Use the L_GetComment function to let the user review the comments before they are saved. |
|
3. |
Save one or more files that you want to include the currently specified comments. You can use any LEADTOOLS function that saves a file. The file format can be any that includes a TIFF header, such as CCITT or TIFF (but not JTIF). |
|
4. |
Use the L_SetComment function with a NULL buffer and 0 length to clear each of the comment fields. You must call the this function once for each specified field. To clear all fields, you can use the type constant as a loop counter. The first constant (specified in the uType parameter) is 0 and the last is CMNT_LAST. |
|
5. |
Use the L_ReadFileComment function to let the user review the comments that have been saved in a file. |
|
Note: |
More options are available in the SAVEFILEOPTION structure. |
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
Windows 2000 / XP/Vista, Windows CE.
See Also
Example
This example demonstrates all of the functions related to comments for TIFF files. It clears all comments, sets a new comment, gets the comment from memory, saves a file with the comment, then gets the comment from the file.
L_INT SetCommentExample(pBITMAPHANDLE LeadBitmap)
{
L_INT nRet;
L_INT i; /* Loop counter */
L_CHAR szMessage[80]; /* MessageBox string */
L_CHAR * pTextToGet; /* Comment string that we will get */
HGLOBAL hTextToGet; /* Handle for memory management */
L_INT CommentLength; /* Length of the comment string that we will get */
/* Clear the current comments */
for(i = 0 ; i < CMNT_LAST ; i++ )
{
nRet = L_SetComment(i, NULL, 0);
}
/* Set the comment that we will save */
nRet = L_SetComment(CMNT_SZARTIST, (L_UCHAR*)"Susie, the artist", (L_UINT)strlen("Susie, the artist") + 1);
if(nRet < SUCCESS)
return nRet;
/* Use the return value to get the length of a comment */
CommentLength = L_GetComment(CMNT_SZARTIST, NULL, 0);
/* Allocate and lock a zero-filled buffer for the comment */
hTextToGet = GlobalAlloc(GPTR, CommentLength);
pTextToGet = (L_CHAR *)GlobalLock( hTextToGet );
/* Get the actual comment */
nRet = L_GetComment(CMNT_SZARTIST, (L_UCHAR *)pTextToGet, CommentLength);
if(nRet < SUCCESS)
return nRet;
/* Show the comment that will be saved */
sprintf_s(szMessage,("Saving this comment:\nArtist: %s"), pTextToGet);
MessageBoxA (NULL, szMessage, ("Notice"), MB_OK);
/* Free memory */
GlobalFree(hTextToGet);
/* Save the image as an 8-bit TIF file */
nRet = L_SaveBitmap(TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\TEST.TIF"), LeadBitmap, FILE_TIF, 8, 0, NULL);
if(nRet != SUCCESS)
return nRet;
/* Use the return value to get the length of a comment in the file */
CommentLength = L_ReadFileComment(TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\TEST.TIF"), CMNT_SZARTIST, NULL, 0, NULL);
/* Allocate and lock a zero-filled buffer for the comment */
hTextToGet = GlobalAlloc(GPTR, CommentLength);
pTextToGet = (L_CHAR *)GlobalLock( hTextToGet );
/* Get the actual comment from the file */
nRet = L_ReadFileComment(TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\TEST.TIF"), CMNT_SZARTIST, (L_UCHAR *)pTextToGet, CommentLength, NULL);
if(nRet < SUCCESS)
return nRet;
/* Show the comment that was saved in the file */
sprintf_s(szMessage, ("File now has this comment:\nArtist: %s"), pTextToGet);
MessageBoxA (NULL, szMessage, ("Notice"), MB_OK);
/* Free memory */
GlobalFree(hTextToGet);
return SUCCESS;
}