OS2_PM_DRV_DEVICENAMES

OS2_PM_DRV_DEVICENAMES must be compiled to run at Ring 3 (privilege level 3).

The device names entry point is exported as OS2_PM_DRV_DEVICENAMES by the presentation driver to support the DevQueryDeviceNames function at the API level. This call returns the device names and device descriptions supported by this driver.

Syntax

OS2_PM_DRV_DEVICENAMES(pszDriverName,pcNames, paDeviceName, paDeviceDesc,
      pcDataTypes, paDataType, lReserved1, lReserved2);

Parameters

pszDriverName (PSZ) - input

A pointer to a string containing the name of the device driver, such as LaserJet.

pcNames (PLONG) - input

A pointer to count of fields, cNames, in DeviceName and DeviceDesc arrays.

paDeviceName (PSTR32) - input

A pointer to DeviceName array, CHAR cNames[32]. Device names are NULL-terminated strings such as 'HP LaserJet II'.

paDeviceDesc (PSTR64) - input

A pointer to DeviceDesc array, CHAR cNames[64]. Device descriptions are NULL-terminated strings such as 'HP LaserJet II'.

pcDataTypes (PLONG) - input

A pointer to count of fields, cDataTypes in DataType array.

paDataType (PSZ) - input

A pointer to DataType array, CHAR cDataTypes[16].

lReserved1 (ULONG) - input

Reserved.

lReserved2 (ULONG) - input

Reserved.

Return Code

rc (LONG) - returns

Return codes.

The handling routine in the presentation driver returns a LONG integer. Valid values are:

• -1 Successful
• 0 Error

Note

The system expects the successful and error return codes from OS2_PM_DRV_DEVICENAMES to be the opposite of those from OS2_PM_DRV_DEVMODE and the Enable subfunctions.

Remarks

Applications such as the Presentation Manager Print Object call DevQueryDeviceNames to determine the device names and descriptions and the data types that the presentation driver supports. Hardcopy drivers must contain a handling routine for OS2_PM_DRV_DEVICENAMES.

Applications usually call this function twice. First, it is called with a NULL value for cNames and cDataTypes to query the number of names and data types. Second, after allocating the arrays, the application calls this function with valid values to get the data. If the value of cNames is NULL at the location addressed by pcNames, the handling routine must update cNames to the actual count of names. If cNames has a valid value, the routine must write device names and device descriptions into the arrays addressed by paDeviceName and paDeviceDesc. Similarly, for cDataTypes, the handling routine either writes a valid value into cDataTypes or writes data-type names into the array addressed by paDataType. Notice that when writing to an array, the routine does not write past the end of the array as defined by the associated count.

Example Code

#include <os2.h>

PSZ       pszDriverName;
PLONG     pcNames;
PSTR32    paDeviceName;
PSTR64    paDeviceDesc;
PLONG     pcDataTypes;
PSZ       paDataType;
ULONG     lReserved1;
ULONG     lReserved2;
LONG      rc;             /*  Return codes. */

rc = OS2_PM_DRV_DEVICENAMES(pszDriverName,
       pcNames, paDeviceName, paDeviceDesc,
       pcDataTypes, paDataType, lReserved1,
       lReserved2);