3.1.4.1.4 FAX_AccessCheckEx2 (Opnum 101)

The FAX_AccessCheckEx2 (Opnum 101) method is called by the client when the client needs to check whether the client's fax user account has certain access permissions on the server.

In response, the server MUST validate the access rights specified by the client against the actual access rights granted to the client's fax user account. On success, the server SHOULD return the access rights specified by the client that are granted to the client's fax user account.

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

 error_status_t FAX_AccessCheckEx2(
   [in] handle_t hBinding,
   [in] DWORD AccessMask,
   [out, ref] BOOL* pfAccess,
   [in, out, unique] LPDWORD lpdwRights
 );

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.

AccessMask: A DWORD ([MS-DTYP] section 2.2.9) variable that contains a set of bit flags specified by the client to be validated. Zero is a valid value for this parameter and means that no access rights are specified by the client to be validated. This parameter can be any combination of fax-specific access rights, standard access rights, and fax-generic access rights. If this parameter is set to 0x02000000 (MAXIMUM_ALLOWED), on return, the lpdwRights parameter SHOULD receive the maximum access rights granted to the client's fax user account.

Fax-generic access rights	Description
FAX_GENERIC_EXECUTE_2 0x00000001	Includes the read-only rights granted by the FAX_ACCESS_SUBMIT access right.
FAX_GENERIC_READ_2 0x00000020	Includes the read-only rights granted by the FAX_ACCESS_QUERY_CONFIG access right.
FAX_GENERIC_WRITE_2 0x00000040	Includes the read-only rights granted by the FAX_ACCESS_MANAGE_CONFIG access right.
FAX_GENERIC_ALL_2 0x000003FF	Includes the read-only rights granted by the following fax-specific access rights: § FAX_ACCESS_SUBMIT § FAX_ACCESS_SUBMIT_NORMAL § FAX_ACCESS_SUBMIT_HIGH § FAX_ACCESS_QUERY_OUT_JOBS § FAX_ACCESS_MANAGE_OUT_JOBS § FAX_ACCESS_QUERY_CONFIG § FAX_ACCESS_MANAGE_CONFIG § FAX_ACCESS_QUERY_ARCHIVES § FAX_ACCESS_MANAGE_ARCHIVES § FAX_ACCESS_MANAGE_RECEIVE_FOLDER

Fax-specific access rights	Description
FAX_ACCESS_SUBMIT 0x00000001	Grants permission to send a low-priority fax transmission to one or more recipients.
FAX_ACCESS_SUBMIT_NORMAL 0x00000002	Grants permission to send a normal-priority fax transmission to one or more recipients.
FAX_ACCESS_SUBMIT_HIGH 0x00000004	Grants permission to send a high-priority fax transmission to one or more recipients.
FAX_ACCESS_QUERY_OUT_JOBS 0x00000008	Grants permission to view the outgoing faxes in the fax queue. By default, no users have this permission.
FAX_ACCESS_MANAGE_OUT_JOBS 0x00000010	Grants permission to manage the outgoing faxes in the fax queue by using such operations as pause, resume, restart, and delete (section 3.1.4.1.82). By default, no users have this permission.
FAX_ACCESS_QUERY_CONFIG 0x00000020	Grants permission to view the properties of the Fax Service and to enumerate accounts, and to read any account configuration information. By default, non-administrator users do not have this permission. Without it, users cannot view any of the tree nodes, except for the cover page node in the Fax Service Manager.
FAX_ACCESS_MANAGE_CONFIG 0x00000040	Grants permission to modify the properties of the fax service. By default, non-administrator users do not have this permission.
FAX_ACCESS_QUERY_ARCHIVES 0x00000080	Grants permission to view the sent and received fax messages in the archives. By default, no users have this permission.
FAX_ACCESS_MANAGE_ARCHIVES 0x00000100	Grants permission to manage the sent and received fax messages in the archives by using such operations as delete (section 3.1.4.1.70) and copy (sections 3.1.4.1.96, 3.1.4.1.97, and 3.1.4.1.15). By default, no users have this permission.
FAX_ACCESS_MANAGE_RECEIVE_FOLDER 0x00000200	When global routing is not enabled, this permission allows the user to delete any messages. When global routing is active, it allows the user to see the contents of all receive folder faxes, to delete faxes, and to cancel receive transmissions in progress.

pfAccess: A pointer to a Boolean value that receives the access check return value. This value MUST be TRUE if the client's fax user account has all of the fax access rights specified by the AccessMask parameter; otherwise, this value MUST be FALSE. If the value submitted by the client for the AccessMask is zero, the value pointed to by the pfAccess parameter SHOULD be FALSE on return.

lpdwRights: A pointer to a DWORD value that receives the fax access rights that this caller is verified to have of those requested in the AccessMask parameter. This value MUST be a DWORD bitwise OR combination of fax-specific access rights, standard access rights, and/or fax-generic access rights limited to those specified by the client in the AccessMask. In order for the client to be verified for the maximum allowed rights, the caller MUST set the AccessMask to 0x02000000 (MAXIMUM_ALLOWED) and the server SHOULD set this output value to the actual rights that this caller is verified to have.

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 caller does not have the required permissions for this request (the caller does not have a valid fax user account).
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The pointer specified in the pfAccess parameter is NULL. § The fax access rights specified in the lpdwRights parameter contain invalid access values.

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