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

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

• GpiCopyMetaFile
• GpiDeleteMetaFile
• GpiLoadMetaFile
• GpiQueryMetaFileLength
• GpiSaveMetaFile
• GpiSetMetaFileBits