DevPostDeviceModes

This function returns, and optionally sets job properties.

Syntax

DevPostDeviceModes(hab, pdrivDriverData, pszDriverName,
                   pszDeviceName, pszName, flOptions)

Parameters

hab (HAB) - input

Anchor-block handle.

pdrivDriverData (PDRIVDATA) - in/out

Driver data.

A data area that, on return, contains device data defined by the presentation driver. If the pointer to the area is NULL, this function returns the required size of the data area.

The format of the data is the same as that which occurs within the DEVOPENSTRUC structure, passed on the pdopData parameter of DevOpenDC.

pszDriverName (PSZ) - input

Device-driver name. A string containing the name of the presentation driver; for example, "LASERJET".

pszDeviceName (PSZ) - input

Device-type name.

Null-terminated string in a 32-byte field, identifying the device type; for example, "HP LaserJet IID" (model number). Valid names are defined by device drivers.

Note: This parameter always overrides the data in the szDeviceName field of the DRIVDATA structure, passed in the pdrivDriverData parameter.

pszName (PSZ) - input

Device name.

A name that identifies the device; for example, "PRINTER1".

flOptions (ULONG) - input

Dialog options.

Options that control whether a dialog is displayed.

DPDM_POSTJOBPROP

This function allows the user to set properties for the print job by displaying a dialog and returning the updated job properties. Examples of job properties are paper size, paper orientation, and single-sided or duplex.

The printer is configured in the shell using a dialog provided by the presentation driver. The configuration describes the actual printer setup such as number of paper bins, available paper sizes, and any installed hardware fonts.

Before the job properties dialog is displayed the presentation driver merges any changes in the printer configuration with the data passed in the pdrivDriverData parameter. This allows, for example new paper sizes to be added into the job properties dialog. The parameter pszName can be specified as NULL although this is not recommended because the presentation driver cannot easily find the printer configuration to merge.

It is the responsibility of the application to retrieve and store job properties. An application can choose to store job properties either on a per document or per application basis. The job properties can then be passed into DevOpenDC. Initial (default) job properties can be retrieved using DPDM_QUERYJOBPROP option.

The application cannot tell if the user modified the job properties or just cancelled the dialog. Hence the job properties returned in the pdrivDriverData parameter must always be stored.

The shell allows users to specify default job properties for a printer. The spooler API SplQueryQueue can be used to retrieve these defaults. The spooler automatically adds the default job properties for a printer to any jobs that are submitted without job properties.

DPDM_QUERYJOBPROP

Do not display a dialog. Return the default job properties. These defaults are derived from the defaults for the chosen device; for example, "HP Laserjet IID" and the printer setup specified via the shell printer driver configuration dialog.

Return Code

lDriverCount (LONG) - returns

Size/error indicator.

Value depends on what was passed as the pointer to pdrivDriverData. If NULL was passed, the following values are possible:

• DPDM_ERROR Error
• DPDM_NONE No settable options
• >0 Size in bytes required for pdrivDriverData.

If any other value was passed, the following values are possible:

• DPDM_ERROR Error
• DPDM_NONE No settable options
• DEV_OK OK.

Errors

Possible returns from WinGetLastError:

• PMERR_INV_DRIVER_DATA (0x2066) : Invalid driver data was specified.
• PMERR_DRIVER_NOT_FOUND (0x2026) : The device driver specified with DevPostDeviceModes was not found.
• PMERR_INV_DEVICE_NAME (0x2061) : An invalid devicename parameter was specified with DevPostDeviceModes.
• PMERR_INV_LOGICAL_ADDRESS (0x2097) : An invalid device logical address was specified.

Remarks

An application can first call this function with a NULL data pointer to find out how much storage is needed for the data area. Having allocated the storage, the application can then make the call a second time for the data to be entered. The returned data can then be passed in DevOpenDC as pdrivDriverData within the pdopData parameter.

Calling this function requires the existence of a message queue.

Use SplEnumDevice or SplEnumPrinter with flType set to SPL_PR_DIRECT_DEVICE or SPL_PR_QUEUED_DEVICE to get a list of all the devices.

To get information about a specific device use SplQueryDevice.

Example Code

This example shows how to call DevPostDeviceModes and allocate a new buffer, if necessary, for the larger job properties (DRIVDATA structure).

#define INCL_DEV /* Or use INCL_PM, */
#define INCL_DOS
#include <os2.h>
#include <memory.h>

{
    ULONG         devrc=FALSE;
    HAB           hab;
    PSZ           pszPrinter;
    HDC           hdc=NULL;
    PDRIVDATA     pOldDrivData;
    PDRIVDATA     pNewDrivData=NULL;
    PDEVOPENSTRUC dops;
    LONG          buflen;

/* check size of buffer required for job properties */
    buflen = DevPostDeviceModes( hab,
                                 NULL,
                                 dops->pszDriverName,
                                 dops->pdriv->szDeviceName,
                                 pszPrinter,
                                 DPDM_POSTJOBPROP
                               );

/* return error to caller */
    if (buflen<=0)
        return(buflen);

/* allocate some memory for larger job properties and */
/* return error to caller */

    if (buflen != dops->pdriv->cb)
    {
        if (DosAllocMem((PPVOID)&pNewDrivData,buflen,fALLOC))
            return(DPDM_ERROR);
    }

/* copy over old data so driver can use old job */
/* properties as base for job properties dialog */
    pOldDrivData = dops->pdriv;
    dops->pdriv = pNewDrivData;
    memcpy( (PSZ)pNewDrivData, (PSZ)pOldDrivData, pOldDrivData->cb );

/* display job properties dialog and get updated */
/* job properties from driver */

    devrc = DevPostDeviceModes( hab,
                                dops->pdriv,
                                dops->pszDriverName,
                                dops->pdriv->szDeviceName,
                                pszPrinter,
                                DPDM_POSTJOBPROP
                              );