Edit

Share via

GetInheritanceSourceW function (aclapi.h)

  • Article

The GetInheritanceSource function returns information about the source of inherited access control entries (ACEs) in an access control list (ACL).

Syntax

DWORD GetInheritanceSourceW(
  [in]           LPWSTR                pObjectName,
  [in]           SE_OBJECT_TYPE        ObjectType,
  [in]           SECURITY_INFORMATION  SecurityInfo,
  [in]           BOOL                  Container,
  [in, optional] GUID                  **pObjectClassGuids,
  [in]           DWORD                 GuidCount,
  [in]           PACL                  pAcl,
  [in, optional] PFN_OBJECT_MGR_FUNCTS pfnArray,
  [in]           PGENERIC_MAPPING      pGenericMapping,
  [out]          PINHERITED_FROMW      pInheritArray
);

Parameters

[in] pObjectName

A pointer to the name of the object that uses the ACL to be checked.

[in] ObjectType

The type of object indicated by pObjectName. The possible values are SE_FILE_OBJECT, SE_REGISTRY_KEY, SE_DS_OBJECT, and SE_DS_OBJECT_ALL.

[in] SecurityInfo

The type of ACL used with the object. The possible values are DACL_SECURITY_INFORMATION or SACL_SECURITY_INFORMATION.

[in] Container

TRUE if the object is a container object or FALSE if the object is a leaf object. Note that the only leaf object is SE_FILE_OBJECT.

[in, optional] pObjectClassGuids

Optional list of GUIDs that identify the object types or names associated with pObjectName. This may be NULL if the object manager only supports one object class or has no GUID associated with the object class.

[in] GuidCount

Number of GUIDs pointed to by pObjectClassGuids.

[in] pAcl

The ACL for the object.

[in, optional] pfnArray

Reserved. Set this parameter to NULL.

[in] pGenericMapping

The mapping of generic rights to specific rights for the object.

[out] pInheritArray

A pointer to an array of INHERITED_FROM structures that the GetInheritanceSource function fills with the inheritance information. The caller must allocate enough memory for an entry for each ACE in the ACL.

Return value

If the function succeeds, the function returns ERROR_SUCCESS.

If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks

The GetInheritanceSource function allocates memory for the names returned in the INHERITED_FROM structure. When the function has finished using this memory, the calling program must free it by calling FreeInheritedFromArray. Note that the caller must provide memory for the array itself. If the caller allocated the memory, the caller must free that memory after calling FreeInheritedFromArray.

This function does not handle race conditions. If your thread calls this function at the approximate time that another thread changes the object's security descriptor, then this function could fail.

Note

The aclapi.h header defines GetInheritanceSource as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header aclapi.h
Library Advapi32.lib
DLL Advapi32.dll

See also

FreeInheritedFromArray