3.1.4.1.23 FAX_EnumJobsEx2 (Opnum 88)

The FAX_EnumJobsEx2 (Opnum 88) method is called by the client to enumerate a specified set of jobs on the server's queue for a specific fax account. The type of jobs to enumerate is described by the dwJobTypes argument.

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 whether the client's fax user account has access to enumerate the jobs for the specified account. If the lpcwstrAccountName is not NULL, the server MUST validate the format of the account name. It MUST check for existence of account name. It MUST also verify that the level argument is set to 1.

On success, the server MUST return information about all the jobs of the specified type for the specified account. It MUST also return the total size of the buffer in which the information is returned and the total number of jobs enumerated.

The client SHOULD free the returned buffer.

 error_status_t FAX_EnumJobsEx2(
   [in] handle_t hBinding,
   [in] BOOL fAllAccounts,
   [in, string, unique] LPCWSTR lpcwstrAccountName,
   [in] DWORD dwJobTypes,
   [in] DWORD level,
   [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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

fAllAccounts: Flag indicating whether the jobs for all accounts are enumerated. If this parameter is nonzero, the jobs for all accounts are enumerated and lpcwstrAccountName is reset to NULL and not taken into account. Otherwise, the lpcwstrAccountName parameter SHOULD indicate which accounts are to be enumerated.

lpcwstrAccountName: Pointer to a constant, null-terminated character string that indicates which account to enumerate. If this value is set to NULL, the current account's jobs are enumerated. Cross-account enumeration is currently not supported. If the fAllAccounts parameter is nonzero, this value is reset to NULL. The value for this parameter can be obtained using the FAX_EnumAccounts (section 3.1.4.1.18) method.

dwJobTypes: A DWORD ([MS-DTYP] section 2.2.9) value that MUST consist of a bitwise combination of the job types defined in section 3.1.1. Only jobs that are of the requested types SHOULD be returned in the buffer.

level: A DWORD value that indicates the type of structure to return in the Buffer parameter. The value MUST be set to 1.

Buffer: Pointer to the address of a buffer that will receive an array of FAX_JOB_ENTRY_EX_1 (section 2.2.34) structures. Each structure describes one fax job.

BufferSize: Pointer to a DWORD value that returns the size, in bytes, of Buffer.

lpdwJobs: Pointer to a DWORD value that receives the number of FAX_JOB_ENTRY_EX_1 that the method returns in 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. This error can be returned when any of the following conditions are true: § 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) that are required in order to enumerate jobs of type JT_SEND on its own account. That is, the fAllAccounts parameter is FALSE. § The client's fax user account does not have the FAX_ACCESS_QUERY_OUT_JOBS access right that is required in order to enumerate jobs of type JT_SEND on all accounts. That is, fAllAccounts is TRUE. § The client's fax user account does not have the FAX_ACCESS_MANAGE_RECEIVE_FOLDER access right that is required in order to enumerate 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	The parameter is incorrect. This value is returned when any of the following conditions are true: § Either the lpwdJobs or the Buffer parameter is NULL. § The BufferSize parameter is 0. § The level parameter is not set to 1. § The lpcwstrAccountName parameter contains an improperly formatted account name or points to a nonexistent or other user account.

The account name that lpcwstrAccountName indicates MUST be in one of the following formats. Any other format is invalid.

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