3.1.4.1.3 FAX_AccessCheck (Opnum 25)

The FAX_AccessCheck (Opnum 25) method is called 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 specific access rights of 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.

 error_status_t FAX_AccessCheck(
   [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 MUST contain a set of bit flags that define the fax access permissions specified by the client to be validated against the access permissions of the client's fax user account. This parameter can be any bitwise OR combination of fax-specific access rights, standard access rights, and fax-generic access rights. For a list of standard access rights, see [MSDN-SAR].

Fax-generic access rights

Meaning

FAX_GENERIC_EXECUTE

0x00000001

Identical to the FAX_ACCESS_SUBMIT access right.

FAX_GENERIC_READ

0x000002A8

Includes the read-only rights that are granted by the following specific access rights:

§ FAX_ACCESS_QUERY_JOBS

§ FAX_ACCESS_QUERY_CONFIG

§ FAX_ACCESS_QUERY_IN_ARCHIVE

§ FAX_ACCESS_QUERY_OUT_ARCHIVE

FAX_GENERIC_WRITE

0x00000550

Includes the management rights that are granted by the following specific access rights:

§ FAX_ACCESS_MANAGE_JOBS

§ FAX_ACCESS_MANAGE_CONFIG

§ FAX_ACCESS_MANAGE_IN_ARCHIVE

§ FAX_ACCESS_MANAGE_OUT_ARCHIVE

FAX_GENERIC_ALL

0x000007FF

Includes all the following specific fax permissions:

§ FAX_ACCESS_SUBMIT

§ FAX_ACCESS_SUBMIT_NORMAL

§ FAX_ACCESS_SUBMIT_HIGH

§ FAX_ACCESS_QUERY_JOBS

§ FAX_ACCESS_MANAGE_JOBS

§ FAX_ACCESS_QUERY_CONFIG

§ FAX_ACCESS_MANAGE_CONFIG

§ FAX_ACCESS_QUERY_IN_ARCHIVE

§ FAX_ACCESS_MANAGE_IN_ARCHIVE

§ FAX_ACCESS_QUERY_OUT_ARCHIVE

§ FAX_ACCESS_MANAGE_OUT_ARCHIVE

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_JOBS

0x00000008

Grants permission to view all the incoming and outgoing faxes in the Incoming and Outbox queues, including those that belong to other users. By default, without this permission, non-administrator users can view their own outgoing messages in the Outbox queue but cannot view the Incoming queue. Also, non-administrator users cannot view incoming or outgoing faxes that belong to other users.

FAX_ACCESS_MANAGE_JOBS

0x00000010

Grants permission to manage all the incoming and outgoing faxes in the Incoming and Outbox queues, including those that belong to other users. By default, without this permission, non-administrator users can manage their own outgoing messages in the Outgoing queue (defined in section 3.1.1) but cannot manage the Incoming queue. Also, non-administrator users cannot manage incoming or outgoing faxes that belong to other users.

FAX_ACCESS_QUERY_CONFIG

0x00000020

Grants permission to view the properties of the Fax Service. By default, non-administrator users do not have this permission. Without this permission, 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_IN_ARCHIVE

0x00000080

Grants permission to view all successfully received messages in the Inbox archive. By default, without this permission, non-administrator users cannot view archived incoming faxes.

FAX_ACCESS_MANAGE_IN_ARCHIVE

0x00000100

Grants permission to manage all successfully received messages in the Inbox archive. By default, without this permission, non-administrator users cannot manage archived incoming faxes.

FAX_ACCESS_QUERY_OUT_ARCHIVE

0x00000200

Grants permission to view all successfully sent messages in the Sent Items archive, including those belonging to other users. By default, without this permission, non-administrator users can view archives of their own sent messages but cannot view archives that belong to other users.

FAX_ACCESS_MANAGE_OUT_ARCHIVE

0x00000400

Grants permission to manage all successfully sent messages in the Sent Items archive, including those that belong to other users. By default, without this permission, non-administrator users can manage archives of their own sent messages but cannot manage archives that belong to other users.

Standard access rights

Descriptiion

DELETE

0x00010000

Delete access.

READ_CONTROL

0x00020000

Read access to the owner, group, and discretionary access control list (ACL) of the security descriptor.

WRITE_DAC

0x00040000

Write access to the ACL.

WRITE_OWNER

0x00080000

Write access to the owner.

SYNCHRONIZE

0x00100000

Allow use of the object for synchronization.

Miscellaneous access rights

Description

MAXIMUM_ALLOWED

0x02000000

Maximum allowed access rights for this server.

pfAccess: A pointer to a BOOL ([MS-DTYP] section 2.2.3) to receive 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 to receive 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 maxiumum 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 user does not have a valid fax user account on the server.<65>

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect. The pfAccess argument is NULL,<66> or the access mask specified by the AccessMask argument contains invalid fax-specific access rights.

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