NetConnectionEnum, fonction (lmshare.h)

Article
08/24/2023

Répertorie toutes les connexions établies à une ressource partagée sur le serveur ou toutes les connexions établies à partir d’un ordinateur particulier. Si plusieurs utilisateurs utilisent cette connexion, il est possible d’obtenir plusieurs structures pour la même connexion, mais avec un nom d’utilisateur différent.

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetConnectionEnum(
  [in]      LMSTR   servername,
  [in]      LMSTR   qualifier,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD resume_handle
);

Paramètres

[in] servername

Pointeur vers une chaîne qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

Cette chaîne est Unicode si _WIN32_WINNT ou FORCE_UNICODE est défini.

[in] qualifier

Pointeur vers une chaîne qui spécifie un nom de partage ou un nom d’ordinateur pour les connexions intéressantes. S’il s’agit d’un nom de partage, toutes les connexions établies à ce nom de partage sont répertoriées. S’il s’agit d’un nom d’ordinateur (par exemple, il commence par deux caractères de barre oblique inverse), NetConnectionEnum répertorie toutes les connexions établies à partir de cet ordinateur au serveur spécifié.

Cette chaîne est Unicode si _WIN32_WINNT ou FORCE_UNICODE est défini.

[in] level

Spécifie le niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
0	Retourne les identificateurs de connexion. Le paramètre bufptr est un pointeur vers un tableau de structures CONNECTION_INFO_0 .
1	Retourne les identificateurs de connexion et les informations de connexion. Le paramètre bufptr est un pointeur vers un tableau de structures CONNECTION_INFO_1 .

[out] bufptr

Pointeur vers l’adresse de la mémoire tampon qui reçoit les informations. Le format de ces données dépend de la valeur du paramètre level .

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

Spécifie la longueur maximale par défaut 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 gestion ré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 d’entrées qui auraient pu être énumérées à partir de la position de reprise actuelle. Notez que les applications doivent considérer cette valeur uniquement comme un indicateur.

[in, out] resume_handle

Pointeur vers une valeur qui contient un handle de reprise utilisé pour poursuivre une recherche de connexion existante. Le handle doit être égal à zéro lors du premier appel et laisser inchangé pour les appels suivants. Si ce paramètre a la valeur NULL, aucun handle de reprise n’est stocké.

Valeur retournée

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

Si la fonction échoue, la valeur de retour est un code d’erreur système. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur système.

Notes

L’appartenance à un groupe Administrateur, Serveur, Opérateur d’impression ou Power User est requise pour exécuter correctement la fonction NetConnectionEnum .

Exemples

L’exemple de code suivant montre comment répertorier les connexions établies à une ressource partagée avec un appel à la fonction NetConnectionEnum . L’exemple appelle NetConnectionEnum, en spécifiant le niveau d’informations 1 (CONNECTION_INFO_1). S’il existe des entrées à retourner, il imprime les valeurs des membres coni1_username et coni1_netname . S’il n’y a aucune entrée à retourner, l’exemple imprime un message approprié. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon d’informations.

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <lm.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print user name and network name.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether 
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')  
               printf("No connection to %S from %S\n", 
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else                       
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }        
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmshare.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll