[This is preliminary documentation and subject to change.]
The GetNamedSecurityInfoEx function retrieves security information for an object identified by a name. The function can also retrieve object-specific access-control and audit-control information. GetNamedSecurityInfoEx uses provider-independent access flags, which enables it to retrieve security information for objects on systems other than Windows NT.
DWORD GetNamedSecurityInfoEx(
LPCTSTR lpObject, // name of the object
SE_OBJECT_TYPE ObjectType,
// type of object
SECURITY_INFORMATION SecurityInfo,
// type of security information to retrieve
LPCTSTR lpProvider, // name of provider to handle request
LPCTSTR lpProperty, // identifies a property, property set, or
// child object
PACTRL_ACCESS *ppAccessList,
// receives a pointer to access-control info
PACTRL_AUDIT *ppAuditList,
// receives a pointer to audit-control info
LPTSTR *lppOwner, // receives the name of the object's owner
LPTSTR *lppGroup // receives the name of the object's primary
// group
);
Value | Meaning |
---|---|
OWNER_SECURITY_INFORMATION | If this flag is set, the lppOwner pointer receives a pointer to a null-terminated string that names the object's owner. |
GROUP_SECURITY_INFORMATION | If this flag is set, the lppGroup pointer receives a pointer to a null-terminated string that names the object's primary group. |
DACL_SECURITY_INFORMATION | If this flag is set, the ppAccessList pointer receives a pointer to a structure that describes DACL information for the object or for the sub-object identified by the lpProperty parameter. |
SACL_SECURITY_INFORMATION | If this flag is set, the ppAuditList pointer receives a pointer to a structure that describes SACL information for the object or for the sub-object identified by the lpProperty parameter. |
If this parameter is NULL, the function retrieves information for the object itself. For object types that do not support object-specific ACEs, set lpProperty to NULL.
If ObjectType specifies SE_DS_OBJECT_ALL, lpProperty is ignored and the function retrieves all the DACL and SACL information for the specified DS object.
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value can be one of the following error codes.
Value | Meaning |
---|---|
ERROR_BAD_PROVIDER | The lpProvider parameter specified an invalid provider name. |
ERROR_INVALID_PARAMETER | An invalid parameter was specified. |
ERROR_NOT_ENOUGH_MEMORY | A memory allocation failed |
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 SACL of the object, the SE_SECURITY_NAME privilege must be enabled for the calling process.
Call the LocalFree function to free any pointers returned by the ppAccessList, ppAccessList, lppOwner, or lppOwner parameters.
Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in aclapi.h.
Import Library: Use advapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
Access Control Overview, Access Control Functions, ACTRL_ACCESS, ACTRL_AUDIT, ACTRL_PROPERTY_ENTRY, GetSecurityInfoEx, LocalFree, SE_OBJECT_TYPE, SECURITY_INFORMATION, SetNamedSecurityInfoEx, SetSecurityInfoEx