GpiQuerySegmentPriority

This function returns the identifier of the named segment that is chained immediately before or after a specified reference segment.

Syntax

GpiQuerySegmentPriority(hps, lRefSegid, lOrder)

Parameters

hps (HPS) - input

Presentation-space handle.

lRefSegid (LONG) - input

Reference-segment identifier.

lOrder (LONG) - input

Segment higher or lower.

Shows whether a segment identifier of a higher or lower priority than identified in the lRefSegid parameter is to be returned. Possible values are:

LOWER_PRI: Return the next segment with a lower priority than lRefSegid. If lRefSegid =0, query the identifier of the segment with the lowest priority.

HIGHER_PRI: Return the next segment with a higher priority than lRefSegid. If lRefSegid =0, query the identifier of the segment with the highest priority.

Return Value

lSegid (LONG) - returns

Segment identifier.

The identifier of the segment that is immediately before or after that specified in the lRefSegid parameter:

>0 : Segment identifier.

0 : The segment specified in the lRefSegid parameter is either the lowest-priority segment (when lOrder = LOWER_PRI) or the highest-priority segment (when lOrder = HIGHER_PRI).

GPI_ALTERROR : Error.

Remarks

The segment that is chained before the specified segment, is considered to have a lower priority than the specified segment; similarly, the segment that is chained after the specified segment, is considered to have a higher priority than the specified segment. Unnamed segments (with an identifier of zero) are ignored.

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_SEG_NAME (0x20C8)

An invalid segment identifier was specified.

PMERR_INV_ORDERING_PARM (0x20AB)

An invalid order parameter was specified with GpiSetSegmentPriority.

PMERR_SEG_NOT_CHAINED (0x20FF)

An attempt was made to issue GpiDrawFrom, GpiCorrelateFrom or GpiQuerySegmentPriority for a segment that was not chained.

PMERR_SEG_NOT_FOUND (0x2100)

The specified segment identifier did not exist.

PMERR_INV_MICROPS_FUNCTION (0x20A1)

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

Example Code

This function returns the identifier of the named segment that is chained immediately before or after a specified reference segment.

#define INCL_GPISEGMENTS
#include <OS2.H>

HPS hps; /* Presentation-space */
/* handle. */
LONG lSegid; /* Segment identifier */
LONG lRefSegid; /* Reference-segment */
/* identifier. */
LONG lOrder; /* Shows whether a */
/* segment identifier of a */
/* higher or lower priority */
/* than identified in the */
/* lRefSegid parameter is */
/* to be returned. */

lOrder = HIGHER_PRI; /* Return the next */
/* segment with a higher */
/* priority than */
/* lRefSegid. If */
/* lRefSegid=0, query */
/* the identifier of the */
/* segment with the */
/* highest priority. */

lRefSegid = 0; /* find the segment with the highest */
/* priority. */

lSegid = GpiQuerySegmentPriority(hps,
    lRefSegid,
    lOrder);

Related Functions

• GpiSetSegmentPriority