2.2.5 FAX_JOB_ENTRY

  • Article

The FAX_JOB_ENTRY structure describes one fax job. The structure includes information about the job type and status, the recipient's and the sender's personal profiles (section 3.1.1), scheduling and delivery settings, and the page count.

This structure is used as an input argument for the FaxObs_SetJob (section 3.1.4.2.11) method.

 typedef struct {
   DWORD SizeOfStruct;
   DWORD JobId;
   LPCWSTR UserName;
   DWORD JobType;
   DWORD QueueStatus;
   DWORD Status;
   DWORD Size;
   DWORD PageCount;
   LPCWSTR RecipientNumber;
   LPCWSTR RecipientName;
   LPCWSTR Tsid;
   LPCWSTR SenderName;
   LPCWSTR SenderCompany;
   LPCWSTR SenderDept;
   LPCWSTR BillingCode;
   DWORD ScheduleAction;
   SYSTEMTIME ScheduleTime;
   DWORD DeliveryReportType;
   LPCWSTR DeliveryReportAddress;
   LPCWSTR DocumentName;
 } FAX_JOB_ENTRY,
  *PFAX_JOB_ENTRY;

SizeOfStruct: A DWORD ([MS-DTYP] section 2.2.9) that indicates the size, in bytes, of the FAX_JOB_ENTRY structure. This value MUST be 92 or 136 bytes. When filled in on a 32-bit implementation, this value SHOULD be 92 bytes. When filled in on a 64-bit implementation, this value SHOULD be 136 bytes.

JobId: 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.

UserName: A null-terminated character string that contains the name of the fax user account that submitted the fax job, if known; otherwise, a NULL pointer.

JobType: A DWORD 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.

QueueStatus: A DWORD variable containing a set of bit flags indicating the job status of the fax job identified by the JobId field. This value MUST be a bitwise OR combination of one or more of the Job Status values listed in section 3.1.1.

Status: A DWORD that specifies the status of the fax device (or port) that received or sent the fax job described by this structure, captured at the time the job information was recorded. This member SHOULD be ignored when this structure is used as an input argument for the FaxObs_SetJob method. 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: A DWORD variable that indicates the total size, in bytes, of the fax document to transmit, if known, or zero otherwise.  The size, if known, includes 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: A DWORD that indicates the total number of pages in the fax transmission, including the cover page, if any, and the fax body, if any, of the fax submitted with this fax job. If the fax is sent to multiple recipients, this total number of pages is the number of fax pages sent to each individual recipient (not the sum of the fax pages sent to all recipients).

RecipientNumber: A null-terminated character string that contains the fax number of the recipient of the fax transmission, if known, or a NULL pointer otherwise. This information comes from the recipient's personal profile.

RecipientName: A null-terminated character string that contains the name of the recipient of the fax, if known, or a NULL pointer otherwise. This information comes from the recipient's personal profile.

Tsid: A null-terminated character string that contains the transmitting subscriber identifier (TSID), if known, or a NULL pointer otherwise. This information comes from the sender's personal profile.

SenderName: A null-terminated character string that contains the fax sender name, if known, or a NULL pointer otherwise. This information comes from the sender's personal profile.

SenderCompany: A null-terminated character string that contains the fax sender company, if known, or a NULL pointer otherwise. This information comes from the sender's personal profile.

SenderDept: A null-terminated character string that contains the fax sender department, if known, or a NULL pointer otherwise. This information comes from the sender's personal profile.

BillingCode: A null-terminated character string that contains the fax billing code, if known, or a NULL pointer otherwise.

ScheduleAction: A DWORD that indicates when the fax is to be sent. This 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 FaxObs_GetConfiguration (section 3.1.4.2.24) method can be called to retrieve the discount period for the fax server.

ScheduleTime: A SYSTEMTIME ([MS-DTYP] section 2.3.13) structure indicating the local date and time to send the fax, in Coordinated Universal Time (UTC) format. This parameter MUST be ignored unless the ScheduleAction parameter is set to 1 (JSA_SPECIFIC_TIME).

DeliveryReportType: A DWORD variable that indicates the fax delivery report type. This value MUST 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 by an OR operation.

DeliveryReportAddress: A null-terminated character string that contains the email address for the delivery report, if known, or a NULL pointer otherwise.

DocumentName: A null-terminated character string that contains the document name, if known, or a NULL pointer otherwise.