Windows Dev Center

Expand Minimize

GetUserObjectSecurity function

The GetUserObjectSecurity function retrieves security information for the specified user object.

Syntax


BOOL WINAPI GetUserObjectSecurity(
  _In_        HANDLE                hObj,
  _In_        PSECURITY_INFORMATION pSIRequested,
  _Inout_opt_ PSECURITY_DESCRIPTOR  pSD,
  _In_        DWORD                 nLength,
  _Out_       LPDWORD               lpnLengthNeeded
);

Parameters

hObj [in]

A handle to the user object for which to return security information.

pSIRequested [in]

A pointer to a SECURITY_INFORMATION value that specifies the security information being requested.

pSD [in, out, optional]

A pointer to a SECURITY_DESCRIPTOR structure in self-relative format that contains the requested information when the function returns. This buffer must be aligned on a 4-byte boundary.

nLength [in]

The length, in bytes, of the buffer pointed to by the pSD parameter.

lpnLengthNeeded [out]

A pointer to a variable to receive the number of bytes required to store the complete security descriptor. If this variable's value is greater than the value of the nLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer. Otherwise, the entire security descriptor is copied.

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

To read the owner, group, or discretionary access control list (DACL) from the user object's security descriptor, the calling process must have been granted READ_CONTROL access when the handle was opened.

To read the system access control list (SACL) from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the handle was opened. The correct way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.

Examples

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

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winuser.h (include Windows.h)

Library

User32.lib

DLL

User32.dll

See also

Low-level Access Control
Low-level Access Control Functions
CreatePrivateObjectSecurity
GetKernelObjectSecurity
GetPrivateObjectSecurity
SECURITY_DESCRIPTOR
SECURITY_INFORMATION
SetUserObjectSecurity

 

 

Community Additions

ADD
Show:
© 2015 Microsoft