Fonction AccessCheckByTypeResultList (securitybaseapi.h)

Article
08/25/2023

La fonction AccessCheckByTypeResultList détermine si un descripteur de sécurité accorde un ensemble spécifié de droits d’accès au client identifié par un jeton d’accès. La fonction peut case activée l’accès du client à une hiérarchie d’objets, comme un objet, ses jeux de propriétés et ses propriétés. La fonction signale les droits d’accès accordés ou refusés à chaque type d’objet dans la hiérarchie. En règle générale, les applications serveur utilisent cette fonction pour case activée l’accès à un objet privé.

Syntaxe

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

Paramètres

[in] pSecurityDescriptor

Pointeur vers une structure SECURITY_DESCRIPTOR sur laquelle l’accès est vérifié.

[in, optional] PrincipalSelfSid

Pointeur vers un identificateur de sécurité (SID). Si le descripteur de sécurité est associé à un objet qui représente un principal (par exemple, un objet utilisateur), le paramètre PrincipalSelfSid doit être le SID de l’objet. Lors de l’évaluation de l’accès, ce SID remplace logiquement le SID dans toute entrée de contrôle d’accès (ACE) qui contient le sid bien connu PRINCIPAL_SELF (S-1-5-10). Pour plus d’informations sur les SID connus, consultez SiDs connus.

Si l’objet protégé ne représente pas de principal, définissez ce paramètre sur NULL.

[in] ClientToken

Handle à un jeton d’emprunt d’identité qui représente le client qui tente d’obtenir l’accès. Le handle doit avoir TOKEN_QUERY accès au jeton ; sinon, la fonction échoue avec ERROR_ACCESS_DENIED.

[in] DesiredAccess

Masque d’accès qui spécifie les droits d’accès à case activée. Ce masque doit avoir été mappé par la fonction MapGenericMask pour ne contenir aucun droit d’accès générique.

Si ce paramètre est MAXIMUM_ALLOWED, la fonction définit les masques d’accès dans le tableau GrantedAccess pour indiquer les droits d’accès maximum du client à chaque élément de la liste des types d’objets.

[in, out, optional] ObjectTypeList

Pointeur vers un tableau de structures OBJECT_TYPE_LIST qui identifient la hiérarchie des types d’objets pour lesquels case activée accès. Chaque élément du tableau spécifie un GUID qui identifie le type d’objet et une valeur qui indique le niveau du type d’objet dans la hiérarchie des types d’objets. Le tableau ne doit pas avoir deux éléments avec le même GUID.

Le tableau doit avoir au moins un élément. Le premier élément du tableau doit se trouver au niveau zéro et identifier l’objet lui-même. Le tableau ne peut avoir qu’un seul élément de niveau zéro. Le deuxième élément est un sous-objet, tel qu’un jeu de propriétés, au niveau 1. Après chaque entrée de niveau 1 se trouvent des entrées subordonnées pour les sous-objets de niveau 2 à 4. Par conséquent, les niveaux des éléments du tableau peuvent être {0, 1, 2, 2, 1, 2, 3}. Si la liste des types d’objets n’est pas en ordre, AccessCheckByTypeResultList échoue et GetLastError retourne ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Nombre d’éléments dans le tableau ObjectTypeList . Il s’agit également du nombre d’éléments dans les tableaux indiqués par les paramètres GrantedAccessList et AccessStatusList .

[out] GenericMapping

Pointeur vers la structure GENERIC_MAPPING associée à l’objet pour lequel l’accès est vérifié.

[out, optional] PrivilegeSet

Pointeur vers une structure de PRIVILEGE_SET qui reçoit les privilèges utilisés pour effectuer la validation de l’accès. Si aucun privilège n’a été utilisé, la fonction définit le membre PrivilegeCount sur zéro.

[in, out] PrivilegeSetLength

Taille, en octets, de la mémoire tampon pointée vers le paramètre PrivilegeSet .

[out] GrantedAccessList

Pointeur vers un tableau de masques d’accès. La fonction définit chaque masque d’accès pour indiquer les droits d’accès accordés à l’élément correspondant dans la liste des types d’objets. Si la fonction échoue, elle ne définit pas les masques d’accès.

[out] AccessStatusList

Pointeur vers un tableau de codes status pour les éléments correspondants dans la liste des types d’objets. La fonction définit un élément sur zéro pour indiquer la réussite ou une valeur différente de zéro pour indiquer l’erreur spécifique pendant l’case activée d’accès. Si la fonction échoue, elle ne définit aucun des éléments du tableau.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour plus d’informations, consultez Vue d’ensemble du fonctionnement d’AccessCheck .

La fonction AccessCheckByTypeResultList compare le descripteur de sécurité spécifié au jeton d’accès spécifié et indique, dans le paramètre AccessStatusList , si l’accès est accordé ou refusé pour chacun des éléments de la liste des types d’objets.

Le tableau ObjectTypeList ne représente pas nécessairement l’ensemble de l’objet défini. Il représente plutôt le sous-ensemble de l’objet auquel case activée accès. Pour instance, pour case activée l’accès à deux propriétés dans un jeu de propriétés, spécifiez une liste de types d’objets avec quatre éléments : l’objet lui-même au niveau zéro, la propriété définie au niveau 1 et les deux propriétés au niveau 2.

La fonction AccessCheckByTypeResultList évalue les AÉC qui s’appliquent à l’objet lui-même et les AOC spécifiques à l’objet pour les types d’objets répertoriés dans le tableau ObjectTypeList . La fonction ignore les ADE spécifiques aux objets pour les types d’objets non répertoriés dans le tableau ObjectTypeList . Ainsi, les résultats retournés pour l’élément zéro dans le paramètre AccessStatusList indiquent l’accès autorisé au sous-ensemble de l’objet défini par le paramètre ObjectTypeList , et non à l’objet entier.

Pour plus d’informations sur la façon dont une hiérarchie d’ACRE contrôle l’accès à un objet et à ses sous-objets, consultez ADE pour contrôler l’accès aux propriétés d’un objet.

Si la liste de contrôle d’accès discrétionnaire (DACL) du descripteur de sécurité est NULL, la fonction accorde l’accès demandé à tous les éléments de la liste de types d’objets.

Si le descripteur de sécurité ne contient pas de SID de propriétaire et de groupe, AccessCheckByTypeResultList échoue avec ERROR_INVALID_SECURITY_DESCR.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	securitybaseapi.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll