3.1.4.1.60 FAX_GetSecurityEx2 (Opnum 99)

The FAX_GetSecurityEx2 (Opnum 99) method is called by the client to retrieve information about the fax security descriptor from the fax 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 the access to retrieve security information. The pSecurityDescriptor parameter MUST NOT be NULL. On success, the server MUST return the fax security descriptor from the fax server in pSecurityDescriptor.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetSecurityEx2(
   [in] handle_t hBinding,
   [in] SECURITY_INFORMATION SecurityInformation,
   [out, size_is(,*lpdwBufferSize)] 
     LPBYTE* pSecurityDescriptor,
   [out, ref] LPDWORD lpdwBufferSize
 );

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.

SecurityInformation: Defines the desired entries, which are indicated as a bitwise OR operation, in the security descriptor to return.

SecurityInformation MUST be a bitwise combination of the following four values found in the SECURITY_INFORMATION ([MS-DTYP] section 2.4.7) datatype:

§ OWNER_SECURITY_INFORMATION: 0x00000001

§ GROUP_SECURITY_INFORMATION: 0x00000002

§ DACL_SECURITY_INFORMATION: 0x00000004

§ SACL_SECURITY_INFORMATION: 0x00000008

The requested access levels to entries by SecurityInformation can be a combination of the following:

§ Read Control (requested if any of the bits in SecurityInformation is set by an OR operation with GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, and/or OWNER_SECURITY_INFORMATION)

§ Request for access to set or get SACL (requested if one of the bits in SecurityInformation is set by an OR operation with SACL_SECURITY_INFORMATION)

For more information, see the description of the SECURITY_INFORMATION bit flags.

pSecurityDescriptor: A pointer to a SECURITY_DESCRIPTOR, as specified in [MS-DTYP] section 2.

lpdwBufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) value that indicates the size, in bytes, of the pSecurityDescriptor buffer.

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. This error is returned when there is a mismatch between the access level requested (Read control, access to set/get SACL security information or both) through the bit pattern in SecurityInformation and the current authorized level.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The pSecurityDescriptor parameter is NULL. § The value of the SecurityInformation parameter does not conform to the definition of valid bit patterns for this parameter.
ERROR_INVALID_SECURITY_DESCR 0x0000053A	The security descriptor structure is invalid.

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