3.1.4.1.43 FAX_GetJobEx2 (Opnum 87)

The FAX_GetJobEx2 (Opnum 87) method is called by the client to retrieve information about a specified job. 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).

Protocol version FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), and FAX_API_VERSION_2 (0x00020000) fax servers SHOULD NOT implement this call. The fax client MUST NOT call this method if the protocol version reported by the server is FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), or FAX_API_VERSION_2 (0x00020000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10).

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 information about the specified job in a FAX_JOB_ENTRY_EX_1 (section 2.2.34) structure. This method is an extended version of FAX_GetJob (section 3.1.4.1.41).

The client SHOULD free the returned buffer.

 error_status_t FAX_GetJobEx2(
   [in] handle_t hBinding,
   [in] DWORDLONG dwlMessageID,
   [in] DWORD level,
   [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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

dwlMessageID: A DWORDLONG ([MS-DTYP] section 2.2.13) value that specifies a unique number that identifies a queued or active fax job. The job MUST be an inbound or outbound transmission.

level: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the structure to return in Buffer. This value MUST be set to 1.

Buffer: A pointer to the address of a buffer that receives a FAX_JOB_ENTRY_EX_1.

BufferSize: A pointer to a DWORD value that specifies the size, in bytes, of the buffer that is pointed to by the Buffer parameter.

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 any of the permissions covered by ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83). § For an outgoing fax job, the caller is not the owner of the fax job, and the caller does not have the FAX_ACCESS_MANAGE_OUT_JOBS rights. § For an incoming fax job, the caller is not the receiver of the call, incoming faxes are not public, and the client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER rights.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command. The fax server failed to allocate sufficient memory to hold the FAX_JOB_ENTRY_EX_1 to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The Buffer and/or BufferSize parameters are set to NULL pointer values.<112> § The level parameter is set to a value other than 1.
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the FAX_JOB_ENTRY_EX_1 to be returned to the client.
FAX_ERR_MESSAGE_NOT_FOUND 0x00001B61	This error code is returned under any of the following conditions: § The fax server cannot find the fax job identified by the value of the dwlMessageID parameter. § The user is not the owner of the fax job identified by the value of dwlMessageID.

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