3.1.4.1.95 FAX_SetSecurityEx2 (Opnum 100)

The FAX_SetSecurityEx2 (Opnum 100) method is called by the client. On success, the server MUST set the fax server's security descriptor.

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 fax client SHOULD call FAX_SetSecurity (section 3.1.4.1.94) instead.

 error_status_t FAX_SetSecurityEx2(
   [in] handle_t hBinding,
   [in] SECURITY_INFORMATION SecurityInformation,
   [in, unique, size_is(dwBufferSize)] 
     const LPBYTE pSecurityDescriptor,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD dwBufferSize
 );

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.

pSecurityDescriptor: A pointer to a SECURITY_DESCRIPTOR ([MS-DTYP] section 2.4.6) structure.

dwBufferSize: A value that indicates the size, in bytes, of the pSecurityDescriptor buffer. The maximum size is FAX_MAX_RPC_BUFFER (section 2.2.82).

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 client's fax user account does not have the access rights required for this operation: § WRITE_OWNER, when the SecurityInformation parameter contains the OWNER_SECURITY_INFORMATION value. § WRITE_DAC, when SecurityInformation contains the GROUP_SECURITY_INFORMATION or DACL_SECURITY_INFORMATION values. § ACCESS_SYSTEM_SECURITY, when SecurityInformation contains the SACL_SECURITY_INFORMATION value.
ERROR_INVALID_DATA 0x0000000D	The data is invalid. The data contained in the buffer specified by the pSecurityDescriptor parameter is not a valid SECURITY_DESCRIPTOR.
ERROR_OUTOFMEMORY 0x0000000E	The fax server cannot allocate sufficient memory for a properly constructed FAX_EVENT_EX_1 (section 2.2.68) structure describing a FAX_EVENT_TYPE_CONFIG event to be signaled to the client. A properly constructed structure has the ConfigType member of the FAX_EVENT_EX_1 set to FAX_CONFIG_TYPE_SECURITY. For more details, see FAX_ClientEventQueueEx (section 3.2.4.3).
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § pSecurityDescriptor is set to a NULL pointer value. § The dwBufferSize parameter is set to 0x00000000. § SecurityInformation is set to a value that does not contain any of the following flags: OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, or SACL_SECURITY_INFORMATION.
ERROR_REGISTRY_CORRUPT 0x000003F7	The registry is corrupted. The structure of one of the files that contains registry data is corrupted, or the system's memory image of the file is corrupted, or the file could not be recovered because the alternate copy or log was absent or corrupted.

The server MUST validate that the client has the following credentials to set security on the server.

Action	Authorization
Set security information on the object owned by the client.	The right to change the owner in the object's security descriptor (WRITE_OWNER).
Set group security information.	The right to modify the DACL in the object's security descriptor (WRITE_DAC).
Set system-wide security information.	The right to modify the SACL in the object's security descriptor (ACCESS_SYSTEM_SECURITY).

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