In This Topic ▼

L_WriteFileTagMemory

Summary

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

Syntax

#include "l_bitmap.h"

L_LTFIL_API L_INT L_WriteFileTagMemory(phHandle, puSize, pSaveOptions)

Parameters

L_HANDLE * phHandle

Pointer to the memory handle that will be updated with a new memory handle that contains the updated file in memory. You must pass an existing file. This pointer should point to a valid memory handle (*phHandle!=NULL).If you pass a valid memory handle, the old handle will become invalid and a new handle created. The new handle may have the same value as the old handle, however, this is not guaranteed.

L_SIZE_T* puSize

Address of a variable, which contains the size of the file in memory, and which the function updates to give you the new size of the file.

pSAVEFILEOPTION 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

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

Comments

To use this function, do the following:

Declare a memory handle.
Declare a long integer (L_UINT32) variable for the file-size. You can then pass its address in this function, which will update its value with the new size of the file in memory.
Use GlobalAlloc to allocate storage for your file in memory.
Fill the memory with your file data and unlock the memory.
Pass the address of the memory handle to this function, which may re-allocate the memory if increasing the size of the file is necessary.
Call this function to write tags into the existing file in the specified memory handle.

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 L_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 EXIF, TIFF, and PNG files.

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

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).

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

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.

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.

Example

L_INT WriteFileTagMemoryExample() 
{ 
   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; 
   L_HANDLE hFile=NULL; 
   L_HANDLE hFileInMemory=NULL; 
   L_SIZE_T nLength=0; 
   L_UCHAR* pData=NULL; 
   DWORD wReadBytes; 
   DWORD wWrittenBytes; 
 
   /* get a file from disk, into a memory handle */ 
   hFile = CreateFile(MAKE_IMAGE_PATH(TEXT("CLEAN.TIF")), GENERIC_ALL, 0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0); 
   if( NULL != hFile ) 
   { 
      /* calculate length of data and load it from the file */ 
      SetFilePointer(hFile, 0, 0, FILE_END); 
      nLength = SetFilePointer(hFile, 0, NULL, FILE_CURRENT) ; 
      SetFilePointer(hFile, 0, 0, FILE_BEGIN); 
      hFileInMemory = GlobalAlloc( GMEM_FIXED, nLength ); 
      pData = (L_UCHAR*)GlobalLock( hFileInMemory ); 
      if( NULL == pData ) 
      { 
         CloseHandle( hFile ); 
         return -1; /* no memory */  
      } 
      /* read in the file */ 
      if(!ReadFile (hFile, pData, (DWORD)nLength, &wReadBytes, NULL)) 
      { 
         GlobalUnlock( hFileInMemory ); 
         GlobalFree( hFileInMemory ); 
         CloseHandle( hFile ); 
         return -1; /* failed while reading */  
      } 
      CloseHandle( hFile ); 
      hFile = NULL; 
 
      /* Set the tag data to be saved */ 
      nRet = L_SetTag(LogoPosition, TagType, TagCount, pTagData); 
      if(nRet < SUCCESS) 
      { 
         GlobalFree(hFileInMemory); 
         return nRet; 
      } 
 
      nRet = L_GetDefaultSaveFileOption(&SaveFileOption, sizeof(SAVEFILEOPTION)); 
      if(nRet != SUCCESS) 
      { 
         GlobalFree(hFileInMemory); 
         return nRet; 
      } 
 
      SaveFileOption.PageNumber = 1; 
 
      /* Save the file with the tag. */ 
      nRet = L_WriteFileTagMemory(&hFileInMemory, &nLength, &SaveFileOption); 
 
      /* Dump the file back to disk */ 
      if(nRet == SUCCESS) 
      { 
         hFile = CreateFile(MAKE_IMAGE_PATH(TEXT("TEST_updated.TIF")), GENERIC_ALL, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, 0); 
         if( hFile ) 
         { 
            pData = (L_UCHAR*)GlobalLock( hFileInMemory ); 
            if( !WriteFile(hFile, pData,(DWORD)(sizeof( L_UCHAR ) * nLength), &wWrittenBytes, NULL) ) 
               nRet = -1; /* failed to write data */ 
            GlobalUnlock( hFileInMemory ); 
            CloseHandle( hFile ); 
         } 
      } 
 
      GlobalFree(hFileInMemory); 
 
      if(nRet != SUCCESS) 
         return nRet; 
 
      /* Clear the tag from memory */ 
      nRet = L_SetTag(0, 0, 0, NULL); 
 
      return SUCCESS; 
   } 
   else 
      return -1; 
}