Platform SDK: Fax Services

FaxGetPort

The FaxGetPort function returns information for a specified fax port to a fax client application. The data includes, among other items, the permanent line identifier, the current status and capability of the port, and the transmitting and called station identifiers.

The application must call the FaxOpenPort function and specify the PORT_OPEN_QUERY access level before calling the FaxGetPort function.

BOOL WINAPI FaxGetPort(
  HANDLE FaxPortHandle,     // fax port handle
  PFAX_PORT_INFO *PortInfo  // structure to receive port data
);

Parameters

FaxPortHandle
[in] Specifies a fax port handle returned by a call to the FaxOpenPort function.
PortInfo
[out] Pointer to the address of a buffer to receive a FAX_PORT_INFO structure. The structure describes one fax port. For information about memory allocation, see the following Remarks section.

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.

Error code Description
ERROR_INVALID_PARAMETER One or both of the PortInfo or FaxPortHandle parameters are NULL.
ERROR_ACCESS_DENIED Access is denied. FAX_PORT_QUERY access is required.
ERROR_NOT_ENOUGH_MEMORY An error occurred during memory allocation.

Remarks

A fax administration application typically calls the FaxGetPort function to query a device associated with the fax server.

To obtain a valid port handle to specify in the FaxPortHandle parameter, call the FaxOpenPort function.

The FaxGetPort function allocates the memory required for the FAX_PORT_INFO buffer 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 Fax Device Management and 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, FaxOpenPort, FaxFreeBuffer, FaxSetPort, FaxEnumPorts, FAX_PORT_INFO