2.2.7 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 subscriber identifiers.

A fax client application passes the FAX_PORT_INFO in a call to the FAX_SetPort (section 3.1.4.1.88) function to modify the configuration of the fax port of interest.

This structure is also used as an input argument for the FaxObs_SetPort (section 3.1.4.2.17) method.

 typedef struct {
   DWORD SizeOfStruct;
   DWORD DeviceId;
   DWORD State;
   DWORD Flags;
   DWORD Rings;
   DWORD Priority;
   [string] LPCWSTR DeviceName;
   [string] LPCWSTR Tsid;
   [string] LPCWSTR Csid;
 } FAX_PORT_INFO,
  *PFAX_PORT_INFO;

SizeOfStruct: A DWORD ([MS-DTYP] section 2.2.9) that holds the size of the structure, in bytes. This value MUST be 36 bytes or 48 bytes. When filled in on a 32-bit implementation, this value SHOULD be 36 bytes. When filled in on a 64-bit implementation, this value SHOULD be 48 bytes.

DeviceId: A DWORD variable that holds the line identifier for the fax device (port) of interest.

State: A DWORD variable that holds a fax device status code or value. This member can be one of the following predefined device status codes.

Value/code	Meaning
FPS_DIALING 0x20000001	The device is dialing a fax number.
FPS_SENDING 0x20000002	The device is sending a fax document.
FPS_RECEIVING 0x20000004	The device is receiving a fax document.
FPS_COMPLETED 0x20000008	The device completed sending or receiving a fax transmission.
FPS_HANDLED 0x20000010	The fax service processed the outbound fax document; the fax service provider (FSP) will transmit the fax document.
FPS_UNAVAILABLE 0x20000020	The device is not available because it is in use by another application.
FPS_BUSY 0x20000040	The device encountered a busy signal.
FPS_NO_ANSWER 0x20000080	The receiving device did not answer the call.
FPS_BAD_ADDRESS 0x20000100	The device dialed an invalid fax number.
FPS_NO_DIAL_TONE 0x20000200	The sending device cannot complete the call because it does not detect a dial tone.
FPS_DISCONNECTED 0x20000400	The fax call was disconnected by the sender or the caller.
FPS_FATAL_ERROR 0x20000800	The device has encountered a fatal protocol error.
FPS_NOT_FAX_CALL 0x20001000	The device received a call that was a data call or a voice call.
FPS_CALL_DELAYED 0x20002000	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 and regions restrict the number of retry attempts when a number is busy).
FPS_CALL_BLACKLISTED 0x20004000	The device could not complete a call because the telephone number was blocked or reserved; emergency numbers such as 911 are blocked.
FPS_INITIALIZING 0x20008000	The device is initializing a call.
FPS_OFFLINE 0x20010000	The device is offline and unavailable.
FPS_RINGING 0x20020000	The device is ringing.
FPS_AVAILABLE 0x20100000	The device is available.
FPS_ABORTING 0x20200000	The device is aborting a fax job.
FPS_ROUTING 0x20400000	The device is routing a received fax document.
FPS_ANSWERED 0x20800000	The device answered a new call.

Flags: A DWORD variable that holds a set of bit flags that specify the capability of the fax port. This member can be a bitwise OR combination of the following flag values.

Value/code	Meaning
FPF_RECEIVE 0x00000001	The device can receive faxes.
FPF_SEND 0x00000002	The device can send faxes.
FPF_VIRTUAL 0x00000004	The device is a virtual fax device. Note that the implementer cannot set a device to be virtual. When FAX_GetPort (section 3.1.4.1.51) is called, the FAX_PORT_INFO flag's FPF_VIRTUAL value indicates whether the device is virtual. When FAX_SetPort (section 3.1.4.1.88) is called, the service will only relate to the FPF_RECEIVE and FPF_SEND values.

Rings: A DWORD variable that holds the number of times an incoming fax call rings before the specified device answers the call. Values can be from 0 to 99 inclusive. This value SHOULD be ignored unless the FPF_RECEIVE port capability bit flag is set.

Priority: A DWORD variable that holds the priority that determines the relative order in which available fax devices send outgoing transmissions. Values for this member can be 1 through n, where n is the value of the PortsReturned parameter returned by a call to the FAX_EnumPorts (section 3.1.4.1.28) 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: A pointer to a constant null-terminated character string that holds the name of the fax device of interest.

Tsid: A pointer to a constant null-terminated character string that holds the transmitting subscriber identifier (TSID). This identifier is usually a telephone number. Only English letters, numeric symbols, and punctuation marks (ASCII range 0x20 to 0x7F) can be used in a TSID.

Csid: A pointer to a constant null-terminated character string that holds the called subscriber identifier (CSID). This identifier is usually a telephone number. Only English letters, numeric symbols, and punctuation marks (ASCII range 0x20 to 0x7F) can be used in a CSID.