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
	JPEG and LEAD FileComments
	Tiff FileComments
	Exif FileComments
	Gif FileComments
	Dicom FileComments
	FlashPix FileComments
	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
File format DLLs

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_FileInfo, L_FileInfoMemory, L_ReadFileComment, L_ReadFileCommentMemory, L_GetPCDResolution, L_SetPCDResolution, L_GetWMFResolution, L_SetWMFResolution, L_SetLoadInfoCallback, L_GetComment, L_ReadFileCommentOffset, L_ReadFileComments
Topics:	Raster Image Functions: Input and Output
	Loading and Saving Images

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(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;
}