Funzione NetServerEnum (lmserver.h)
La funzione NetServerEnum elenca tutti i server del tipo specificato visibili in un dominio.
Sintassi
NET_API_STATUS NET_API_FUNCTION NetServerEnum(
[in, optional] LMCSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in] DWORD servertype,
[in, optional] LMCSTR domain,
[in, out, optional] LPDWORD resume_handle
);
Parametri
[in, optional] servername
Riservati; deve essere NULL.
[in] level
Livello di informazioni dei dati richiesti. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Restituire i nomi dei server e le informazioni sulla piattaforma. Il parametro bufptr punta a una matrice di strutture SERVER_INFO_100 . |
|
Restituire nomi di server, tipi e dati associati. Il parametro bufptr punta a una matrice di strutture SERVER_INFO_101 . |
[out] bufptr
Puntatore al buffer che riceve i dati. Il formato di questi dati dipende dal valore del parametro di livello . Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree . Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.
[in] prefmaxlen
Lunghezza massima preferita dei dati restituiti, in byte. Se si specifica MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Se si specifica un altro valore in questo parametro, può limitare il numero di byte restituiti dalla funzione. Se le dimensioni del buffer non sono sufficienti per contenere tutte le voci, la funzione restituisce ERROR_MORE_DATA. Per altre informazioni, vedere Buffer delle funzioni di gestione della rete e lunghezze del buffer delle funzioni di gestione della rete.
[out] entriesread
Puntatore a un valore che riceve il conteggio degli elementi effettivamente enumerati.
[out] totalentries
Puntatore a un valore che riceve il numero totale di server e workstation visibili nella rete. Si noti che le applicazioni devono considerare questo valore solo come hint.
[in] servertype
Valore che filtra le voci del server da restituire dall'enumerazione. Questo parametro può essere una combinazione dei valori seguenti definiti nel file di intestazione Lmserver.h .
[in, optional] domain
Puntatore a una stringa costante che specifica il nome del dominio per il quale deve essere restituito un elenco di server. Il nome di dominio deve essere un nome di dominio NetBIOS ,ad esempio Microsoft. La funzione NetServerEnum non supporta nomi in stile DNS, ad esempio microsoft.com.
Se questo parametro è NULL, il dominio primario è implicito.
[in, out, optional] resume_handle
Riservati; deve essere impostato su zero.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NERR_Success.
Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti:
| Codice/valore restituito | Descrizione |
|---|---|
|
Accesso negato. |
|
Parametro non corretto. |
|
Sono disponibili altre voci. Specificare un buffer sufficientemente grande per ricevere tutte le voci. |
|
Nessun server browser trovato. |
|
La richiesta non è supportata. |
|
Si è verificato un errore remoto senza dati restituiti dal server. |
|
Il servizio server non viene avviato. |
|
Il servizio non è stato avviato. |
|
Il servizio Workstation non è stato avviato. Il servizio workstation locale viene usato per comunicare con un server remoto di livello inferiore. |
Commenti
La funzione NetServerEnum viene utilizzata per elencare tutti i server del tipo specificato visibili in un dominio. Ad esempio, un'applicazione può chiamare NetServerEnum per elencare solo tutti i controller di dominio o tutti i server che eseguono solo istanze di SQL Server.
Un'applicazione combina le maschere di bit per vari tipi di server nel parametro servertype per elencare diversi tipi. Ad esempio, un valore di SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) combina le maschere di bit per SV_TYPE_WORKSTATION (0x00000001) e SV_TYPE_SERVER (0x00000002).
Se sono necessarie altre informazioni per un server specifico, chiamare la funzione WNetEnumResource .
Per eseguire correttamente la funzione NetServerEnum non è necessaria alcuna appartenenza a gruppi speciali.
Se si specifica il valore SV_TYPE_LOCAL_LIST_ONLY, la funzione NetServerEnum restituisce l'elenco di server gestiti internamente dal browser. Questo significa solo nel master browser (o in un computer che è stato il master browser in passato). Il master browser è il computer che dispone attualmente dei diritti per determinare quali computer possono essere server o workstation nella rete.
Se non sono presenti server che corrispondono ai tipi specificati nel parametro servertype , la funzione NetServerEnum restituisce il parametro bufptr come valori NULL e DWORD a cui puntano i parametri vociread e totalentries vengono impostati su zero.
La funzione NetServerEnum dipende dal servizio browser in esecuzione e installato. Se non viene trovato alcun server browser, NetServerEnum ha esito negativo con ERROR_NO_BROWSER_SERVERS_FOUND.
Se si esegue la programmazione per Active Directory, è possibile chiamare determinati metodi ADSI (Active Directory Service Interface) per ottenere la stessa funzione che è possibile ottenere chiamando le funzioni del server di gestione di rete. Per altre informazioni, vedere IADsComputer.
Esempio
Nell'esempio di codice seguente viene illustrato come elencare tutti i server visibili in un dominio con una chiamata alla funzione NetServerEnum . L'esempio chiama NetServerEnum, specificando il livello di informazioni 101 ( SERVER_INFO_101). Se vengono trovati server, il codice di esempio scorre le voci e stampa i dati recuperati. Se il server è un controller di dominio, identifica il server come controller di dominio primario (PDC) o un controller di dominio di backup. L'esempio stampa anche il numero totale di voci disponibili e un suggerimento sul numero di voci effettivamente enumerate, avvisando l'utente se tutte le voci non sono state enumerate. Infine, l'esempio libera la memoria allocata per il buffer delle informazioni.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t * argv[])
{
LPSERVER_INFO_101 pBuf = NULL;
LPSERVER_INFO_101 pTmpBuf;
DWORD dwLevel = 101;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwTotalCount = 0;
DWORD dwServerType = SV_TYPE_SERVER; // all servers
DWORD dwResumeHandle = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
LPWSTR pszDomainName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
exit(1);
}
// The request is not for the primary domain.
//
if (argc == 2)
pszDomainName = argv[1];
//
// Call the NetServerEnum function to retrieve information
// for all servers, specifying information level 101.
//
nStatus = NetServerEnum(pszServerName,
dwLevel,
(LPBYTE *) & pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
dwServerType,
pszDomainName,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
if ((pTmpBuf = pBuf) != NULL) {
//
// Loop through the entries and
// print the data for all server types.
//
for (i = 0; i < dwEntriesRead; i++) {
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL) {
fprintf(stderr, "An access violation has occurred\n");
break;
}
printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
wprintf(L"\tName: %s\n", pTmpBuf->sv101_name);
printf("\tVersion: %d.%d\n",
pTmpBuf->sv101_version_major,
pTmpBuf->sv101_version_minor);
printf("\tType: %d", pTmpBuf->sv101_type);
//
// Check to see if the server is a domain controller;
// if so, identify it as a PDC or a BDC.
//
if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
wprintf(L" (PDC)");
else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
wprintf(L" (BDC)");
printf("\n");
//
// Also print the comment associated with the server.
//
wprintf(L"\tComment: %s\n\n", pTmpBuf->sv101_comment);
pTmpBuf++;
dwTotalCount++;
}
// Display a warning if all available entries were
// not enumerated, print the number actually
// enumerated, and the total number available.
if (nStatus == ERROR_MORE_DATA) {
fprintf(stderr, "\nMore entries available!!!\n");
fprintf(stderr, "Total entries: %d", dwTotalEntries);
}
printf("\nEntries enumerated: %d\n", dwTotalCount);
} else {
printf("No servers were found\n");
printf("The buffer (bufptr) returned was NULL\n");
printf(" entriesread: %d\n", dwEntriesRead);
printf(" totalentries: %d\n", dwEntriesRead);
}
} else
fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | lmserver.h (include Lm.h) |
| Libreria | Netapi32.lib |
| DLL | Netapi32.dll |