3.1.4.1.32 FAX_GetAccountInfo (Opnum 96)

The FAX_GetAccountInfo (Opnum 96) method is called by the client to retrieve information about a specified fax user account. The fax user account for which information is retrieved is specified by the lpcwstrAccountName parameter, which can be obtained using the FAX_EnumAccounts (section 3.1.4.1.18) method.

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 the account name that is passed in with the lpwstrAccountName argument. If the account name specified by the lpwstrAccountName argument is not the same as the logged-on user, the server MUST check whether this user account has access to query configuration as follows. If the user account specified by the lpwstrAccountName argument is not the caller, and it does not have the FAX_ACCESS_QUERY_CONFIG rights, the call MUST return ERROR_ACCESS_DENIED. The server MUST allocate the buffer to hold the account information.

On success, the server MUST return the detailed information about the account that is passed in the buffer as per the level specified, along with the buffer size.

The client SHOULD free the buffer.

 error_status_t FAX_GetAccountInfo(
   [in] handle_t hBinding,
   [in, string, unique] LPCWSTR lpcwstrAccountName,
   [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.

lpcwstrAccountName: A pointer to a constant, null-terminated character string that contains the name of the account for which to retrieve information.

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

Buffer: A pointer to a FAX_ACCOUNT_INFO_0 (section 2.2.24) structure that contains fax account information.

BufferSize: A pointer to a DWORD value that specifies the size, in bytes, of the structure 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_FILE_NOT_FOUND 0x00000002	The account name specified by the lpcwstrAccountName parameter appears valid but does not exist.
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The user account specified by the lpwstrAccountName argument is not the caller, and it does not have the fax access rights FAX_ACCESS_QUERY_CONFIG.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. The value of the level argument is greater than zero. The account name specified by lpcwstrAccountName is not a valid fax account name.

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 that has machine_name as the name of the local machine.
<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].