funzione ldap_init (winldap.h)
La funzione ldap_init inizializza una sessione con un server LDAP.
Sintassi
WINLDAPAPI LDAP *LDAPAPI ldap_init(
[in] PSTR HostName,
[in] ULONG PortNumber
);
Parametri
[in] HostName
Puntatore a una stringa con terminazione null contenente un nome di dominio o un elenco separato da spazio di nomi host o stringhe punteggiate che rappresentano l'indirizzo IP degli host che eseguono un server LDAP a cui connettersi. Ogni nome host nell'elenco può includere un numero di porta facoltativo separato dall'host stesso con due punti (:). Per altre informazioni sull'uso dell'opzione LDAP_OPT_AREC_EXCLUSIVE durante la connessione ai server Active Directory, vedere la sezione Osservazioni.
[in] PortNumber
Contiene il numero di porta TCP a cui connettersi. Impostare su LDAP_PORT per ottenere la porta predefinita 389. Questo parametro viene ignorato se un nome host include un numero di porta.
Valore restituito
Se la funzione ha esito positivo, restituisce un handle di sessione, sotto forma di puntatore a una struttura di dati LDAP . L'handle di sessione deve essere liberato con una chiamata a ldap_unbind quando non è più necessario.
Se la funzione ha esito negativo, restituisce NULL. Usare LdapGetLastError per recuperare il codice di errore.
Commenti
Chiamare ldap_init per creare un blocco di connessione a un server LDAP. A differenza di ldap_open, una chiamata a ldap_init non apre la connessione. È possibile chiamare ldap_connect in modo esplicito per avere il contatto della libreria con il server. Questo è utile quando si vuole specificare un timeout locale in cui si chiamerebbe ldap_set_option, con il blocco di connessione da ldap_init, prima di chiamare ldap_connect. In genere, questa chiamata non è necessaria perché la prima funzione di operazione che richiede chiamate di connessione aperte ldap_connect internamente se non è stata chiamata.
La funzione alloca una struttura di dati LDAP per mantenere i dati sullo stato per la sessione e restituisce un handle a questa struttura. Passare questo handle alle chiamate di funzione LDAP durante la sessione.
Il parametro HostName può essere NULL, in cui il tempo di esecuzione tenta di trovare il server LDAP "predefinito". Quando viene chiamato ldap_connect , gli host vengono tentati nell'ordine elencato, arrestandosi con la prima connessione riuscita. Per i server Active Directory, la funzione DsGetDcName può essere usata per ottenere il nome del server, che può quindi essere passato come parametro HostName anziché usare NULL.
Anche quando la funzione ldap_set_option viene usata per impostare l'opzione LDAP_OPT_GETDSNAME_FLAGS , che a sua volta specifica i flag che verranno passati a DsGetDCName per individuare il controller di dominio a cui connettersi. Il client LDAP passa anche il flag di DS_ONLY_LDAP_NEEDED a DsGetDCName oltre ai flag che LDAP_OPT_GETDSNAME_FLAGS specifica.
Se NULL viene passato per il parametro HostName e il computer chiamante è membro di un dominio Di Active Directory, il runtime cercherà un controller di dominio nel dominio in cui il computer corrente è un membro durante il tentativo di connessione.
Se NULL viene passato per il parametro HostName e il computer chiamante è un controller di dominio di Active Directory, il runtime cambierà NULL con 127.0.0.1 e si connette al computer locale usando il loopback durante il tentativo di connessione.
Se un nome di dominio di Active Directory viene passato per il parametro HostName , ldap_init troverà il server LDAP "predefinito" in tale dominio.
Se hostName è stato impostato su NULL o sul nome di dominio, si applica la riconnessione automatica. Se il controller di dominio connesso viene interrotto per qualche motivo durante la durata della connessione, LDAP si riconnetterà automaticamente a un altro controller di dominio nel dominio specificato. Questo comportamento può essere disattivato o attivato usando l'opzione di sessione LDAP_OPT_AUTO_RECONNECT , attiva per impostazione predefinita.
Se un nome del server DNS di Active Directory viene passato per il parametro HostName , ldap_set_option deve essere chiamato per impostare il flag di LDAP_OPT_AREC_EXCLUSIVE prima di chiamare qualsiasi funzione LDAP che crea la connessione effettiva. In questo modo viene eseguita una ricerca di record A e viene ignorata la ricerca di record SRV durante la risoluzione del nome host. Nel caso di una succursale con una connessione con accesso esterno, l'uso della ricerca A-Record può evitare di forzare il dialup per eseguire query su un server DNS remoto per i record SRV durante la risoluzione dei nomi.
Se un numero di porta catalogo globale viene passato a ldap_init come uno degli argomenti, il nome HostName passato per tale numero di porta deve essere il nome della foresta per la chiamata sottostante a DsGetDcName() per trovare correttamente la GC nell'organizzazione.
Multithreading: una chiamata a ldap_init è thread safe.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista |
| Server minimo supportato | Windows Server 2008 |
| Piattaforma di destinazione | Windows |
| Intestazione | winldap.h |
| Libreria | Wldap32.lib |
| DLL | Wldap32.dll |