SetUserObjectSecurity function (winuser.h)

Article
10/13/2021

The SetUserObjectSecurity function sets the security of a user object. This can be, for example, a window or a DDE conversation.

Syntax

BOOL SetUserObjectSecurity(
  [in] HANDLE                hObj,
  [in] PSECURITY_INFORMATION pSIRequested,
  [in] PSECURITY_DESCRIPTOR  pSID
);

Parameters

[in] hObj

A handle to a user object for which security information is set.

[in] pSIRequested

A pointer to a value that indicates the components of the security descriptor to set. This parameter can be a combination of the following values.

Value	Meaning
DACL_SECURITY_INFORMATION	Sets the discretionary access control list (DACL) of the object. The handle specified by hObj must have WRITE_DAC access, or the calling process must be the owner of the object.
GROUP_SECURITY_INFORMATION	Sets the primary group security identifier (SID) of the object.
OWNER_SECURITY_INFORMATION	Sets the SID of the owner of the object. The handle specified by hObj must have WRITE_OWNER access, or the calling process must be the owner of the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled.
SACL_SECURITY_INFORMATION	Sets the system access control list (SACL) of the object. The handle specified by hObj must have ACCESS_SYSTEM_SECURITY access. To obtain ACCESS_SYSTEM_SECURITY access Enable the SE_SECURITY_NAME privilege in the current access token of the caller. Open the handle for ACCESS_SYSTEM_SECURITY access. Disable the privilege.

[in] pSID

A pointer to a SECURITY_DESCRIPTOR structure that contains the new security information.

This buffer must be aligned on a 4-byte boundary.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

The SetUserObjectSecurity function applies changes specified in a security descriptor to the security descriptor assigned to a user object. The security descriptor of the object must be in self-relative form. If necessary, this function allocates additional memory to increase the size of the security descriptor.

Examples

For an example that uses this function, see Starting an Interactive Client Process.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll