3.1.4.1.42 FAX_GetJobEx (Opnum 29)

The FAX_GetJobEx (Opnum 29) is called by the client to retrieve information about a specified job at the server. The job is identified by the job message ID. The job message ID 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).

In response, the server MUST validate that the message ID is for a valid job. The server MUST validate that the client's fax user account has read access to the job.

On success, the server MUST return the queued job's job information and the size of the job information.

This method is an extended version of FAX_GetJob (section 3.1.4.1.41), which returns a FAX_JOB_ENTRY_EXW (section 2.2.35) structure for the specified message.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetJobEx(
   [in] handle_t hBinding,
   [in] DWORDLONG dwlMessageID,
   [out, size_is(, *BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize
 );

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.

dwlMessageID: A unique number that identifies a queued or active fax job. The job MUST be an inbound or outbound transmission.

Buffer: A pointer to the address of a buffer to receive one FAX_JOB_ENTRY_EXW followed by one FAX_JOB_STATUS (section 2.2.36) structure, followed by other data pointed at from these two structures (from pointer type fields). These two data structures describe one fax job. If the pStatus pointer field of the FAX_JOB_ENTRY_EXW is not NULL, it MUST point to the address of the FAX_JOB_STATUS in the buffer. If the pStatus pointer is NULL, the FAX_JOB_STATUS is located in the buffer immediately after the FAX_JOB_ENTRY_EXW. The field length MUST be clamped to 32 bits before serialization.

BufferSize: A variable to return the size, in bytes, of the buffer.

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 for this operation: ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83).
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The server cannot allocate memory for the data to be returned to the caller.
ERROR_INVALID_PARAMETER 0x00000057	This error code is returned under any of the following conditions:<111> § The pointer submitted for the Buffer argument is NULL. § The pointer submitted for the BufferSize argument is NULL.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	The fax server cannot find the fax job indicated by the dwlMessageId argument.

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