LEADTOOLS Raster Imaging C DLL Help > Function References > 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
Win32, x64, Linux.
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.
#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 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(MAKE_IMAGE_PATH(TEXT("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(MAKE_IMAGE_PATH(TEXT("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(MAKE_IMAGE_PATH(TEXT("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; }