Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

GetPrivateObjectSecurity function

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

Syntax


BOOL WINAPI GetPrivateObjectSecurity(
  _In_       PSECURITY_DESCRIPTOR ObjectDescriptor,
  _In_       SECURITY_INFORMATION SecurityInformation,
  _Out_opt_  PSECURITY_DESCRIPTOR ResultantDescriptor,
  _In_       DWORD DescriptorLength,
  _Out_      PDWORD ReturnLength
);

Parameters

ObjectDescriptor [in]

A 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 parameter can be a combination of the SECURITY_INFORMATION bit flags.

ResultantDescriptor [out, optional]

A 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]

A 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 value

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

This function is intended for use by resource managers only. To implement the standard access control semantics for updating security descriptors, a resource manager should verify that the following conditions are met before calling GetPrivateObjectSecurity:

  • If the object's owner is being set, the calling process must have either WRITE_OWNER permission or be the object's owner.
  • If the object's discretionary access control list is being set, the calling process must have either WRITE_DAC permission or be the object's owner.
  • If the object's system access control list is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

If the preceding conditions are not met, a call to this function does not fail, however, standard access policy is not enforced.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

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

 

 

Community Additions

Show:
© 2014 Microsoft