FaxEnumPorts

The FaxEnumPorts function enumerates all fax devices currently attached to the fax server to which the client has connected. The function returns detailed information for each fax port to the fax client application.

BOOL WINAPI FaxEnumPorts(
  HANDLE FaxHandle,          // handle to the fax server
  PFAX_PORT_INFO *PortInfo,  // buffer to receive array of port data
  LPDWORD PortsReturned      // number of fax port structures returned
);

Parameters

FaxHandle

[in] Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.

PortInfo

[out] Pointer to the address of a buffer to receive an array of FAX_PORT_INFO structures. Each structure describes one fax port. The data includes, among other items, the permanent line identifier, and the current status and capability of the port. For information about memory allocation, see the following Remarks section.

PortsReturned

[out] Pointer to a DWORD variable to receive the number of FAX_PORT_INFO structures the function returns in the PortInfo parameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can return one of the following errors.

Remarks

A fax administration application typically calls the FaxEnumPorts function to display fax devices for administrative or querying purposes.

To obtain a handle to a fax port, call the FaxOpenPort function. Use the handle when you call the following functions:

• FaxSetPort to change the configuration of the port
• FaxEnumRoutingMethods to retrieve information about the fax routing methods associated with a fax device

For more information, see Device and Configuration Management and Fax Device Management.

The FaxEnumPorts function allocates the memory required for the FAX_PORT_INFO buffer array pointed to by the PortInfo parameter. An application must call the FaxFreeBuffer function to deallocate the resources associated with this parameter. For more information, see Freeing Fax Resources.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable with BackOffice Small Business Server.
  Header: Declared in Winfax.h.
  Library: Included as a resource in Winfax.dll.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FaxFreeBuffer, FaxGetPort, FaxSetPort, FaxOpenPort, FAX_PORT_INFO