In This Topic ▼

L_LoadMarkers

Summary

Loads metadata markers (COM and APPn) into a handle.

Syntax

#include "l_bitmap.h"

L_LTFIL_API L_INT L_LoadMarkers(pszFilename, phMarkers, uFlags)

Parameters

L_TCHAR * pszFilename

Character string that contains the name of the file from which to load the collection of metadata markers.

L_VOID ** phMarkers

Pointer to a variable to be updated with a handle to the collection of metadata markers. This handle is allocated by this function.

L_UINT uFlags

Reserved for future use. Pass 0.

Returns

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

Comments

The handle referenced by the phMarkers parameter is allocated by this function. This handle can then be used to save the metadata information. For Exif files, this metadata handle will contain ALL the Exif and GPS comments, stored in APP1. It will also contain the audio information stored in APP2.

The marker data in APPn markers will typically start with a string identifying the type of data present in the marker. For example, the APP1 Exif marker will usually start with the 4-byte string "Exif" followed by 2 bytes of 0x00. That is because there can be many types of data stored in an APP1 marker. This simple convention is a good way of distinguishing between an Exif APP1 marker and another type of APP1 marker.

The markers can also be retrieved by calling L_TransformFile. Each retrieved marker is passed to the TRANSFORMFILECALLBACK function. There is one important difference between the markers passed to TRANSFORMFILECALLBACK and those loaded with L_LoadMarkers:

TRANSFORMFILECALLBACK receives ALL the markers (metadata and image-related markers).

L_LoadMarkers loads only the metadata markers.

When the marker collection handle is no longer needed, use the L_FreeMarkers function to free it.

To save the collection of metadata markers referenced by the handle in phMarkers to a file, pass this handle to the L_SetMarkers function.

Important!

The comments set with L_SetComment will OVERRIDE any comments contained in the metadata markers. For example, if the original file had an author of "Steve" and you call:

L\_SetComment(CMNT\_SZAUTHOR, TEXT("John"), 5);

the next time you save a file, the author will be John (not Steve). However, all the comments that have not been set will be taken from the metadata handle.

You can call L_MarkersSupported to find out if a certain file format supports markers.

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 LoadMarkersExample(HWND      hWnd, 
                                        L_TCHAR * pszSrc, 
                                        L_TCHAR * pszDest) 
{ 
   HANDLE hMarkers; 
   L_INT nRet; 
 
   FILEINFO info; 
   memset(&info, 0, sizeof (FILEINFO)); 
   info.uStructSize = sizeof(FILEINFO); 
 
   nRet = L_FileInfo(pszSrc, &info, sizeof(FILEINFO), 0, NULL); 
   if (nRet != SUCCESS) 
      return nRet; 
 
   if (!L_MarkersSupported(info.Format)) 
      return ERROR_FEATURE_NOT_SUPPORTED; 
 
   nRet = L_LoadMarkers(pszSrc, &hMarkers, 0); 
   if(nRet != SUCCESS) 
   { 
      MessageBox(hWnd, TEXT("Error loading markers"), TEXT("FAILURE"), MB_OK); 
      return nRet; 
   } 
 
   L_SetMarkers(hMarkers, 0); 
   nRet = L_FreeMarkers(hMarkers); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   return L_WriteFileMetaData(pszDest, METADATA_ALL, NULL); 
}