Funzione DsCrackNamesA (ntdsapi.h)

Articolo
11/20/2024

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 (Dominio\UserName), nome dell'entità utente (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 flag contiene DS_NAME_FLAG_SYNTACTICAL_ONLY, hDS può essere NULL.

[in] flags

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

[in] formatOffered

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

È anche possibile passare il valore DS_LIST_NCS per questo parametro. In questo modo DsCrackNames restituire i nomi distinti di tutti i contesti di denominazione nella foresta corrente. Il parametro formatDesired viene ignorato. cNames deve essere almeno una e tutte le stringhe in rpNames devono avere una lunghezza maggiore di zero caratteri. Il contenuto della rpNames stringhe viene ignorato.

la notaDS_LIST_NCS non è definita 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 contenenti nomi da convertire.

[out] ppResult

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

Valore restituito

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

Osservazioni

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 univoco il dominio e questo dominio si trova nella foresta, i dati restituiti identificano il nome di dominio DNS per il dominio di interesse. È previsto che i client usino questi dati per eseguire l'associazione al controller di dominio corretto o al catalogo globale e chiamare DsCrackNames di nuovo con il nuovo handle di associazione.

Il valore restituito da DsCrackNames indica errori quali parametri non validi o memoria insufficiente. Tuttavia, i problemi di conversione dei singoli nomi vengono segnalati nello stato membro della struttura DS_NAME_RESULT_ITEM restituito 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 denominati in modo analogo definiti nell'enumerazione ADS_NAME_TYPE_ENUM utilizzata dall'interfaccia IADsNameTranslate . I due set di formati di elemento 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista
server minimo supportato	Windows Server 2008
piattaforma di destinazione	Finestre
intestazione	ntdsapi.h
libreria	Ntdsapi.lib
dll	Ntdsapi.dll