DsCrackNamesA, fonction (ntdsapi.h)

Article
11/20/2024

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 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 (Domaine\Nom d’utilisateur), nom d’utilisateur principal (Nom d’utilisateur@Domaine.com) ou 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 indicateurs contient DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS peut être 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 craquelée.

[in] formatOffered

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

La valeur DS_LIST_NCS peut également être passée pour ce paramètre. Cela provoque DsCrackNames retourner 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 de rpNames doivent avoir une longueur supérieure à zéro. Le contenu des chaînes rpNames est ignoré.

RemarqueDS_LIST_NCS n’est pas définie 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 identifie 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 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, lorsqu’elle n’est plus nécessaire, en appelant DsFreeNameResult.

Valeur de retour

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’emplacement où le client est lié. Les clients se lient à des instances spécifiques du service d’annuaire à l’aide d’une variante de DsBind. Si elle est liée à 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 n’est pas trouvé, mais le nom d’entrée identifie sans ambiguïté son domaine et 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 doivent utiliser ces données pour établir une liaison au contrôleur de domaine ou au catalogue global approprié et appeler DsCrackNames à nouveau 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, les problèmes de conversion de noms individuels sont signalés dans l’état membre de la structure DS_NAME_RESULT_ITEM retournée pour chaque nom d’entrée.

Remarque 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 nommés de la même façon que 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.

Note

L’en-tête ntdsapi.h définit DsCrackNames comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista
serveur minimum pris en charge	Windows Server 2008
plateforme cible	Windows
d’en-tête	ntdsapi.h
bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll