Funzione DsCrackNamesA (ntdsapi.h)

Articolo
03/08/2023

La funzione DsCrackNames converte una matrice di nomi di oggetti del servizio directory da un formato a un altro. La conversione dei nomi consente alle applicazioni client di eseguire il mapping tra più nomi usati per identificare vari oggetti del servizio directory. Ad esempio, gli oggetti utente possono essere identificati da nomi di account SAM (Domain\UserName), user principal name (UserName@Domain.com) o nome distinto.

Sintassi

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
);

Parametri

[in] hDS

Contiene un handle del servizio directory ottenuto dalla funzione DSBind o DSBindWithCred. Se i flag contengono DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS può essere NULL.

[in] flags

Contiene uno o più valori di DS_NAME_FLAGS usati per determinare come verrà interrotta la sintassi del nome.

[in] formatOffered

Contiene uno dei valori di DS_NAME_FORMAT che identifica il formato dei nomi di input.

Il valore DS_LIST_NCS può essere passato anche per questo parametro. In questo modo DsCrackNames restituisce i nomi distinti di tutti i contesti di denominazione nella foresta corrente. Il parametro formatDesired viene ignorato . cNames deve essere almeno uno e tutte le stringhe in rpNames devono avere una lunghezza maggiore di zero caratteri. Il contenuto delle stringhe rpNames viene ignorato.

NotaDS_LIST_NCS non è definito in un file di intestazione pubblicato. Per usare questo valore, definirlo nel formato esatto illustrato di seguito.

#ifndef DS_LIST_NCS
    #define DS_LIST_NCS 0xfffffff6
#endif

[in] formatDesired

Contiene uno dei valori DS_NAME_FORMAT che identifica il formato dei nomi di output. Il valore DS_SID_OR_SID_HISTORY_NAME non è supportato.

[in] cNames

Contiene il numero di elementi nella matrice rpNames .

[in] rpNames

Puntatore a una matrice di puntatori a stringhe con terminazione null che contengono nomi da convertire.

[out] ppResult

Puntatore a un valore PDS_NAME_RESULT che riceve una struttura DS_NAME_RESULT contenente i nomi convertiti. Il chiamante deve liberare questa memoria, quando non è più necessario, chiamando DsFreeNameResult.

Valore restituito

Restituisce un valore di errore Win32, un valore di errore RPC o uno dei seguenti.

Commenti

L'esito positivo della richiesta di conversione dei nomi dipende dalla posizione in cui è associato il client. I client si associano a istanze specifiche del servizio directory usando una variante di DsBind. Se associato a un catalogo globale, l'ambito del mapping dei nomi è l'intera foresta. Se non è associato a un catalogo globale, l'ambito del mapping dei nomi è il dominio non coperto da un catalogo globale per tale controller di dominio. Se non è associato a un catalogo globale e non viene trovato un nome, ma il nome di input identifica in modo ambiguo il proprio dominio e questo dominio si trova nella foresta, i dati restituiti identificano il nome di dominio DNS per il dominio di interesse. I client devono usare questi dati per associare al controller di dominio corretto o al catalogo globale e chiamare di nuovo DsCrackNames con il nuovo handle di associazione.

Il valore restituito da DsCrackNames indica errori quali parametri non validi o memoria insufficiente. Tuttavia, i problemi durante la conversione di singoli nomi vengono segnalati nel membro di stato della struttura DS_NAME_RESULT_ITEM restituiti per ogni nome di input.

Nota Non confondere i valori degli elementi di formato del parametro formatOffered utilizzato dalla funzione DsCrackNames con gli elementi di formato simili definiti nell'enumerazione ADS_NAME_TYPE_ENUM utilizzata dall'interfaccia IADsNameTranslate . I due set di formati di elementi non sono equivalenti e non sono intercambiabili.

Nota

L'intestazione ntdsapi.h definisce DsCrackNames come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	ntdsapi.h
Libreria	Ntdsapi.lib
DLL	Ntdsapi.dll