GpiQueryElement

This function returns element content data.

Syntax

GpiQueryElement(hps, lOff, lMaxLength, pbData);

Parameters

hps (HPS) - input

Presentation-space handle.

lOff (LONG) - input

Starting byte offset within the element.

lMaxLength (LONG) - input

Maximum length of data that can be returned.

pbData (PBYTE) - output

Element content data.

An area of lMaxLength bytes in which the element content data is to be returned.

Returns

lRetLength (LONG) - returns

Number of bytes returned.

>=0

Actual number of bytes returned

GPI_ALTERROR

Error.

Errors

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)

An invalid presentation-space handle was specified.

PMERR_PS_BUSY (0x20F4)

An attempt was made to access the presentation space from more than one thread simultaneously.

PMERR_INV_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

PMERR_NO_CURRENT_ELEMENT (0x20E5)

An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open element.

PMERR_NOT_IN_RETAIN_MODE (0x20E2)

An attempt was made to issue a segment editing element function that is invalid when the actual drawing mode is not set to retain.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_INV_IN_ELEMENT (0x2089)

An attempt was made to issue a function invalid inside an element bracket.

PMERR_INV_ELEMENT_OFFSET (0x206A)

An invalid off (offset) parameter was specified with GpiQueryElement.

PMERR_NO_CURRENT_SEG (0x20E6)

An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open segment.

Remarks

Returns the element content (or part of the element content) for the element to which the element pointer currently points.

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not draw-and-retain), and a segment bracket is currently in progress.

This function is not valid within an element bracket.

Example Code

This example uses the GpiQueryElement function to retrieve the graphics-order data for an element.

#define INCL_GPISEGEDITING      /* GPI Segment Edit functions   */
#include <os2.h>

HPS  hps;               /* presentation space handle            */
BYTE abElement[512];    /* element data buffer                  */

/* Move pointer to first element in segment. */

GpiSetElementPointer(hps, 1L);
GpiQueryElement(hps,    /* presentation space               */
    0L,                 /* start with first byte in element */
    512L,               /* copy no more than 512 bytes      */
    abElement);         /* buffer to receive data           */

Definition

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

HPS      hps;         /*  Presentation-space handle. */
LONG     lOff;        /*  Starting byte offset within the element. */
LONG     lMaxLength;  /*  Maximum length of data that can be returned. */
PBYTE    pbData;      /*  Element content data. */
LONG     lRetLength;  /*  Number of bytes returned. */

lRetLength = GpiQueryElement(hps, lOff, lMaxLength,
               pbData);