LFile::WriteTag

#include "ltwrappr.h"

virtual L_INT LFile::WriteTag(pSaveOptions)

/* pointer to optional extended save options */

Writes tags to a file or changes existing tags in a file.

Parameter	Description
pSaveOptions	Pointer to optional extended save options. Pass NULL to use the default save options. pSaveOptions.PageNumber indicates the page on which to write the tags. Note that an error code will be returned if the page does not exist.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

This function writes tags into an existing file or changes tags in an existing file.

This function will write all the tags that have been set using LFileSettings::SetTag. There must be at least one tag set for this function to work. If no tags have been set, an error will be returned by this function.

This function works only with TIFF files.

Note: Use this function carefully. LEADTOOLS will not restrict the tags that you write. If you write bad tags, the file might become corrupted. Consult the TIFF documentation for a list of predefined tags. It is recommended that you write only the user-defined tags (the tags between 0x8000 and 0xFFFF).

When you add or remove comments or tags, the comments and tags array at the end of the TIFF/Exif image file is re-written. When you modify existing comments or tags, the new value is added to the file and the IFD is modified as necessary. In all of these cases, there is no image recompression.

See the TIFF documentation for a complete list of the TIFF tags and types.

Some restrictions apply to this function if you use an IFD to indicate to which page to write the tag. See the Loading and Saving Large TIFF Files topic for more information.

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.

See Also

Functions:	LFile::DeleteTag, LFileSettings::SetTag, LFileSettings::GetTag, SAVEFILEOPTION, LFile::SaveFile, LFile::ReadTag, Class Members
Topics:	Raster Image Functions: Input and Output
	Loading and Saving Images

Example

L_INT LFile__WriteTagExample()
{
   L_INT nRet;
   L_UINT16 LogoPosition = 0x8001; /* my private tag */
   L_UINT16 TagType = TAG_SHORT; /* tagged data type */
   L_UINT32 TagCount = 4; /* count of data items */
   L_INT16 TagData[] = {5, 5, 24, 37};
   L_VOID * pTagData = &TagData; /* pointer to the buffer containing the data */
   SAVEFILEOPTION SaveFileOption;
   LFileSettings MyFileSettings;
   LFile MyFile;
   /* Set the tag data to be saved */
   nRet = MyFileSettings.SetTag(LogoPosition, TagType, TagCount, pTagData);
   if(nRet != SUCCESS)
      return nRet;
   MyFile.GetDefaultSaveFileOption (&SaveFileOption, sizeof(SAVEFILEOPTION));
   SaveFileOption.PageNumber = 1;
   MyFile.SetFileName(TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\TEST.TIF"));
   /* Save the file with the tag. Note that TEST.TIF must exist and contain at least one page! */
   nRet = MyFile.WriteTag(&SaveFileOption);
   if(nRet != SUCCESS)
      return nRet;
   /* Clear the tag from memory */
   nRet = MyFileSettings.SetTag(0, 0, 0, NULL);
   if(nRet != SUCCESS)
      return nRet;
   return SUCCESS;
}