3.1.4.1.59 FAX_GetSecurityEx (Opnum 81)

The FAX_GetSecurityEx (Opnum 81) method is called by the clients to retrieve information about the fax security descriptor from the fax server.<134>

Protocol version FAX_API_VERSION_3 (0x00030000) fax servers SHOULD fail this call by returning ERROR_NOT_SUPPORTED (0x00000032). The fax client SHOULD NOT call this method if the protocol version reported by the server is FAX_API_VERSION_3 (0x00030000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10). The fax client SHOULD call the FAX_GetSecurityEx2 (section 3.1.4.1.60) method instead.

The server MUST validate that the client's fax user account has access to retrieve security information. On success, the server MUST return the fax security descriptor in pSecurityDescriptor.

The client SHOULD free pSecurityDescriptor.

 error_status_t FAX_GetSecurityEx(
   [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 only 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

pSecurityDescriptor: A pointer to a SECURITY_DESCRIPTOR.

lpdwBufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) value that indicates the size 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 code is returned if any of the following conditions occur: § The client's fax user account does not have READ_CONTROL access but the requesting SecurityInformation parameter contains one of these flags: GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or OWNER_SECURITY_INFORMATION. § The client's fax user account does not have ACCESS_SYSTEM_SECURITY but the SecurityInformation contains the flag SACL_SECURITY_INFORMATION.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This is returned when the pSecurityDescriptor parameter is NULL.
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].