View source for 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 ==
<pre>
#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);
</pre>

== 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.

[[Category:Spl]]