GreQueryRealColors

GreQueryRealColors stores, in the array addressed by pArray, the RGB values of the distinct colors available on the currently associated device.

This function must be supported by the presentation driver. GreQueryRealColors is called by GpiQueryRealColors in response to an application requesting the currently available colors for the device context.


 * Simulation support: None. This function is mandatory for all drivers.

Syntax
GreQueryRealColors(hdc, flOptions, lStart, cArray, pArray, pInstance, lFunction);

Parameters

 * hdc (HDC) - input : Device context handle.


 * flOptions (ULONG) - input : Options flag.


 * Valid options are:


 * LCOLOPT_REALIZED: If set, the information is required when the logical color table (if any) is realized. When this flag is not set, the information is required when the logical color table is not realized.
 * LCOLOPT_INDEX: If set, the handling routine must return the index for each RGB value. Other flags are reserved and must be 0.


 * lStart (LONG) - input : Ordinal number of the first color required.


 * Typically, this is 0 to start the sequence. This value does not necessarily bear any relationship to the color index because the order in which the colors are returned is not defined.


 * cArray (LONG) - input : Number of elements available in the array.


 * pArray (PLONG) - input : Pointer to array in which data is returned.


 * When LCOLOPT_INDEX is set, this is an array of alternating color indexes and values (in the order, index1, value1, index2, value2 and so on). If there is a color table, colors that are not in the table but are available on the device, have a special index of QLCT_NOTLOADED. In RGB mode, the RGB value is returned in the color indexes.


 * When LCOLOPT_INDEX is not set, this is an array of color values. Each value is the same as those defined for GreCreateLogColorTable.


 * pInstance (PVOID) - input : Pointer to instance data.


 * lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGreQueryRealColors.

Returns

 * rc (LONG) - returns : Return Code.

On completion, the handling routine must return the number of colors returned in the array (cColors), or GPI_ALTERROR if an error occurred

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:


 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_INV_COLOR_OPTIONS
 * PMERR_INV_COLOR_START_INDEX
 * PMERR_INV_HDC
 * PMERR_INV_LENGTH_OR_COUNT

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

 * 1) define INCL_GRE_COLORTABLE
 * 2) include 

HDC     hdc;        /*  Device context handle. */ ULONG   flOptions;  /*  Options flag. */ LONG    lStart;     /*  Ordinal number of the first color required. */ LONG    cArray;     /*  Number of elements available in the array. */ PLONG   pArray;     /*  Pointer to array in which data is returned. */ PVOID   pInstance;  /*  Pointer to instance data. */ ULONG   lFunction;  /*  High-order WORD=flags; low-order WORD=NGreQueryRealColors. */ LONG    rc;         /*  Return Code. */

rc = GreQueryRealColors(hdc, flOptions, lStart,      cArray, pArray, pInstance, lFunction);