The EnumPorts function enumerates the ports that are available for printing on a specified server.

BOOL EnumPorts(
  LPTSTR pName,       // server name
  DWORD Level,        // information level
  LPBYTE pPorts,      // port information buffer
  DWORD cbBuf,        // size of port information buffer
  LPDWORD pcbNeeded,  // bytes received or required
  LPDWORD pcReturned  // number of ports received
);

Parameters

pName

[in] Pointer to a null-terminated string that specifies the name of the server whose printer ports you want to enumerate.

If pName is NULL, the function enumerates the local machine's printer ports.

Level

[in] Specifies the type of information returned in the pPorts buffer. If Level is 1, pPorts receives an array of PORT_INFO_1 structures. If Level is 2, pPorts receives an array of PORT_INFO_2 structures.

pPorts

[out] Pointer to a buffer that receives an array of PORT_INFO_1 or PORT_INFO_2 structures. Each structure contains data that describes an available printer port. The buffer must be large enough to store the strings pointed to by the structure members.

To determine the required buffer size, call EnumPorts with cbBuf set to zero. EnumPorts fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the pcbNeeded parameter returns the size, in bytes, of the buffer required to hold the array of structures and their data.

cbBuf

[in] Specifies the size, in bytes, of the buffer pointed to by pPorts.

pcbNeeded

[out] Pointer to a variable that receives the number of bytes copied to the pPorts buffer. If the buffer is too small, the function fails and the variable receives the number of bytes required.

pcReturned

[out] Pointer to a variable that receives the number of PORT_INFO_1 or PORT_INFO_2 structures returned in the pPorts buffer. This is the number of printer ports that are available on the specified server.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

The EnumPorts function can succeed even if the server specified by pName does not have a printer defined.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.1 and later.
  Windows 95/98/Me: Included in Windows 95 and later.
  Header: Declared in Winspool.h; include Windows.h.
  Library: Use Winspool.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.

See Also

Printing and Print Spooler Overview, Printing and Print Spooler Functions, AddPort, DeletePort, PORT_INFO_1, PORT_INFO_2