GpiQueryMetaFileBits

This function transfers a metafile to application storage.

Syntax

GpiQueryMetaFileBits(hmf, lOffset, lLength, pbData)

Parameters

hmf (HMF) - input: Memory-metafile handle.

lOffset (LONG) - input: Byte offset.; Offset into the metafile data from which the transfer must start. This is useful in instances where the metafile data is too long to fit into a single application buffer. It must be greater or equal to 0.

lLength (LONG) - input: Length in bytes of the metafile data to copy.; It must be greater or equal to 0.

pbData (PBYTE) - output: Metafile data.; Address in application storage into which the metafile data is copied.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion
FALSE: Error occurred.

Remarks

The total length of a metafile can be found from the data returned by GpiQueryMetaFileLength. This function allows an application to retrieve the data in units of a manageable size.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HMF (0x207E): An invalid metafile handle was specified.
PMERR_INV_METAFILE_LENGTH (0x209E): An invalid length parameter was specified with GpiSetMetaFileBits or GpiQueryMetaFileBits.
PMERR_INV_METAFILE_OFFSET (0x209F): An invalid length parameter was specified with GpiSetMetaFileBits or GpiQueryMetaFileBits.
PMERR_METAFILE_IN_USE (0x20D9): An attempt has been made to access a metafile that is in use by another thread.
PMERR_TOO_MANY_METAFILES_IN_USE (0x2106): The maximum number of metafiles allowed for a given process was exceeded.

Example Code

#define INCL_GPIMETAFILES /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HMF     hmf;     /* Memory-metafile handle. */
LONG    lOffset; /* Byte offset. */
LONG    lLength; /* Length in bytes of the metafile data to copy. */
PBYTE   pbData;  /* Metafile data. */
BOOL    rc;      /* Success indicator. */

rc = GpiQueryMetaFileBits(hmf, lOffset, lLength, pbData);

This example uses the GpiQueryMetaFileBits function to retrieve the graphics-order data from the specified metafile. The GpiQueryMetaFileLength function returns the length of the metafile.

#define INCL_GPIMETAFILES /* Metafile functions */
#define INCL_DOSMEMMGR /* DOS Memory Manager Functions */
#include <os2.h>

HPS hps; /* presentation space handle */
HMF hmf; /* metafile handle */
LONG cBytes; /* metafile length */
LONG off; /* metafile byte offset */
PBYTE pbBuffer; /* metafile data buffer */

hmf = GpiLoadMetaFile(hps, "sample.met");
cBytes = GpiQueryMetaFileLength(hmf); /* gets length of metafile */

/* Allocate the buffer for the metafile data. */
DosAllocMem((VOID *)pbBuffer, (ULONG)cBytes, PAG_COMMIT | PAG_READ | PAG_WRITE);

GpiQueryMetaFileBits(hmf, /* handle of metafile */
                      off, /* offset of next byte to retrieve */
                      cBytes, /* length of data */
                      pbBuffer); /* buffer to receive metafile data */

Related Functions