GetNamedSecurityInfo

The GetNamedSecurityInfo function retrieves a copy of the security descriptor for an object specified by name.

DWORD GetNamedSecurityInfo(
  LPTSTR pObjectName,                        // object name
  SE_OBJECT_TYPE ObjectType,                 // object type
  SECURITY_INFORMATION SecurityInfo,         // information type
  PSID *ppsidOwner,                          // owner SID
  PSID *ppsidGroup,                          // primary group SID
  PACL *ppDacl,                              // DACL
  PACL *ppSacl,                              // SACL
  PSECURITY_DESCRIPTOR *ppSecurityDescriptor // SD
);

Parameters

pObjectName

[in] Pointer to a null-terminated string that specifies the name of the object from which to retrieve security information. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

ObjectType

[in] Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo

[in] A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values.

Value	Meaning
DACL_SECURITY_INFORMATION	If this flag is set, the ppDacl parameter receives the object's discretionary access-control list (DACL).
GROUP_SECURITY_INFORMATION	If this flag is set, the ppsidGroup parameter receives the SID of the object's primary group.
OWNER_SECURITY_INFORMATION	If this flag is set, the ppsidOwner parameter receives the security identifier (SID) of the object's owner.
SACL_SECURITY_INFORMATION	If this flag is set, the ppSacl parameter receives the object's system access-control list (SACL)..

ppsidOwner

[out] Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID.

ppsidGroup

[out] Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID.

ppDacl

[out] Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL.

ppSacl

[out] Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL.

ppSecurityDescriptor

[out] Pointer to a variable that receives a pointer to the security descriptor of the object. You must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

If the ppsidOwner, ppsidGroup, ppDacl, ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor.

To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant READ_CONTROL access to the caller or the caller must be the owner of the object.

To read the system access-control list (SACL) of the object, the SE_SECURITY_NAME privilege must be enabled for the calling process.

You can use the GetNamedSecurityInfo function with the following types of objects:

• Local or remote files or directories on an NTFS file system
• Local or remote printers
• Local or remote Win32 services
• Network shares
• Registry keys
• Semaphores, events, mutexes, and waitable timers
• File-mapping objects
• Directory service objects

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Aclapi.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Access Control Overview, Access Control Functions, ACL, GetSecurityInfo, LocalFree, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetNamedSecurityInfo, SetSecurityInfo, SID