L_SetComment
#include "l_bitmap.h"
L_INT EXT_FUNCTION L_SetComment(uType, pComment, uLength)
|
L_UINT uType; |
/* type of comment */ |
|
/* 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 95 / 98 / Me, Windows 2000 / XP, 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. */
BITMAPHANDLE LeadBitmap; /* Bitmap handle to hold the loaded image */
void TestSaveFunction(void)
{
L_INT i; /* Loop counter */
L_UCHAR TextToSet[80]; /* Comment string that we will set */
L_CHAR L_FAR * pTextToSet = (L_CHAR L_FAR *)TextToSet;
L_TCHAR szMessage[80]; /* MessageBox string */
L_CHAR L_FAR * 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++ )
{
L_SetComment(i, NULL, 0);
}
/* Set the comment that we will save */
pTextToSet = "Susie, the artist";
L_SetComment(CMNT_SZARTIST, (L_UCHAR *)pTextToSet, strlen(pTextToSet) + 1);
/* 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 L_FAR *)GlobalLock( hTextToGet );
/* Get the actual comment */
L_GetComment(CMNT_SZARTIST, (L_UCHAR L_FAR *)pTextToGet, CommentLength);
/* Show the comment that will be saved */
wsprintf (szMessage,TEXT("Saving this comment:\nArtist: %hs"), pTextToGet);
MessageBox (NULL, szMessage, TEXT("Notice"), MB_OK);
/* Free memory */
GlobalFree(hTextToGet);
/* Save the image as an 8-bit TIF file */
L_SaveBitmap(TEXT("TEST.TIF"), &LeadBitmap, FILE_TIF, 8, 0, NULL);
/* Use the return value to get the length of a comment in the file */
CommentLength = L_ReadFileComment(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 L_FAR *)GlobalLock( hTextToGet );
/* Get the actual comment from the file */
L_ReadFileComment(TEXT("TEST.TIF"), CMNT_SZARTIST, (L_UCHAR L_FAR *)pTextToGet,
CommentLength, NULL);
/* Show the comment that was saved in the file */
wsprintf (szMessage, TEXT("File now has this comment:\nArtist: %hs"), pTextToGet);
MessageBox (NULL, szMessage, TEXT("Notice"), MB_OK);
/* Free memory */
GlobalFree(hTextToGet);
return;
}