TRUSTEE_W structure (accctrl.h)

The TRUSTEE structure identifies the user account, group account, or logon session to which an access control entry (ACE) applies. The structure can use a name or a security identifier (SID) to identify the trustee.

Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to identify the logon account associated with the access control or audit control information in an EXPLICIT_ACCESS structure.

Syntax

typedef struct _TRUSTEE_W {
  struct _TRUSTEE_W          *pMultipleTrustee;
  MULTIPLE_TRUSTEE_OPERATION MultipleTrusteeOperation;
  TRUSTEE_FORM               TrusteeForm;
  TRUSTEE_TYPE               TrusteeType;
  union {
    LPWSTR             ptstrName;
    SID                *pSid;
    OBJECTS_AND_SID    *pObjectsAndSid;
    OBJECTS_AND_NAME_W *pObjectsAndName;
  };
  LPWCH                      ptstrName;
} TRUSTEE_W, *PTRUSTEE_W, TRUSTEEW, *PTRUSTEEW;

Members

pMultipleTrustee

A pointer to a TRUSTEE structure that identifies a server account that can impersonate the user identified by the ptstrName member. This member is not currently supported and must be NULL.

MultipleTrusteeOperation

A value of the MULTIPLE_TRUSTEE_OPERATION enumeration type. Currently, this member must be NO_MULTIPLE_TRUSTEE.

TrusteeForm

A value from the TRUSTEE_FORM enumeration type that indicates the type of data pointed to by the ptstrName member.

TrusteeType

A value from the TRUSTEE_TYPE enumeration type that indicates whether the trustee is a user account, a group account, or an unknown account type.

ptstrName

A pointer to a buffer that identifies the trustee and, optionally, contains information about object-specific ACEs. The type of data depends on the value of the TrusteeForm member.

This member can be one of the following values.

Value Meaning
TRUSTEE_IS_NAME
A pointer to a null-terminated string that contains the name of the trustee.
TRUSTEE_IS_OBJECTS_AND_NAME
A pointer to an OBJECTS_AND_NAME structure that contains the name of the trustee and the names of the object types in an object-specific ACE.
TRUSTEE_IS_OBJECTS_AND_SID
A pointer to an OBJECTS_AND_SID structure that contains the SID of the trustee and the GUIDs of the object types in an object-specific ACE.
TRUSTEE_IS_SID
Pointer to the SID of the trustee.

pSid

pObjectsAndSid

pObjectsAndName

Remarks

A trustee name can have any of the following formats:

  • A fully qualified name, such as "g:\remotedir\abc".
  • A domain account, such as "domain1\xyz".
  • One of the predefined group names, such as "EVERYONE" or "GUEST".
  • One of the following special names.
    Name Meaning
    CREATOR GROUP The CREATOR_GROUP SID is a SID used in inheritable ACEs. When a new object is created, the system replaces this SID with the primary group SID of the user who created the object.
    CREATOR OWNER The CREATOR_OWNER SID is a SID used in inheritable ACEs. When a new object is created, the system replaces this SID with the SID of the user who created the object.
    CURRENT_USER The owner of the calling thread or process.
     
A trustee SID can be any user or group SID. It can also be any of the universal, well-known SIDs. For more information, see Security Identifiers.

Note

The accctrl.h header defines TRUSTEE_ as an alias which 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 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]
Header accctrl.h

See also

ACL

EXPLICIT_ACCESS

GetExplicitEntriesFromAcl

MULTIPLE_TRUSTEE_OPERATION

OBJECTS_AND_NAME

OBJECTS_AND_SID

SID

SetEntriesInAcl

TRUSTEE_FORM

TRUSTEE_TYPE