2.2.6 _FAX_JOB_ENTRY
The _FAX_JOB_ENTRY structure is the custom-marshaled variant of the FAX_JOB_ENTRY (section 2.2.5) structure and describes one fax job. The structure includes information about the job type and status, the personal profiles (section 3.1.1) of the recipient and sender, scheduling and delivery settings, and the page count. The SizeOfStruct, RecipientNumber, and QueueStatus fields in the Fixed_Portion block MUST NOT be 0. Except for these fields and the JobId field, all fields of this structure are optional, and if the respective information is not available, the fields in the Fixed_Portion block MUST be zero.
An application can call the FAX_GetJob (section 3.1.4.1.41) method to retrieve information about a specified job at the server, information which is returned in a _FAX_JOB_ENTRY structure.
An application can call the FAX_EnumJobs function (section 3.1.4.1.21) to enumerate all queued and active fax jobs (see Fax Queue in section 3.1.1 for details) on the fax server of interest. The FAX_EnumJobs function returns an array of _FAX_JOB_ENTRY structures. Each structure describes one fax job in detail.
This structure is also returned as a single structure by the FaxObs_GetJob (section 3.1.4.2.10) method and as an array of structures by the FaxObs_EnumJobs (section 3.1.4.2.9) 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 (92 bytes) |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
... |
|||||||||||||||||||||||||||||||
Variable_Data (variable) |
|||||||||||||||||||||||||||||||
... |
Fixed_Portion (92 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
JobId
UserNameOffset
JobType
QueueStatus
Status
Size
PageCount
RecipientNumberOffset
RecipientNameOffset
TsidOffset
SenderNameOffset
SenderCompanyOffset
SenderDeptOffset
BillingCodeOffset
ScheduleAction
ScheduleTime (16 bytes)
...
...
...
DeliveryReportType
DeliveryReportAddressOffset
DocumentNameOffset
-
SizeOfStruct (4 bytes): A DWORD ([MS-DTYP] section 2.2.9) that indicates the size, in bytes, of the _FAX_JOB_ENTRY structure. MUST be set to 92 bytes.
-
JobId (4 bytes): A DWORD that indicates a unique number that identifies the fax jobs of interest. This is the same kind of job identifier number as the JobId parameter for the FAX_SetJob (section 3.1.4.1.82) function.
-
UserNameOffset (4 bytes): Offset to the UserName field in the Variable_Data portion of the structure.
-
JobType (4 bytes): A DWORD variable that indicates the type of the fax job of interest. This field is one of the following values, which are defined in section 3.1.1.
-
Value/code
Meaning
0x00000000
The job type is JT_UNKNOWN.
0x00000001
The job type is JT_SEND.
0x00000002
The job type is JT_RECEIVE.
0x00000003
The job type is JT_ ROUTING.
0x00000004
The job type is JT_FAIL_RECEIVE.
0x00000020
The job type is JT_BROADCAST.<2>
-
-
QueueStatus (4 bytes): A DWORD variable containing a set of bit flags indicating the job status of the fax job identified by the JobId field. This field MUST be a bitwise OR combination of one or more of the Job Status values listed in section 3.1.1.
-
Status (4 bytes): A DWORD that specifies the status of the fax device that received or sent the fax job described by this structure, captured at the time the job information was recorded. This value MUST be one of the following predefined device status codes.
-
Value/code
Meaning
FPS_UNKNOWN
0x00000000
The status of the device is unknown.
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.
-
-
Size (4 bytes): A DWORD variable that indicates the total size, in bytes, of the fax document received or sent, including the size of the cover page, if a cover page is present, and the size of the fax body, if a fax body is present. The size MUST NOT exceed 4 gigabytes.
-
PageCount (4 bytes): A DWORD variable that indicates the total number of pages in the fax transmission.
-
RecipientNumberOffset (4 bytes): Offset to the RecipientNumber 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.
-
TsidOffset (4 bytes): Offset to the Tsid 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.
-
SenderCompanyOffset (4 bytes): Offset to the SenderCompany field in the Variable_Data portion of the structure.
-
SenderDeptOffset (4 bytes): Offset to the SenderDepth field in the Variable_Data portion of the structure.
-
BillingCodeOffset (4 bytes): Offset to the BillingCode field in the Variable_Data portion of the structure.
-
ScheduleAction (4 bytes): A DWORD variable that indicates how the fax was configured or is configured to be sent if this job is an outgoing fax transmission; otherwise, this parameter SHOULD be ignored. This value can be one of the following values.
-
Value/code
Meaning
JSA_NOW
0x00000000
The fax is to be sent as soon as a fax device is available.
JSA_SPECIFIC_TIME
0x00000001
The fax is to be sent at the time specified by the ScheduleTime field of this _FAX_JOB_ENTRY structure.
JSA_DISCOUNT_PERIOD
0x00000002
The fax is to be sent during the discount rate period. The FAX_GetConfiguration (section 3.1.4.1.36) or the FaxObs_GetConfiguration (section 3.1.4.2.24) method can be called to retrieve the discount period for the fax server.
-
-
ScheduleTime (16 bytes): A SYSTEMTIME ([MS-DTYP] section 2.3.13) structure indicating the local date and time when the fax was sent or configured to be sent, in UTC format. This parameter SHOULD be ignored unless the ScheduleAction parameter is set to 1 (JSA_SPECIFIC_TIME) and this job is an outgoing fax transmission.
-
DeliveryReportType (4 bytes): A DWORD variable that indicates the fax delivery report type. This value can be one of the FAX_ENUM_DELIVERY_REPORT_TYPES (section 2.2.76) enumeration values. The DRT_ATTACH_FAX value can be combined with the DRT_EMAIL value in one value by an OR operation.
-
DeliveryReportAddressOffset (4 bytes): Offset to the DeliveryReportAddress 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.
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
1UserName (variable)
...
RecipientNumber (variable)
...
RecipientName (variable)
...
Tsid (variable)
...
SenderName (variable)
...
SenderCompany (variable)
...
SenderDept (variable)
...
BillingCode (variable)
...
DeliveryReportAddress (variable)
...
DocumentName (variable)
...
-
UserName (variable): A null-terminated character string that contains the name of the fax user account that submitted the fax job.
-
RecipientNumber (variable): A null-terminated character string that contains the fax number of the recipient of the fax transmission. This information comes from the recipient's personal profile.
-
RecipientName (variable): A null-terminated character string that contains the name of the recipient of the fax. This information comes from the recipient's personal profile.
-
Tsid (variable): A null-terminated character string that contains the transmitting subscriber identifier (TSID). This information comes from the sender's personal profile.
-
SenderName (variable): A null-terminated character string that contains the fax sender name. This information comes from the sender's personal profile.
-
SenderCompany (variable): A null-terminated character string that contains the fax sender company. This information comes from the sender's personal profile.
-
SenderDept (variable): A null-terminated character string that contains the fax sender department. This information comes from the sender's personal profile.
-
BillingCode (variable): A null-terminated character string that contains the fax billing code.
-
DeliveryReportAddress (variable): A null-terminated character string that contains the email address for the delivery report.
-
DocumentName (variable): A null-terminated character string that contains the document name.