3.1.4.2.11 FaxObs_SetJob (Opnum 9)

The FaxObs_SetJob (Opnum 9) method is called by the client to pause, resume, or cancel a fax job. The value for the JobId parameter can be obtained by calling the FaxObs_EnumJobs (section 3.1.4.2.9) or FaxObs_SendDocument (section 3.1.4.2.7) method.

On success, the server MUST pause, resume, or cancel the specified fax job and MUST set the job status (section 3.1.1) to reflect the new job state.

 error_status_t FaxObs_SetJob(
   [in] handle_t hBinding,
   [in] DWORD JobId,
   [in] DWORD Command,
   [in] const FAX_JOB_ENTRY* JobEntry
 );

hBinding: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FaxObs_ConnectionRefCount (section 3.1.4.2.2) method call used to connect to the fax server.

JobId: A DWORD ([MS-DTYP] section 2.2.9) containing a value that uniquely identifies the fax job to modify.

Command: A DWORD containing a job command that the fax server is requested to perform.

Value/code	Meaning
JC_DELETE 0x00000001	The fax server MUST cancel the specified fax job. This job can be in an active or queued state. This is equivalent to calling the FaxObs_Abort (section 3.1.4.2.14) method.
JC_PAUSE 0x00000002	The fax server MUST pause the specified fax job if the job's status is JS_PENDING or JS_RETRYING.
JC_RESUME 0x00000003	The fax server MUST resume the specified fax job if it is in a paused state and return the job status to the value it had when the job was paused: JS_PENDING or JS_RETRYING.

Note that JC_RESTART is defined to the same value as JC_RESUME. When receiving a value of 0x00000003 the server MUST treat this as a JC_RESUME request.

JobEntry: A pointer to a FAX_JOB_ENTRY (section 2.2.5) structure. The fax server MUST validate this pointer to be not NULL and fail to return ERROR_INVALID_PARAMETER otherwise. Except for this validation requirement, the fax server SHOULD ignore this parameter. The fax client SHOULD submit the pointer to a valid FAX_JOB_ENTRY. This structure contains data obtained from FaxObs_GetJob (section 3.1.4.2.10) or FaxObs_EnumJobs (section 3.1.4.2.9). This data represents the job identified by the JobId parameter.<196>

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. This error code is returned under any of the following conditions: § The client's fax user account does not have the FAX_ JOB_MANAGE access rights. § The client's fax user account is not the owner of the fax job identified by the JobId parameter.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The fax job indicated by JobId cannot be found by the fax server. § The specified Command parameter value is not JC_DELETE, JC_PAUSE, or JC_RESUME. § The specified Command value is JC_DELETE, the specified JobId represents the job for an outgoing broadcast message, and aborting outgoing broadcast messages is not supported. For more information, see FaxObs_Abort. § The JobId is set to a NULL pointer value.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol, [MS-RPCE].