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

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

HAB       hab;            /*  Anchor-block handle. */
PSZ       pszDriverName;  /*  Fully-qualified name of the file containing the presentation driver. */
PLONG     pldn;           /*  Maximum number of device names and descriptions that can be returned. */
PSTR32    aDeviceName;    /*  Device-name array. */
PSTR64    aDeviceDesc;    /*  Device-description array. */
PLONG     pldt;           /*  Maximum number of data types that can be returned. */
PSTR16    aDataType;      /*  Data type array. */
BOOL      rc;             /*  Success indicator. */

rc = DevQueryDeviceNames(hab, pszDriverName,
       pldn, aDeviceName, aDeviceDesc, pldt,
       aDataType);

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

Related Functions

• DevQueryCaps
• DevQueryHardCopyCaps