FAX_PORT_INFOA structure (winfax.h)
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.
Syntax
typedef struct _FAX_PORT_INFOA {
DWORD SizeOfStruct;
DWORD DeviceId;
DWORD State;
DWORD Flags;
DWORD Rings;
DWORD Priority;
LPCSTR DeviceName;
LPCSTR Tsid;
LPCSTR Csid;
} FAX_PORT_INFOA, *PFAX_PORT_INFOA;
Members
SizeOfStruct
Type: DWORD
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
Type: DWORD
Specifies a DWORD variable that indicates the permanent line identifier for the fax device of interest.
State
Type: DWORD
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.
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/regions 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
Type: DWORD
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.
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. Note that you cannot set a device to be virtual. When calling FaxGetPort, the FAX_PORT_INFO flag's FPF_VIRTUAL value indicates whether the device is virtual. When calling FaxSetPort, the service will only relate to the FPF_RECEIVE and FPF_SEND values.
Rings
Type: DWORD
Specifies a DWORD variable that indicates the number of times an incoming fax call should ring before the specified device answers the call. Possible values are from 0 to 99 inclusive. This value is ignored unless the FPF_RECEIVE port capability bit flag is set.
Priority
Type: DWORD
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
Type: LPCTSTR
Pointer to a constant null-terminated character string that specifies the name of the fax device of interest.
Tsid
Type: LPCTSTR
Pointer to a constant null-terminated character string that specifies the TSID. This identifier is usually a telephone number. Only printable characters such as English letters, numeric symbols, and punctuation marks (ASCII range 0x20 to 0x7F) can be used in a TSID.
Csid
Type: LPCTSTR
Pointer to a constant null-terminated character string that specifies the called station identifier (CSID). This identifier is usually a telephone number. Only printable characters such as English letters, numeric symbols, and punctuation marks (ASCII range 0x20 to 0x7F) can be used in a CSID.
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.
Note
The winfax.h header defines FAX_PORT_INFO as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Header | winfax.h |
See also
Fax Service Client API Structures