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.
#define INCL_DEV /* Device Function definitions */
#define INCL_DOSMEMMGR /* DOS Memory Manager Functions */
#include <os2.h>
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);
}