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

 * 1) include 

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); 