3.1.4.1.82 FAX_SetJob (Opnum 6)

The FAX_SetJob (Opnum 6) method is called by the client. The value for the JobId parameter can be obtained using one of the following methods: FAX_EnumJobs (section 3.1.4.1.21), FAX_EnumJobsEx (section 3.1.4.1.22), or FAX_EnumJobsEx2 (section 3.1.4.1.23).

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

 error_status_t FAX_SetJob(
   [in] handle_t hBinding,
   [in] DWORD JobId,
   [in] DWORD Command
 );

hBinding: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FAX_ConnectFaxServer (section 3.1.4.1.10) or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

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

Command: A DWORD variable that indicates the 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 with the FAX_Abort (section 3.1.4.1.2) call.
JC_PAUSE 0x00000002	The fax server MUST pause the specified fax job if the job 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.
JC_RESTART 0x00000003	The fax server MUST restart the specified fax job.

Note  that JC_RESUME and JC_RESTART are both defined to the same value. When receiving either a JC_RESUME or JC_RESTART FAX_SetJob request, the server MUST restart the job if the Job Status (section 3.1.1) is JS_RETRIES_EXCEEDED (_FAX_JOB_ENTRY (section 2.2.6)); otherwise, the server MUST resume the job.

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. The client's fax user account does not have the access rights required to perform this operation: § For an outgoing fax job, the client's fax user account is not the owner of the fax job and the client's fax user account does not have the FAX_ACCESS_MANAGE_OUT_JOBS rights. § For an incoming fax job, incoming faxes are not public, and the client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER rights.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The fax job indicated by the JobId argument cannot be found by the fax server. § The specified Command argument value is JC_DELETE and the fax job specified by the JobId argument indicates a fax job that is already in a state of being deleted or was already deleted. § The specified Command argument value is JC_UNKNOWN (0). § The specified Command argument value is not JC_DELETE, JC_PAUSE, or JC_RESUME/JC_RESTART. § The specified Command argument value is JC_DELETE and the type of the fax job specified by the JobId parameter is JT_BROADCAST See the definition of the dwJobType member of the FAX_JOB_STATUS structure (section 2.2.36).
ERROR_INVALID_OPERATION 0x000010DD	The specified Command argument value is JC_DELETE, and the specified JobId represents a fax job with a current job status other than JS_PENDING or JS_RETRYING.

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