Platform SDK: Fax Services

FAX_PORT_INFO

The FAX_PORT_INFO structure describes one fax port. The data includes, among other items, a device identifier, the port's name and current status, and station identifiers.

typedef struct _FAX_PORT_INFO {
  DWORD   SizeOfStruct;  // structure size, in bytes
  DWORD   DeviceId;      // line identifier of the device
  DWORD   State;         // fax device status
  DWORD   Flags;         // set of fax port capability bit flags
  DWORD   Rings;         // rings before answer
  DWORD   Priority;      // priority for device selection
  LPCTSTR DeviceName;    // pointer to device name
  LPCTSTR Tsid;          // pointer to 
                         // transmitting station identifier
  LPCTSTR Csid;          // pointer to called station identifier
} FAX_PORT_INFO, *PFAX_PORT_INFO;

Members

SizeOfStruct

Specifies the size, in bytes, of the FAX_PORT_INFO structure. The calling application should ensure that this member is set to sizeof(FAX_PORT_INFO) before it calls the FaxSetPort function.

DeviceId

Specifies a DWORD variable that indicates the permanent line identifier for the fax device of interest.

State

Specifies a DWORD variable that is a fax device status code or value. This member can be one of the predefined device status codes shown following.

Value	Meaning
FPS_DIALING	The device is dialing a fax number.
FPS_SENDING	The device is sending a fax document.
FPS_RECEIVING	The device is receiving a fax document.
FPS_COMPLETED	The device has completed sending or receiving a fax transmission.
FPS_UNAVAILABLE	The device is not available because it is in use by another application.
FPS_BUSY	The device has encountered a busy signal.
FPS_NO_ANSWER	The receiving device did not answer the call.
FPS_BAD_ADDRESS	The device dialed an invalid fax number.
FPS_NO_DIAL_TONE	The sending device cannot complete the call because it does not detect a dial tone.
FPS_DISCONNECTED	The fax call was disconnected by the sender or the caller.
FPS_FATAL_ERROR	The device encountered a fatal protocol error.
FPS_NOT_FAX_CALL	The device has received a data call or a voice call.
FPS_CALL_DELAYED	The device delayed a fax call because the sending device received a busy signal multiple times. The device cannot retry the call because dialing restrictions exist. (Some countries restrict the number of retry attempts when a number is busy.)
FPS_CALL_BLACKLISTED	The device could not complete a call because the telephone number was blocked or reserved; emergency numbers such as 911 are blocked.
FPS_INITIALIZING	The device is initializing a call.
FPS_OFFLINE	The device is offline and unavailable.
FPS_RINGING	The device is ringing.
FPS_AVAILABLE	The device is available.
FPS_ABORTING	The device is aborting a fax job.
FPS_ROUTING	The device is routing a received fax document.
FPS_ANSWERED	The device answered a new call.
FPS_HANDLED	The fax service processed the outbound fax document; the fax service provider will transmit the document.

Flags

Specifies a DWORD variable that is a set of bit flags that specify the capability of the fax port. This member can be a combination of the following values.

Value	Meaning
FPF_RECEIVE	The device can receive faxes.
FPF_SEND	The device can send faxes.
FPF_VIRTUAL	The device is a virtual fax device. For more information, see Virtual Fax Devices.

Rings

Specifies a DWORD variable that indicates the number of times an incoming fax call should ring before the specified device answers the call. This value is ignored unless the FPF_RECEIVE port capability bit flag is set.

Priority

Specifies a DWORD variable that determines the relative order in which available fax devices send outgoing transmissions. Valid values for this member are 1 through n, where n is the value of the PortsReturned parameter returned by a call to the FaxEnumPorts function.

When the fax server initiates an outgoing fax transmission, it attempts to select the device with the highest priority and FPF_SEND port capability. If that device is not available, the server selects the next available device that follows in rank order, and so on. The value of the Priority member has no effect on incoming transmissions.

DeviceName

Pointer to a constant null-terminated character string that specifies the name of the fax device of interest.

Tsid

Pointer to a constant null-terminated character string that specifies the transmitting station identifier. This identifier is usually a telephone number.

Csid

Pointer to a constant null-terminated character string that specifies the called station identifier. This identifier is usually a telephone number.

Remarks

A fax client application passes the FAX_PORT_INFO structure in a call to the FaxSetPort function to modify the configuration of the fax port of interest.

If an application calls the FaxEnumPorts function to enumerate all the fax devices currently attached to a fax server, the function returns an array of FAX_PORT_INFO structures. Each structure describes one device in detail. If an application calls the FaxGetPort function to query one device, that function returns information about the device in one FAX_PORT_INFO structure. For more information, see Fax Ports and Fax Device Management.

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.
  Unicode: Declared as Unicode and ANSI structures.

FAX_PORT_INFO

Members

Remarks

Requirements

See Also