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

 * 1) include 

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.