3.1.4.1.12 FAX_CreateAccount (Opnum 93)

The FAX_CreateAccount (Opnum 93) method is called by the client to request a new fax user account to be created based on an existing valid operating system user account.

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 create an account. On success, the server MUST create a new fax account. The server SHOULD apply the following default fax access rights, depending on the authenticated user identity of the user account described by the FAX_ACCOUNT_INFO_0 (section 2.2.24) structure,<77> and return ERROR_SUCCESS. The function MUST return ERROR_ALREADY_EXISTS if the account already exists.

The client SHOULD free the returned Buffer.

 error_status_t FAX_CreateAccount(
   [in] handle_t hBinding,
   [in] DWORD level,
   [in, ref, size_is(BufferSize)] const LPBYTE Buffer,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD 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.

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

Buffer: A pointer to a FAX_ACCOUNT_INFO_0 that contains fax account information. The lpcwstrAccountName member of the FAX_ACCOUNT_INFO_0 MUST be set to the name of the operating system user account for which the new fax user account is to be created, using the same account name. The format of the user account name string is described in section 2.2.24 (FAX_ACCOUNT_INFO_0).

BufferSize: A DWORD value that indicates the return size, in bytes, of the buffer that is pointed to by the Buffer parameter. The maximum size is FAX_MAX_RPC_BUFFER(section 2.2.82).

Return Values: This method MUST return 0 (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 that are 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 the FAX_ACCESS_MANAGE_CONFIG access right.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This value is returned when any of the following conditions are true: § The Buffer parameter is NULL. § The BufferSize parameter is 0. § The level parameter is greater than zero. § The account name, as pointed to by the account information contained in Buffer, is NULL or is specified using an invalid format.
ERROR_ALREADY_EXISTS 0x000000B7	The fax account already exists.
ERROR_INVALID_HANDLE_STATE 0x00000649	The handle is in an invalid state.

The account name contained in the lpcwstrAccountName member of the FAX_ACCOUNT_INFO_0, as pointed to by the Buffer parameter, 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].