Platform SDK: Fax Services

FAX_DEVICE_STATUS

The FAX_DEVICE_STATUS structure contains information about the current status of a fax device. In addition to the status, the structure also includes data on whether the device is currently sending or receiving a fax transmission, device and station identifiers, sender and recipient names, and routing information.

typedef struct _FAX_DEVICE_STATUS {
  DWORD      SizeOfStruct;   //structure size, in bytes 
  LPCTSTR    CallerId;       //pointer to calling device
  LPCTSTR    Csid;           //pointer to called station identifier
  DWORD      CurrentPage;    //current page number; 1-relative 
  DWORD      DeviceId;       //line identifier 
                             //of the receiving device
  LPCTSTR    DeviceName;     //pointer to device name
  LPCTSTR    DocumentName;   //pointer to document name to display
  DWORD      JobType;        //job type (send/receive)
  LPCTSTR    PhoneNumber;    //pointer to fax number for
                             //outgoing fax
  LPCTSTR    RoutingString;  //pointer to routing string
  LPCTSTR    SenderName;     //pointer to sender name
  LPCTSTR    RecipientName;  //pointer to recipient name
  DWORD      Size;           //size, in bytes, of document
  FILETIME   StartTime;      //transmission start time
  DWORD      Status;         //status code for device
  LPCTSTR    StatusString;   //must be NULL
  FILETIME   SubmittedTime;  //time of fax submission
  DWORD      TotalPages;     //total pages in transmission
  LPCTSTR    Tsid;           //pointer to transmitting
                             //station identifier
  LPCTSTR    UserName;       //user who submitted job
} FAX_DEVICE_STATUS, *PFAX_DEVICE_STATUS;

Members

SizeOfStruct

Specifies the size, in bytes, of the FAX_DEVICE_STATUS structure. The fax service sets this member to sizeof(FAX_DEVICE_STATUS).

CallerId

If the JobType member is equal to the JT_RECEIVE job type, CallerId is a pointer to a null-terminated character string that identifies the calling device that sent the active fax document. This string can include the telephone number of the calling device.

Csid

Pointer to a constant null-terminated character string that specifies the called station identifier of the device.

CurrentPage

Specifies a DWORD variable that indicates the number of the page in the fax transmission that the fax device is currently sending or receiving. The page count is relative to one.

DeviceId

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

DeviceName

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

DocumentName

Pointer to a constant null-terminated character string to associate with the fax document that the device is currently sending or receiving. This is the user-friendly name that appears in the print spooler.

JobType

Specifies a DWORD variable that identifies the type of fax job that is currently active on the device. This member can be one of the following job types.

Value	Meaning
JT_SEND	The fax device is sending a fax document.
JT_RECEIVE	The fax device is receiving a fax document.
JT_UNKNOWN	The fax device is in an unknown or idle state.

PhoneNumber

If the JobType member is equal to the JT_SEND job type, PhoneNumber is a pointer to a constant null-terminated character string that is the fax number dialed for the outgoing fax transmission.

RoutingString

If the JobType member is equal to the JT_RECEIVE job type, RoutingString is a pointer to a constant null-terminated character string that specifies the routing string for an incoming 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 Telecommunications Union (ITU) from Study Group 8 (SG8). This recommendation is currently known as "T.Routing."

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

SenderName

Pointer to a constant null-terminated character string that specifies the name of the sender who initiated the fax transmission.

RecipientName

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

Size

Specifies a DWORD variable that indicates the size, in bytes, of the active fax document.

StartTime

Specifies a FILETIME structure that contains the starting time of the current fax job expressed in Coordinated Universal Time (UTC).

Status

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; 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.

StatusString

This member must be NULL.

SubmittedTime

Specifies a FILETIME structure that contains the time the client submitted the fax document for transmission to the fax job queue. The time is expressed in Coordinated Universal Time (UTC).

TotalPages

Specifies a DWORD variable that indicates the total number of pages in the fax transmission.

Tsid

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

UserName

Pointer to a constant null-terminated character string that specifies the name of the user who submitted the active fax job.

Remarks

The fax client application can call the FaxGetDeviceStatus function to retrieve status information for the fax device of interest. The function returns the information in a FAX_DEVICE_STATUS structure.

For more information, see Fax Device Management. For information about the status information a fax service provider supplies for an active fax operation, see the FAX_DEV_STATUS topic.

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_DEVICE_STATUS

Members

Remarks

Requirements

See Also