Platform SDK: Fax Services

FAX_DEV_STATUS

The FAX_DEV_STATUS structure contains status and identification information about an individual active fax operation.

typedef struct _FAX_DEV_STATUS {
    DWORD   SizeOfStruct;  // structure size, in bytes 
    DWORD   StatusId;      // fax status identifier 
    DWORD   StringId;      // string resource identifier 
    DWORD   PageCount;     // current page number; 1-relative 
    LPWSTR  CSI;           // pointer to remote identifier 
    LPWSTR  CallerId;      // pointer to calling device 
    LPWSTR  RoutingInfo;   // pointer to routing string for fax
    DWORD   ErrorCode;     // Win32 error code 
    DWORD   Reserved[3];   // must be zero 
} FAX_DEV_STATUS, *PFAX_DEV_STATUS;

Members

SizeOfStruct

Specifies the size, in bytes, of the FAX_STATUS structure. Before responding to the FaxDevReportStatus function, the fax service provider must set this member to sizeof(FAX_STATUS).

StatusId

Specifies a fax status code or value. This can be a predefined fax status code (shown following), one of the TAPI LINEERR_ Constants error codes, or a value that the fax service provider defines. If the status identifier is provider-defined, the fax service provider must also supply a value for the StringId member. Following are the predefined fax status codes.

Value	Meaning
FS_INITIALIZING	The call is initializing.
FS_DIALING	The fax service provider is dialing digits for the call.
FS_TRANSMITTING	The fax service provider is transmitting the fax document.
FS_RECEIVING	The fax service provider is receiving the fax document.
FS_COMPLETED	The fax transmission call is complete.
FS_LINE_UNAVAILABLE	The fax service provider cannot complete the call because the device is not available.
FS_BUSY	The fax service provider received a busy signal.
FS_NO_ANSWER	The fax service provider cannot complete the call because the receiving device does not answer.
FS_BAD_ADDRESS	The fax service provider cannot complete the call because the destination address is invalid.
FS_NO_DIAL_TONE	The fax service provider cannot complete the call because it does not detect a dial tone.
FS_DISCONNECTED	The call was disconnected by the receiving device.
FS_FATAL_ERROR	A fatal error has occurred. For more information, see the description of the StringId member.
FS_NOT_FAX_CALL	The call is a data call or a voice call.
FS_CALL_DELAYED	The fax service provider received a busy signal multiple times. The provider cannot retry because dialing restrictions exist. (Some countries restrict the number of retries when a number is busy.)
FS_HANDLED	The fax service processed the fax job but it has not yet assigned the job to a fax service provider.
FS_USER_ABORT	The fax service provider has canceled the transmission. Cancellation can result from a call to the FaxDevAbortOperation function. Service providers can also provide a user interface for cancellation of fax transmissions.
FS_ANSWERED	The fax service provider answered the inbound call but is not yet receiving the call. This status indicates to the fax service that the call may not be a fax call.
FS_CALL_BLACKLISTED	The fax service provider cannot complete the call because the telephone number is blocked or reserved, for example, a call to 911 or another emergency number.

StringId

Specifies a string resource identifier for the StatusId member if the StatusId is provider-defined. The fax service loads the string from the fax service provider's image. If StatusId contains a provider-defined status code or value, this member is required.

PageCount

Specifies the number of the page in the fax transmission that the fax service provider is receiving. The page count is relative to one.

CSI

Pointer to a null-terminated Unicode character string that specifies an identifier of the remote fax device that is connected with the current call to either the FaxDevReceive or FaxDevSend function.

If the operation is sending a fax, the identifier specifies the called station identifier (CSID) of the remote device; if the operation is receiving a fax, the identifier specifies the transmitting station identifier (TSID) of the remote device.

CallerId

Pointer to a null-terminated Unicode character string that identifies the calling device that sent the received fax document. This string can include the telephone number of the calling device.

RoutingInfo

Pointer to a null-terminated Unicode character string that specifies the routing string for an inbound fax. The string must be of the form:

Canonical-Phone-Number[|Additional-Routing-Info]

where Canonical-Phone-Number is defined in Canonical Addresses in the TAPI documentation; and the format of Additional-Routing-Info is defined by the recommendation of the standards body of the International Telecommunication Union (ITU) from Study Group 8 (SG8). This is currently known as "T.Routing."

For direct inward dialing (DID) routing, append the specific DID digits to the telephone number prefix. The DID address must be the canonical telephone number that corresponds to the fully qualified telephone number that the sender would have dialed.

If there is additional routing information, for example, subaddressing or Dual Tone Multiple Frequency (DTMF tones), separate it from the canonical telephone number by a vertical bar character as indicated in the TAPI specification. You can specify multiple recipients.

For more information, see Dialable Addresses and Canonical Addresses in the TAPI documentation.

ErrorCode

Specifies one of the Win32 Error Codes that the fax service provider should use to report an error that occurs. The fax service provider should set this value to NO_ERROR when it is running and after a fax job completes normally.

Reserved[3]

This member is reserved for future use by Microsoft. It must be set to zero.

Remarks

The fax service provider must either set all of the members of the FAX_DEV_STATUS structure to the status information for the active fax operation, or set them to zero.

The fax service allocates the memory for the strings pointed to by the CSI, CallerId and RoutingInfo members. The size of the memory the service allocates is equal to sizeof(FAX_DEV_STATUS) + FAXDEVREPORTSTATUS_SIZE. The fax service provider must place the strings in the block of memory that immediately follows the FAX_DEV_STATUS structure. The CSI, CallerId, and RoutingInfo members must point to the location of the strings in the memory block.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxdev.h.

FAX_DEV_STATUS

Members

Remarks

Requirements

See Also