DsCrackNamesA, fonction (ntdsapi.h)

Article
08/25/2023

La fonction DsCrackNames convertit un tableau de noms d’objets de service d’annuaire d’un format à un autre. La conversion de noms permet aux applications clientes de mapper entre les noms multiples utilisés pour identifier différents objets de service d’annuaire. Par exemple, les objets utilisateur peuvent être identifiés par des noms de compte SAM (Domain\UserName), un nom d’utilisateur principal (UserName@Domain.com) ou un nom unique.

Syntaxe

NTDSAPI DWORD DsCrackNamesA(
  [in]  HANDLE           hDS,
  [in]  DS_NAME_FLAGS    flags,
  [in]  DS_NAME_FORMAT   formatOffered,
  [in]  DS_NAME_FORMAT   formatDesired,
  [in]  DWORD            cNames,
  [in]  const LPCSTR     *rpNames,
  [out] PDS_NAME_RESULTA *ppResult
);

Paramètres

[in] hDS

Contient un handle de service d’annuaire obtenu à partir de la fonction DSBind ou DSBindWithCred . Si les indicateurscontiennent DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS peut avoir la valeur NULL.

[in] flags

Contient une ou plusieurs des valeurs DS_NAME_FLAGS utilisées pour déterminer la façon dont la syntaxe de nom sera fissurée.

[in] formatOffered

Contient l’une des valeurs DS_NAME_FORMAT qui identifient le format des noms d’entrée.

La valeur DS_LIST_NCS peut également être passée pour ce paramètre. Cela amène DsCrackNames à renvoyer les noms uniques de tous les contextes de nommage dans la forêt actuelle. Le paramètre formatDesired est ignoré. cNames doit être au moins une et toutes les chaînes dans rpNames doivent avoir une longueur supérieure à zéro caractères. Le contenu des chaînes rpNames est ignoré.

NotezDS_LIST_NCS n’est pas défini dans un fichier d’en-tête publié. Pour utiliser cette valeur, définissez-la dans le format exact indiqué ci-dessous.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Contient l’une des valeurs DS_NAME_FORMAT qui identifient le format des noms de sortie. La valeur DS_SID_OR_SID_HISTORY_NAME n’est pas prise en charge.

[in] cNames

Contient le nombre d’éléments dans le tableau rpNames .

[in] rpNames

Pointeur vers un tableau de pointeurs vers des chaînes terminées par un caractère Null qui contiennent des noms à convertir.

[out] ppResult

Pointeur vers une valeur PDS_NAME_RESULT qui reçoit une structure DS_NAME_RESULT qui contient les noms convertis. L’appelant doit libérer cette mémoire, quand elle n’est plus nécessaire, en appelant DsFreeNameResult.

Valeur retournée

Retourne une valeur d’erreur Win32, une valeur d’erreur RPC ou l’une des valeurs suivantes.

Remarques

La réussite de la demande de conversion de nom dépend de l’endroit où le client est lié. Les clients se lient à des instances spécifiques du service d’annuaire à l’aide d’une variante de DsBind. S’il est lié à un catalogue global, l’étendue du mappage de noms est la forêt entière. S’il n’est pas lié à un catalogue global, l’étendue du mappage de noms est le domaine non couvert par un catalogue global pour ce contrôleur de domaine. S’il n’est pas lié à un catalogue global et qu’un nom est introuvable, mais que le nom d’entrée identifie sans ambiguïté son domaine et que ce domaine se trouve dans la forêt, les données de retour identifient le nom de domaine DNS pour le domaine d’intérêt. Les clients sont censés utiliser ces données pour établir une liaison avec le contrôleur de domaine ou le catalogue global approprié et appeler à nouveau DsCrackNames avec le nouveau handle de liaison.

La valeur de retour de DsCrackNames indique des erreurs telles que des paramètres non valides ou une mémoire insuffisante. Toutefois, des problèmes de conversion de noms individuels sont signalés dans le status membre de la structure DS_NAME_RESULT_ITEM retournée pour chaque nom d’entrée.

Note Ne confondez pas les valeurs des éléments de format du paramètre formatOffered utilisé par la fonction DsCrackNames avec les éléments de format de même nom définis dans l’énumération ADS_NAME_TYPE_ENUM utilisée par l’interface IADsNameTranslate . Les deux ensembles de formats d’élément ne sont pas équivalents et ne sont pas interchangeables.

Notes

L’en-tête ntdsapi.h définit DsCrackNames en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	ntdsapi.h
Bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll