DevQueryDeviceNames

This function causes a presentation driver to return the names, descriptions, and data types of the devices it supports.

Syntax
DevQueryDeviceNames(hab, pszDriverName, pldn, aDeviceName, aDeviceDesc, pldt, aDataType)

Parameters

 * hab (HAB) - input: Anchor-block handle.
 * pszDriverName (PSZ) - input: Fully-qualified name of the file containing the presentation driver.
 * The file-name extension is DRV.


 * pldn (PLONG) - in/out: Maximum number of device names and descriptions that can be returned.
 * On input, it must be greater or equal to 0. pldn can have the following values:
 * Zero:The number of device names and descriptions supported is returned; aDeviceName and aDeviceDesc are not updated.
 * Nonzero:pldn is updated to the number returned in aDeviceName and aDeviceDesc; aDeviceName and aDeviceDesc are updated.


 * aDeviceName (PSTR32) - output: Device-name array.
 * An array of null-terminated strings, each element of which identifies a particular device. Valid names are defined by presentation drivers.


 * aDeviceDesc (PSTR64) - output: Device-description array.
 * An array of null-terminated strings, each element of which is a description of a particular device. Valid descriptions are defined by presentation drivers.


 * pldt (PLONG) - in/out: Maximum number of data types that can be returned.
 * On input, it must be greater or equal to 0. pldt can have the following values:
 * Zero:The number of data types supported is returned, and aDataType is not updated.
 * Nonzero:pldt is updated to the number returned, and aDataType is updated.


 * aDataType (PSTR16) - output: Data type array.
 * An array of null-terminated strings, each element of which identifies a data type. Valid data types are defined by presentation drivers.

Return Code

 * rc (BOOL) - returns: Success indicator.
 * TRUE Successful completion
 * FALSE Error occurred.
 * Errors:Possible returns from WinGetLastError:
 * PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.

Remarks
An application can first call this function with pldn and pldt set to 0 to find how much storage is needed for the data areas. Having allocated the storage, the application calls the function a second time for the data to be entered.

"HP Laserjet IID" is an example of a device name, "Hewlett-Packard Laserjet IID" is an example of a device description, and "PM_Q_STD" is an example of a data type.

Example Code
This example uses DevQueryDeviceNames to return the names, descriptions, and data types of supported devices for a presentation driver. The first call to DevQueryDeviceNames determines the number of names, description, and data types available; after allocating the arrays, the second call actually returns the information in the arrays. 
 * 1) define INCL_DEV               /* Device Function definitions  */
 * 2) define INCL_DOSMEMMGR         /* DOS Memory Manager Functions */
 * 3) include 

BOOL fSuccess;         /* success indicator                    */ HAB  hab;              /* Anchor-block handle                  */ LONG pldn = 0L;        /* number of device names/descriptions  */ LONG pldt = 0L;        /* number of data types                 */ PSTR32 aDeviceName;    /* array of device names                */ PSTR64 aDeviceDesc;    /* array of device descriptions         */ PSTR16 aDataType;      /* array of data types                  */

/* query number of supported names/descriptions/data types (pldn & pldt both 0) */ fSuccess = DevQueryDeviceNames(hab, "IBM4201.DRV", &pldn,                              aDeviceName, aDeviceDesc, &pldt,                               aDataType);

if (fSuccess) {  /* allocate arrays */ DosAllocMem((VOID *)aDeviceName, (ULONG)pldn*sizeof(STR32),              PAG_COMMIT | PAG_WRITE); DosAllocMem((VOID *)aDeviceDesc, (ULONG)pldn*sizeof(STR64),              PAG_COMMIT | PAG_WRITE); DosAllocMem((VOID *)aDataType, (ULONG)pldt*sizeof(STR16),              PAG_COMMIT | PAG_WRITE);

/* query supported device information */ fSuccess = DevQueryDeviceNames(hab, "IBM4201.DRV", &pldn,                                 aDeviceName, aDeviceDesc, &pldt,                                  aDataType); } 

Related Functions

 * DevQueryCaps
 * DevQueryHardCopyCaps