2.2.10 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 includes data about whether the device is currently sending or receiving a fax transmission, device and subscriber identifiers, sender and recipient names, and routing information.
The fax client application can call the FAX_GetDeviceStatus (section 3.1.4.1.38) function to retrieve status information for the fax device of interest. The function returns the information in a FAX_DEVICE_STATUS.
This structure is also returned by the FaxObs_GetDeviceStatus (section 3.1.4.2.13) method.
This data structure is custom marshaled as follows and uses the custom-marshaling rules defined in section 2.2.1.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Fixed_Portion (88 bytes) |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
Variable_Data (variable) |
|||||||||||||||||||||||||||||||
... |
Fixed_Portion (88 bytes):
-
0
1
2
3
4
5
6
7
8
91
0
1
2
3
4
5
6
7
8
92
0
1
2
3
4
5
6
7
8
93
0
1SizeOfStruct
CallerIdOffset
CsidOffset
CurrentPage
DeviceId
DeviceNameOffset
DocumentNameOffset
JobType
PhoneNumberOffset
RoutingStringOffset
SenderNameOffset
RecipientNameOffset
Size
StartTime
...
Status
StatusStringOffset
SubmittedTime
...
TotalPages
TsidOffset
UserNameOffset
-
SizeOfStruct (4 bytes): A DWORD [MS-DTYP] (section 2.2.9) that holds the size of the Fixed_Portion block, in bytes. This value MUST be 88 bytes.
-
CallerIdOffset (4 bytes): Offset to the CallerId field in the Variable_Data portion of the structure. If the JobType field is not equal to the JT_RECEIVE job type, this field SHOULD be zero.
-
CsidOffset (4 bytes): Offset to the Csid field in the Variable_Data portion of the structure.
-
CurrentPage (4 bytes): A DWORD that holds the current page number of the fax transmission, if any, that the fax device is currently sending or receiving. If the device is not sending or receiving a fax, this field MUST be zero.
-
DeviceId (4 bytes): A DWORD that holds the line identifier for the fax device (port) of interest.
-
DeviceNameOffset (4 bytes): Offset to the DeviceName field in the Variable_Data portion of the structure.
-
DocumentNameOffset (4 bytes): Offset to the DocumentName field in the Variable_Data portion of the structure.
-
JobType (4 bytes): A DWORD that holds the type of fax job that is currently active on the device. This field is one of the following values.
-
Value/code
Meaning
JT_UNKNOWN
0x00000000
The fax device is in an unknown or idle state.
JT_SEND
0x00000001
The fax device is sending a fax document.
JT_RECEIVE
0x00000002
The fax device is receiving a fax document.
-
-
PhoneNumberOffset (4 bytes): Offset to the PhoneNumber field in the Variable_Data portion of the structure. If the JobType field is not equal to the JT_SEND job type, this field SHOULD be zero.
-
RoutingStringOffset (4 bytes): If the JobType field is not equal to the JT_RECEIVE job type, this field SHOULD be zero. Otherwise, this field MAY be a nonzero offset to the RoutingString field in the Variable_Data portion of the structure.
-
SenderNameOffset (4 bytes): Offset to the SenderName field in the Variable_Data portion of the structure.
-
RecipientNameOffset (4 bytes): Offset to the RecipientName field in the Variable_Data portion of the structure.
-
Size (4 bytes): A DWORD that holds the size, in bytes, of the active fax document. If the JobType field is JT_SEND, this field SHOULD contain the total size of the active fax document being transmitted at the device, including the size of the cover page and the size of the fax body, if present. Otherwise, this field SHOULD be zero.
-
StartTime (8 bytes): A FILETIME ([MS-DTYP] section 2.3.3) structure that specifies the starting time of the current fax job. The time is expressed in Coordinated Universal Time (UTC).
-
Status (4 bytes): A DWORD variable that holds a fax device status code or value. This field is 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.
-
-
StatusStringOffset (4 bytes): Offset to the StatusString field in the Variable_Data portion of the structure. This field can be set to zero.<3>
-
SubmittedTime (8 bytes): A FILETIME that holds the time the client submitted the fax document for transmission to the fax queue. The time is expressed in UTC.
-
TotalPages (4 bytes): A DWORD that holds the total number of pages in the fax transmission.
-
TsidOffset (4 bytes): Offset to the Tsid field in the Variable_Data portion of the structure.
-
UserNameOffset (4 bytes): Offset to the UserName field in the Variable_Data portion of the structure.
Variable_Data (variable):
-
0
1
2
3
4
5
6
7
8
91
0
1
2
3
4
5
6
7
8
92
0
1
2
3
4
5
6
7
8
93
0
1CallerId (variable)
...
Csid (variable)
...
DeviceName (variable)
...
DocumentName (variable)
...
PhoneNumber (variable)
...
RoutingString (variable)
...
SenderName (variable)
...
RecipientName (variable)
...
StatusString (variable)
...
Tsid (variable)
...
UserName (variable)
...
-
CallerId (variable): If the JobType field is equal to the JT_RECEIVE job type, this is a null-terminated character string that contains the caller ID of the calling device that sent the active fax document.
-
Csid (variable): A null-terminated character string that holds the called subscriber identifier of the device.
-
DeviceName (variable): A null-terminated character string that holds the name of the fax device of interest.
-
DocumentName (variable): A null-terminated character string that holds the document name to associate with the fax document that the device is currently sending or receiving.
-
PhoneNumber (variable): If the JobType field is equal to the JT_SEND job type, this is a null-terminated character string that holds the fax number dialed for the outgoing fax transmission.
-
RoutingString (variable): If the JobType field is equal to the JT_RECEIVE job type, this is a null-terminated character string that holds the routing string (section 3.1.1) for an incoming fax.
-
SenderName (variable): A null-terminated character string that holds the name of the sender who initiated the fax transmission.
-
RecipientName (variable): A null-terminated character string that holds the name of the recipient of the fax transmission.
-
StatusString (variable): A null-terminated character string that holds a textual description of the fax device status.
-
Tsid (variable): A null-terminated character string that holds the transmitting subscriber identifier (TSID). This identifier is usually a telephone number.
-
UserName (variable): A null-terminated character string that holds the name of the client's fax user account that submitted the active fax job. When this structure is returned by the FAX_GetDeviceStatus (section 3.1.4.1.38) method, this account is the client's fax user account that called the FAX_SendDocumentEx (section 3.1.4.1.73) method. When this structure is returned by the FaxObs_GetDeviceStatus (section 3.1.4.2.13) method, this account is the client's Fax User Account that called the FaxObs_SendDocument (section 3.1.4.2.7) method.