3.1.4.1.22 FAX_EnumJobsEx (Opnum 28)

  • Article

The FAX_EnumJobsEx (Opnum 28) method is called by the client to enumerate a specified set of jobs on the server's queue. The type of jobs to enumerate is described by the dwJobTypes argument.

In response, the server MUST validate whether the client's fax user account has access to enumerate the jobs. On success, the server MUST return information about all the jobs of the specified type. It MUST also return the total size of the buffer in which the information is returned and the total number of enumerated jobs.

The client SHOULD free the returned buffer.

 error_status_t FAX_EnumJobsEx(
   [in] handle_t hBinding,
   [in] DWORD dwJobTypes,
   [out, size_is(, *BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize,
   [out, ref] LPDWORD lpdwJobs
 );

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.

dwJobTypes: A DWORD ([MS-DTYP] section 2.2.9) value. The dwJobTypes parameter SHOULD be a bitwise combination of job types defined in section 3.1.1. Only jobs that are of the requested types SHOULD be returned in the buffer. If zero is passed as a value for the parameter (0 is not a valid job type), the server will return success, but with a zero-byte buffer.

Buffer: A pointer to the address of a buffer to receive an array of FAX_JOB_ENTRY_EXW (section 2.2.35) structures followed by an array of the same number of FAX_JOB_STATUS (section 2.2.36) structures, followed by other data pointed at from these structures (from pointer type fields). Each FAX_JOB_ENTRY_EXW and FAX_JOB_STATUS pair describes one fax job. For each returned FAX_JOB_ENTRY_EXW, if the pStatus pointer is not NULL, it MUST point to one of the FAX_JOB_STATUS in the buffer. If the pStatus pointer is NULL, the FAX_JOB_STATUS attached to the current FAX_JOB_ENTRY_EXW is located at the corresponding index position in the structure array. This data is serialized on the wire. The field length MUST be clamped to 32 bits before serialization.

For example, when three jobs are successfully enumerated, the call returns ERROR_SUCCESS with a value of 3 for the *lpdwJobs output argument. The returned data is arranged in memory as follows, from the start of the address specified by the Buffer parameter:

Data structure

Size

Description

FAX_JOB_ENTRY_EXW

 
sizeof(FAX_JOB_ENTRY_EXW)

The first FAX_JOB_ENTRY_EXW in the buffer, corresponding to the first FAX_JOB_STATUS in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

FAX_JOB_ENTRY_EXW

 
 sizeof(FAX_JOB_ENTRY_EXW)

The second FAX_JOB_ENTRY_EXW in the buffer, corresponding to the second FAX_JOB_STATUS in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

FAX_JOB_ENTRY_EXW

 
 sizeof(FAX_JOB_ENTRY_EXW)

The third FAX_JOB_ENTRY_EXW in the buffer, corresponding to the third FAX_JOB_STATUS in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

FAX_JOB_STATUS

 
 sizeof(FAX_JOB_STATUS)

The first FAX_JOB_STATUS in the buffer, corresponding to the first FAX_JOB_ENTRY_EXW in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

FAX_JOB_STATUS

 
 sizeof(FAX_JOB_STATUS)

The second FAX_JOB_STATUS in the buffer, corresponding to the second FAX_JOB_ENTRY_EXW in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

FAX_JOB_STATUS

 
 sizeof(FAX_JOB_STATUS)

The third FAX_JOB_STATUS in the buffer, corresponding to the third FAX_JOB_ENTRY_EXW in the buffer if pStatus is NULL in this FAX_JOB_ENTRY_EXW.

Other data

 
 *BufferSize   – (3 * (sizeof(FAX_JOB_ENTRY_EXW) + sizeof(FAX_JOB_STATUS)))

Data pointed at by pointer fields in FAX_JOB_ENTRY_EXW and FAX_JOB_STATUS at the beginning of the buffer.

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

lpdwJobs: A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable to receive the number of FAX_JOB_ENTRY_EXW and FAX_JOB_STATUS that the method returns in 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. The client's fax user account does not have any of the access rights defined in ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83) when enumerating jobs of type JT_SEND. The client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER access right when enumerating jobs of type JT_RECEIVE or JT_ROUTING.

ERROR_NOT_ENOUGH_MEMORY

0x00000008

Not enough storage is available to process this command.

ERROR_INVALID_PARAMETER

0x00000057

At least one of the following arguments has been specified as NULL: Buffer, BufferSize, or lpdwJobs.<88>

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