L_ReadFileCommentOffset

#include "l_bitmap.h"

L_INT EXT_FUNCTION L_ReadFileCommentOffset(fd, nOffsetBegin, nBytesToLoad, uType, pComment, uLength, pLoadOptions)

L_INT fd;	/* windows file handle of the file to load */
L_INT32 nOffsetBegin;	/* position of the first byte to load */
L_INT32 nBytesToLoad;	/* size of the embedded image file */
L_UINT uType;	/* type of comment */
L_UCHAR L_FAR * pComment;	/* pointer to your buffer for the comment field */
L_UINT uLength;	/* size of your buffer for the comment field */
pLOADFILEOPTION pLoadOptions;	/* pointer to optional extended load options */

Reads a comment from a file and lets you specify the location of the image data within the file. This enables you to read comments from an image file that is embedded in another file.

Parameter	Description
fd	The Windows file handle of the file to load.
nOffsetBegin	The position, from the beginning of the file, of the first byte to load.
nBytesToLoad	The size of the embedded image file. (The embedded file may be a record within the larger file, and in such cases, this is the record size.)
uType	The type of comment. Refer to Types of File Comments.
pComment	Pointer to your buffer that will hold the comment field, including the terminating NULL. You can pass NULL if you only want to get the length of the field (the return value).
uLength	The size of your buffer that will hold the comment field.
pLoadOptions	Pointer to optional extended load options. Pass NULL to use the default load options.

Returns

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

Comments

Like the L_ReadFileComment function, this function lets you read comments that are already saved in a file header. The only difference between the L_ReadFileComment function and this function is that this function allows you to specify an offset for the image data. For more information refer to the L_SetComment function.

The location of the image is specified as shown in the following simple illustration:

$image\loadoff.gif$

You must open the file and get a Windows file handle before calling this function. Redirected input (specified with L_RedirectIO) is disabled when this function is executing.

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.

Before saving a file, you use the L_SetComment function to specify the comments to be saved.

Note:

More options are available in the LOADFILEOPTION 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

Windows 95 / 98 / Me, Windows 2000 / XP.

See Also

Functions:	L_ReadFileComment, L_SaveFileOffset, L_SetComment, L_ReadFileCommentMemory
Topics:	Raster Image Functions: Maintaining File Comments and Tags
	Types of File Comments

Example

/* The following sample will create a file with an offset and will read a comment from the file it just saved: */
#define COMMENT "I am the artist!"
L_VOID TestReadFileCommentOffset(HWND hWnd)
{
   BITMAPHANDLE Bitmap;
   L_INT nRet; /* Return value */
   HFILE OffsetFile; /* File handle */
   L_INT32 SizeWritten; /* Variable to be updated with the size written */

   /* Load an existing bitmap */
   nRet = L_LoadBitmap(TEXT("eagle.cmp"), &Bitmap, sizeof(BITMAPHANDLE),
                     0, ORDER_BGR, NULL, NULL);
   if(nRet != SUCCESS)
   {
      MessageBox(hWnd, "Load has failed!", "FAILURE", MB_OK);
      return;
   }

   #ifdef UNICODE
      OffsetFile = _wcreat(TEXT("TOFFSET.TST"), 0);
   #else
      OffsetFile = _lcreat("TOFFSET.TST", 0);
   #endif

   /* Write some text in the file -- 29 characters and a terminator */
   _lwrite(OffsetFile, "This is a 29-character string", 30);

   /* set and save a comment into a file with an offset */
   L_SetComment(CMNT_SZARTIST, (L_UCHAR L_FAR*)COMMENT, sizeof(COMMENT));

   /* Save the image file with an offset inside the TOFFSET.TST file */
   nRet = L_SaveFileOffset(OffsetFile, 30, &SizeWritten, &Bitmap, FILE_TIF, 1, 0,
                                 SAVEFILE_FIXEDPALETTE, NULL, NULL, NULL);
   /* Close the file */
   _lclose(OffsetFile);

   /* free the bitmap */
   L_FreeBitmap(&Bitmap);

   /* Notify the user with a message box */
   if (nRet != SUCCESS)
   {
      MessageBox (NULL, TEXT("Error saving file"), TEXT("Error"), MB_OK);
      return;
   }

   /***** Now load the file we just saved ****/
   /* Open the file and get the file handle */
   #ifdef UNICODE
      OffsetFile = _wopen(TEXT("TOFFSET.TST"), OF_READ|OF_SHARE_DENY_WRITE );
   #else
      OffsetFile = _lopen("TOFFSET.TST", OF_READ|OF_SHARE_DENY_WRITE );
   #endif

   /* Get the comment size */
   nRet = L_ReadFileCommentOffset( OffsetFile, 30, SizeWritten,
               CMNT_SZARTIST, NULL, 0, NULL);
   if(nRet > 0)
   {
      /* Allocate a buffer for the comment. Allocate extra byte for string terminator */
      L_UCHAR L_FAR*pComment = (L_UCHAR L_FAR*)malloc(nRet + 1);
      nRet = L_ReadFileCommentOffset(OffsetFile, 30, SizeWritten,
               CMNT_SZARTIST, pComment, nRet + 1, NULL);
      if(nRet > 0)
      {
         /* make sure the string is NULL-terminated */
         pComment[nRet] = 0;
#ifdef UNICODE
         /* convert the string to UNICODE and display it */
#else
         MessageBox(hWnd, (LPSTR)pComment, "SUCCESS", MB_OK);
#endif
      }
      free(pComment);
   }

   /* Close the file */
   _lclose(OffsetFile);

   return;
}