Fonction NetServerEnum (lmserver.h)

La fonction NetServerEnum répertorie tous les serveurs du type spécifié qui sont visibles dans un domaine.

Syntaxe

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

Paramètres

[in, optional] servername

Réservés au; doit avoir la valeur NULL.

[in] level

Niveau d’informations des données demandées. Ce paramètre peut prendre les valeurs suivantes.

[out] bufptr

Pointeur vers la mémoire tampon qui reçoit les données. Le format de ces données dépend de la valeur du paramètre de niveau . Cette mémoire tampon est allouée par le système et doit être libérée à l’aide de la fonction NetApiBufferFree . Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA.

[in] prefmaxlen

Longueur maximale préférée des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour les données. Si vous spécifiez une autre valeur dans ce paramètre, cela peut limiter le nombre d’octets retournés par la fonction. Si la taille de la mémoire tampon est insuffisante pour contenir toutes les entrées, la fonction retourne ERROR_MORE_DATA. Pour plus d’informations, consultez Mémoires tampons de fonction de gestionréseau et Longueurs de mémoire tampon des fonctions de gestion réseau.

[out] entriesread

Pointeur vers une valeur qui reçoit le nombre d’éléments réellement énumérés.

[out] totalentries

Pointeur vers une valeur qui reçoit le nombre total de serveurs et de stations de travail visibles sur le réseau. Notez que les applications doivent considérer cette valeur uniquement comme un indicateur.

[in] servertype

Valeur qui filtre les entrées de serveur à retourner à partir de l’énumération. Ce paramètre peut être une combinaison des valeurs suivantes définies dans le fichier d’en-tête Lmserver.h .

[in, optional] domain

Pointeur vers une chaîne constante qui spécifie le nom du domaine pour lequel une liste de serveurs doit être retournée. Le nom de domaine doit être un nom de domaine NetBIOS (par exemple, microsoft). La fonction NetServerEnum ne prend pas en charge les noms de style DNS (par exemple, microsoft.com).

Si ce paramètre a la valeur NULL, le domaine principal est implicite.

[in, out, optional] resume_handle

Réservés au; doit être défini sur zéro.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants :

Remarques

La fonction NetServerEnum est utilisée pour répertorier tous les serveurs du type spécifié qui sont visibles dans un domaine. Par exemple, une application peut appeler NetServerEnum pour répertorier uniquement tous les contrôleurs de domaine ou tous les serveurs qui exécutent des instances de SQL Server uniquement.

Une application combine les masques de bits pour différents types de serveurs dans le paramètre servertype pour répertorier plusieurs types. Par exemple, une valeur de SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) combine les masques de bits pour les SV_TYPE_WORKSTATION (0x00000001) et les SV_TYPE_SERVER (0x00000002).

Si vous avez besoin d’informations supplémentaires pour un serveur spécifique, appelez la fonction WNetEnumResource .

Aucune appartenance à un groupe spécial n’est requise pour exécuter correctement la fonction NetServerEnum .

Si vous spécifiez la valeur SV_TYPE_LOCAL_LIST_ONLY, la fonction NetServerEnum retourne la liste des serveurs que le navigateur gère en interne. Cela n’a de sens que sur le navigateur master (ou sur un ordinateur qui a été le master navigateur dans le passé). Le navigateur master est l’ordinateur qui dispose actuellement des droits permettant de déterminer quels ordinateurs peuvent être des serveurs ou des stations de travail sur le réseau.

Si aucun serveur ne correspond aux types spécifiés dans le paramètre servertype , la fonction NetServerEnum retourne le paramètre bufptr en tant que valeurs NULL et DWORD pointées par les paramètres entriesread et totalntries sont définis sur zéro.

La fonction NetServerEnum dépend du service de navigateur en cours d’installation et d’exécution. Si aucun serveur de navigateur n’est trouvé, NetServerEnum échoue avec ERROR_NO_BROWSER_SERVERS_FOUND.

Si vous programmez pour Active Directory, vous pouvez peut-être appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir la même fonction que celle que vous pouvez obtenir en appelant les fonctions du serveur d’administration réseau. Pour plus d’informations, consultez IADsComputer.

Exemples

L’exemple de code suivant montre comment répertorier tous les serveurs visibles dans un domaine avec un appel à la fonction NetServerEnum . L’exemple appelle NetServerEnum, en spécifiant le niveau d’informations 101 ( SERVER_INFO_101). Si des serveurs sont trouvés, l’exemple de code effectue une boucle dans les entrées et imprime les données récupérées. Si le serveur est un contrôleur de domaine, il identifie le serveur en tant que contrôleur de domaine principal (PDC) ou contrôleur de domaine de sauvegarde (BDC). L’exemple affiche également le nombre total d’entrées disponibles et un indicateur sur le nombre d’entrées réellement énumérées, indiquant à l’utilisateur si toutes les entrées n’ont pas été énumérées. Enfin, l’exemple libère la mémoire allouée pour la mémoire tampon d’informations.

#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;
}

Configuration requise

Voir aussi

NetQueryDisplayInformation

NetServerDiskEnum

Fonctions de gestion réseau

Vue d’ensemble de la gestion du réseau

SERVER_INFO_100

SERVER_INFO_101

Fonctions serveur