Platform SDK: Access Control

GetPrivateObjectSecurity

The GetPrivateObjectSecurity retrieves information from a private object's security descriptor.

BOOL GetPrivateObjectSecurity(
  PSECURITY_DESCRIPTOR ObjectDescriptor,    // SD
  SECURITY_INFORMATION SecurityInformation, // requested info type
  PSECURITY_DESCRIPTOR ResultantDescriptor, // requested SD info
  DWORD DescriptorLength,                   // size of SD buffer
  PDWORD ReturnLength                       // required buffer size
);

Parameters

ObjectDescriptor
[in] Pointer to a SECURITY_DESCRIPTOR structure. This is the security descriptor to be queried.
SecurityInformation
[in] A set of bit flags that indicate the parts of the security descriptor to retrieve. This value can be a combination of the SECURITY_INFORMATION bit flags.
ResultantDescriptor
[out] Pointer to a buffer that receives a copy of the requested information from the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.
DescriptorLength
[in] Specifies the size, in bytes, of the buffer pointed to by the ResultantDescriptor parameter.
ReturnLength
[out] Pointer to a variable the function sets to zero if the descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable's value is greater than the value of the DescriptorLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application must perform appropriate access/privilege checks and audits before calling this function.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GetFileSecurity, GetKernelObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetPrivateObjectSecurity