GreOpenDC

GreOpenDC creates an output device context (DC). The new device context inherits the current code page of the process that created it.

This function is supported by the graphics engine.

Syntax
GreOpenDC(hdc, ulType, pszToken, cData, pszData, pInstance, lFunction);

Parameters

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


 * When ulType is OD_ context compatible with bit maps that are used with this device context. If this is NULL, compatibility with the display is assumed.


 * ulType (ULONG) - input
 * Type of DC being opened.


 * Type of device context:


 * OD_QUEUED
 * The DC is for a hardcopy device for which output is to be queued by the spooler.


 * OD_DIRECT
 * The DC is for a device for which output is not to be queued by the spooler.


 * OD_INFO
 * This is similar to OD_DIRECT except that it is only used to retrieve information such as font metrics. Drawing can be done to a presentation space associated with such a DC but no output medium is updated.


 * OD_MEMORY
 * The new DC is a memory DC used to contain a bit map. The hdc parameter identifies the device with which the bit map is to be compatible.


 * pszToken (PSZ) - input
 * This parameter is ignored by the graphics engine.


 * cData (LONG) - input
 * Number of elements in the data structure.


 * pszData (PDEVOPENDATA) - input
 * Pointer to data structure.


 * Pointer to DEVOPENDATA structure:


 * pszLogAddress
 * Pointer to logical address, for example, LPT1Q.


 * pszDriverName
 * Pointer to presentation driver name, for example, LASERJET.


 * pdriv
 * Pointer to a DRIVDATA structure:
 * cb
 * Size in bytes of this structure
 * lVersion
 * Version number of the data. Version numbers are defined by the presentation driver.
 * szDeviceName[32]
 * String identifying the device. Valid values are supplied by the presentation driver.
 * abGeneralData
 * General data defined by the presentation driver. This does not contain pointers as they might not be valid when passed to the driver.


 * pszDataType
 * Pointer to a data type of the queued file. Supported data types are:


 * PM_Q_STD
 * PM_Q_RAW
 * User-defined data types can also be supported.


 * pszComment
 * Pointer to a description of the file that can be displayed by the spooler to the user.


 * pszQueueProcName
 * Pointer to name of queue processor.


 * pszQueueProcParams
 * Pointer to a string of queue processor parameters.


 * pszSpoolerParams
 * Pointer to a string of spooler parameters separated by one or more blanks. Valid parameters are:


 * FORM=aaa
 * Identifies the form name for a print job. Multiple names are separated by commas (aaa,bbb,ccc). If this parameter is not present, the current form is used.


 * Form names are defined by the presentation driver. Valid names are those that would be returned from a call to the GreQueryHardcopyCaps handling routine of the driver.


 * PRTY=n
 * Identifies the priority for the print job. The priority can be any value from 1 - 99 (1 is lowest priority). If this parameter is not present, the priority value defaults to 50.


 * pszNetworkParams
 * Pointer to a string of networking parameters, which are used only in a network environment. Their nature is defined by the network application.


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


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

Return Code

 * rc (HDC) - returns
 * Return codes.


 * On completion, the graphics engine returns the handle of the new device context (hdc), or DEV_ERROR if an error occurs.


 * Possible Errors Detected: When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:


 * PMERR_BASE_ERROR
 * PMERR_BITMAP_IS_SELECTED
 * PMERR_COORDINATE_OVERFLOW
 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_EXCEEDS_MAX_SEG_LENGTH
 * PMERR_HBITMAP_BUSY
 * PMERR_HDC_BUSY
 * PMERR_HUGE_FONTS_NOT_SUPPORTED
 * PMERR_INSUFFICIENT_MEMORY
 * PMERR_INV_BACKGROUND_COL_ATTR
 * PMERR_INV_BACKGROUND_MIX_ATTR
 * PMERR_INV_BITMAP_DIMENSION
 * PMERR_INV_CHAR_DIRECTION_ATTR
 * PMERR_INV_CHAR_MODE_ATTR
 * PMERR_INV_CODEPAGE
 * PMERR_INV_COLOR_ATTR
 * PMERR_INV_COORD_SPACE
 * PMERR_INV_COORDINATE
 * PMERR_INV_DC_DATA
 * PMERR_INV_DC_TYPE
 * PMERR_INV_DRIVER_NAME
 * PMERR_INV_HBITMAP
 * PMERR_INV_HDC
 * PMERR_INV_HRGN
 * PMERR_INV_ID
 * PMERR_INV_IN_AREA
 * PMERR_INV_IN_PATH
 * PMERR_INV_INFO_TABLE
 * PMERR_INV_LENGTH_OR_COUNT
 * PMERR_INV_LINE_TYPE_ATTR
 * PMERR_INV_MIX_ATTR
 * PMERR_INV_PATTERN_REF_PT_ATTR
 * PMERR_INV_PATTERN_SET_ATTR
 * PMERR_INV_PATTERN_SET_FONT
 * PMERR_INV_RECT
 * PMERR_INV_REGION_CONTROL
 * PMERR_INV_SCAN_START


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

Remarks
Subsequent calls to DosSetCp do not alter the code page of an existing DC. Default VIO and KBD code pages are always in the last code page set by any application process.

When this function is called for the first time, the graphics engine performs the following sequence:

DosLoadModule("NEWDRIVER", &hDriver) /****************************************************/                 /* Load the presentation driver DLL file. */                 /****************************************************/

DosGetProcAddr(hDriver, "OS2_PM_DRV_ENABLE", &Enable) /****************************************************/                 /* Find the presentation driver's Enable function. */                 /* See OS2_PM_DRV_ENABLE. */                 /****************************************************/

/****************************************************/                 /* The presentation driver must:                    */ /*  Save the addresses of the engine simulations   */ /*  Overwrite the dispatch table, as necessary     */ /*  Hook the ExitList for the calling process      */ /****************************************************/
 * Enable(FillLogicalDeviceBlock, &DispatchTable)

hPhysDev=*Enable(FillPhysicalDeviceBlock, pDevOpenStructure) /****************************************************/                 /* Create the physical device block. */                 /****************************************************/

pInstance=*Enable(EnableDeviceContext, hdc, Type, hPhysDev) /****************************************************/                 /* The presentation driver must create an instance  */ /* data structure for the DC. */                 /****************************************************/

/****************************************************/                 /* The presentation driver must inform the system   */ /* that the DC is open and ready to receive output. */                 /****************************************************/
 * Enable(CompleteOpenDC, hdc, pInstance)

For subsequent calls to GreOpenDC for the same DC, the graphics engine calls Enable (EnableDeviceContext) to create a new instance for the DC and then calls Enable (CompleteOpenDC). When GreOpenDC is called for the same DC by a different process, the graphics engine calls DosLoadModule to load the presentation driver. It then calls Enable (FillLogicalDeviceBlock), Enable (EnableDeviceContext), and Enable (CompleteOpenDC).

Sample Code

 * 1) define INCL_GRE_DCS
 * 2) include 

HDC            hdc;        /*  Device context handle. */ ULONG          ulType;     /*  Type of DC being opened. */ PSZ            pszToken;   /*  This parameter is ignored by the graphics engine. */ LONG           cData;      /*  Number of elements in the data structure. */ PDEVOPENDATA   pszData;    /*  Pointer to data structure. */ PVOID          pInstance;  /*  Pointer to instance data. */ ULONG          lFunction;  /*  High-order WORD=flags; low-order WORD=NGreOpenDC. */ HDC            rc;         /*  Return codes. */

rc = GreOpenDC(hdc, ulType, pszToken, cData, pszData, pInstance, lFunction); 