SplPdEnumPort

SplPdEnumPort enumerates the port names and port descriptions that this port driver can manipulate.

Syntax

SplPdEnumPort(hab, pBuf, cbBuf, pulReturned, pulTotal, pcbNeeded)

Parameters

hab (HAB) - input

The handle to the anchor block.

pBuf (PVOID) - input

The pointer to the buffer of data structures.

cbBuf (ULONG) - input

The size of the buffer in bytes.

pulReturned (PULONG) - input

The number of port entries returned.

pulTotal (PULONG) - input

The total number of port entries.

pcbNeeded (PULONG) - input

The size of the buffer required for all data.

Returns

rc (APIERR) - returns

Return codes.

This handling routine returns the following errors:

ERROR_INSUFFICIENT_BUFFER
ERROR_MORE_DATA
NO_ERROR

The buffer, on return, consists of an array of the following data structure:

typedef struct _PORTNAMES {
        PSZ pszPortName;
        PSZ pszPortDesc;
} PORTNAMES;

Sample

#include <os2.h>

HAB       hab;          /*  The handle to the anchor block. */
PVOID     pBuf;         /*  The pointer to the buffer of data structures. */
ULONG     cbBuf;        /*  The size of the buffer in bytes. */
PULONG    pulReturned;  /*  The number of port entries returned. */
PULONG    pulTotal;     /*  The total number of port entries. */
PULONG    pcbNeeded;    /*  The size of the buffer required for all data. */
APIERR    rc;           /*  Return codes. */

rc = SplPdEnumPort(hab, pBuf, cbBuf, pulReturned,
       pulTotal, pcbNeeded);

Remarks

If the buffer is too small to hold even one data structure, the error code ERROR_INSUFFICIENT_BUFFER, is returned. If there is more data, ERROR_MORE_DATA is returned and cbRequired gives the size of buffer required to get all the data.

The Workplace Shell is the expected caller of this function and determines which ports to install in OS2SYS.INI. The port descriptions are used to label the icon for each port. The Workplace Shell does not allow the installation of ports that can be serviced by more than one port driver. The first port installed is used. The Workplace Shell does not display other ports for installation. If another port is required, the first port must be uninstalled.