GreQueryHardcopyCaps

GreQueryHardcopyCaps stores information about the hardcopy capabilities of the device in the buffer addressed by pInfo. The information is stored as a sequence of one or more HCINFO structures defining the hardcopy capabilities for one or more form codes.

This function must be supported by hardcopy drivers. It is not required for display drivers. GreQueryHardcopyCaps is called by the function DevQueryHardcopyCaps.

Simulation support

This function is mandatory for hardcopy drivers, but may simply return a DEVESC_NOTIMPLEMENTED code. For other drivers, it is simulated by a handling routine in the graphics engine.

Syntax

GreQueryHardcopyCaps(hdc, lStart, cCount, pInfo, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

lStart (LONG) - input

Index.

Index to the required starting HCINFO structure. A value of 0 identifies the HCINFO for the first form.

cCount (LONG) - input

Number of forms.

Number of structures to be returned in the buffer. A value of 0 requests the handling routine to set the return code to the number of forms that the driver supports.

pInfo (PHCINFO) - input

Pointer to buffer for returned form data.

A pointer to the buffer for the returned data. The data is returned as a set of one or more HCINFO structures. When pInfo is not equal to NULL and lStart is greater than or equal to the number of form codes that the hardcopy drivers supports, the hardcopy driver should return 0 without modifying the memory block pointed to by pInfo.

• szFormname[32] Character string containing the name of the form
• cx Width (left-to-right) in millimeters
• cy Height (top-to-bottom) in millimeters
• xLeftClip Left clip limit in millimeters
• yBottomClip Bottom clip limit in millimeters
• xRightClip Right clip limit in millimeters
• yTopClip Top clip limit in millimeters
• xPels Number of pels between left and right clip limits
• yPels Number of pels between bottom and top clip limits
• flAttributes Attributes describing the availability of the form:

HCAPS_SELECTABLE

The form is installed on the printer as given by the printer properties dialog (see OS2_PM_DRV_DEVMODE). It is available from an alternate form source without operator intervention. If the form does not have this bit set and is used (if the user selects it) in a print job, a "forms mismatch" error is generated by the printer object.

HCAPS_CURRENT

The form is the one currently selected by pdriv (the job properties), a field in OS2_DRV_ENABLE (FillPhysicalDeviceBlock) (see FillPhysicalDeviceBlock). The HCAPS_SELECTABLE bit is not necessarily set. This is also the form size returned by GreQueryDeviceCaps capabilities of CAPS_WIDTH and CAPS_HEIGHT.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreQueryHardcopyCaps.

Return Code

rc (LONG) - returns

Return Code.

The value returned by the handling routine depends on the initial value of cCount. If cCount=0, return the total number of form codes that the presentation driver supports. For any other value, return the number of HCINFO structures that were transferred to the buffer.

Possible Errors Detected: When an error is detected, the handling routine must return DQHC_ERROR and call WinSetErrorInfo to post the condition. An error code for conditions that the handling routine is expected to check is:

• PMERR_INV_LENGTH_OR_COUNT

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

Remarks

For presentation drivers that support more than one form code with the relevant data held in a structure of HCINFO structures, the parameters lStart and cCount identify the starting point in the main structure and the number of HCINFO structures to be stored.

It is usual for this function to be issued twice (initially with a value of 0 in cCount) to return the number of forms available. Storage can be allocated and the function called again with cCount set to the number of forms for which information is required.

Declaration

#define INCL_GRE_DEVICE
#include <os2.h>

HDC        hdc;        /*  Device context handle. */
LONG       lStart;     /*  Index. */
LONG       cCount;     /*  Number of forms. */
PHCINFO    pInfo;      /*  Pointer to buffer for returned form data. */
PVOID      pInstance;  /*  Pointer to instance data. */
ULONG      lFunction;  /*  High-order WORD=flags; low-order WORD=NGreQueryHardcopyCaps. */
LONG       rc;         /*  Return Code. */

rc = GreQueryHardcopyCaps(hdc, lStart, cCount,
       pInfo, pInstance, lFunction);