3.1.4.1.18 FAX_EnumAccounts (Opnum 95)

The FAX_EnumAccounts (Opnum 95) method is called by the client to enumerate all the fax accounts on the server.

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).

The server MUST validate that the client's fax user account  has access to receive an enumeration of the accounts. The Buffer, BufferSize, and lpdwAccounts parameters MUST NOT be NULL. On success, the server MUST enumerate all existing fax accounts and return the enumerated accounts in Buffer.

 error_status_t FAX_EnumAccounts(
   [in] handle_t hBinding,
   [in] DWORD level,
   [out, size_is(,*BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize,
   [out, ref] LPDWORD lpdwAccounts
 );

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.

level: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the type of structure that is pointed to by Buffer. The value passed in this parameter MUST be zero.

Buffer: A pointer to an array of FAX_ACCOUNT_INFO_0 (section 2.2.24) structures that contain fax account information.

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

lpdwAccounts: A DWORD that contains the number of accounts whose information is being returned.

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	The client's fax user account does not have the access right FAX_ACCESS_QUERY_CONFIG to perform this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The fax server failed to allocate the amount of memory needed to process this request.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § The value specified for the level parameter is not equal to zero. § The pointer specified by the Buffer parameter is NULL.<83> § The value pointed to by the BufferSize parameter is zero.<84> § The pointer specified by the lpdwAccounts parameter is NULL.<85>

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

Format	Description
<machine_name>\<user_name>	For a local user with machine_name as the local machine's name.
<domain_name>\<user_name>	For a nonlocal user.

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