GetSecurityInfoEx

[This is preliminary documentation and subject to change.]

The GetSecurityInfoEx function retrieves security information for an object identified by a handle. The function can also retrieve object-specific access-control and audit-control information. GetSecurityInfoEx uses provider-independent access flags, which enables it to retrieve security information for objects on systems other than Windows NT.

DWORD GetSecurityInfoEx(
  HANDLE hObject,      // handle to 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
);
 

Parameters

hObject

A handle to the object from which to retrieve security information.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object identified by the hObject parameter.

SecurityInfo

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
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.

lpProvider

Pointer to a null-terminated string that specifies the name of the provider to handle the request. If this parameter is NULL, the system determines the proper provider to handle the request.

lpProperty

Pointer to a null-terminated string that identifes the type of child object, property set, or property for which to retrieve object-specific access-control and audit-control information. This string can be the display name of the object, or it can be a string representation of the GUID that identifies the object. You can use the UuidToString function to generate a string representation of a GUID.

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.

ppAccessList

Pointer to a variable that receives a pointer to an ACTRL_ACCESS structure. The structure describes discretionary access-control information for the object or for the sub-object identified by the lpProperty parameter. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. Call the LocalFree function to free the returned buffer. This parameter can be NULL if you do not need the DACL information.

ppAuditList

Pointer to a variable that receives a pointer to an ACTRL_AUDIT structure. The structure describes system audit-control information for the object or for the sub-object identified by the lpProperty parameter. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. Call the LocalFree function to free the returned buffer. This parameter can be NULL if you do not need the SACL information.

lppOwner

Pointer to a variable that receives a pointer to a null-terminated string containing the name of the object's owner. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. Call the LocalFree function to free the returned buffer. This parameter can be NULL if you do not need the information.

lppGroup

Pointer to a variable that receives a pointer to a null-terminated string containing the name of the object's primary group. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. Call the LocalFree function to free the returned buffer. This parameter can be NULL if you do not need the information.

Return Values

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.

Remarks

To read the owner, group, or DACL from the object's security descriptor, the calling process must have been granted READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must be the owner of the object or the object's DACL must grant the access.

To read the SACL from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the handle was opened. The proper 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.

Call the LocalFree function to free any pointers returned by the ppAccessList, ppAccessList, lppOwner, or lppOwner parameters.

QuickInfo

  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.

See Also

Access Control Overview, Access Control Functions, ACTRL_ACCESS, ACTRL_AUDIT, ACTRL_PROPERTY_ENTRY, GetNamedSecurityInfoEx, LocalFree, SE_OBJECT_TYPE, SECURITY_INFORMATION, SetNamedSecurityInfoEx, SetSecurityInfoEx