NetConnectionEnum-Funktion (lmshare.h)

Listet alle Verbindungen auf, die mit einer freigegebenen Ressource auf dem Server hergestellt werden, oder alle Verbindungen, die von einem bestimmten Computer hergestellt wurden. Wenn mehrere Benutzer diese Verbindung verwenden, ist es möglich, mehr als eine Struktur für dieselbe Verbindung abzurufen, jedoch mit einem anderen Benutzernamen.

Syntax

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

Parameter

[in] servername

Zeiger auf eine Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

Diese Zeichenfolge ist Unicode, wenn _WIN32_WINNT oder FORCE_UNICODE definiert ist.

[in] qualifier

Zeiger auf eine Zeichenfolge, die einen Freigabenamen oder Computernamen für die relevanten Verbindungen angibt. Wenn es sich um einen Freigabenamen handelt, werden alle Verbindungen aufgeführt, die mit diesem Freigabenamen hergestellt werden. Wenn es sich um einen Computernamen handelt (z. B. beginnt er mit zwei umgekehrten Schrägstrichen), listet NetConnectionEnum alle Verbindungen auf, die von diesem Computer mit dem angegebenen Server hergestellt werden.

Diese Zeichenfolge ist Unicode, wenn _WIN32_WINNT oder FORCE_UNICODE definiert ist.

[in] level

Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.

[out] bufptr

Zeiger auf die Adresse des Puffers, der die Informationen empfängt. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab.

Dieser Puffer wird vom System zugewiesen und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die Funktion mit ERROR_MORE_DATA fehlschlägt.

[in] prefmaxlen

Gibt die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes an. Wenn Sie MAX_PREFERRED_LENGTH angeben, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn Sie in diesem Parameter einen anderen Wert angeben, kann die Anzahl der Von der Funktion zurückgegebenen Bytes eingeschränkt werden. Wenn die Puffergröße nicht ausreicht, um alle Einträge aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.

[out] entriesread

Zeiger auf einen Wert, der die Anzahl der tatsächlich aufgelisteten Elemente empfängt.

[out] totalentries

Zeiger auf einen Wert, der die Gesamtanzahl von Einträgen empfängt, die aus der aktuellen Fortsetzenposition aufgezählt worden sein könnten. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in, out] resume_handle

Zeiger auf einen Wert, der ein Resume-Handle enthält, das verwendet wird, um eine vorhandene Verbindungssuche fortzusetzen. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn dieser Parameter NULL ist, wird kein Resume-Handle gespeichert.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode. Eine Liste der Fehlercodes finden Sie unter Systemfehlercodes.

Hinweise

Administrator, Server- oder Druckoperator oder Power User-Gruppenmitgliedschaft ist erforderlich, um die NetConnectionEnum-Funktion erfolgreich ausführen zu können.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Die Verbindungen mit einer freigegebenen Ressource mit einem Aufruf der NetConnectionEnum-Funktion aufgelistet werden. Im Beispiel wird NetConnectionEnum aufgerufen, wobei die Informationsebene 1 (CONNECTION_INFO_1) angegeben wird. Wenn Einträge zurückgegeben werden sollen, werden die Werte der coni1_username - und coni1_netname-Member ausgegeben. Wenn keine Einträge zurückgegeben werden sollen, gibt das Beispiel eine entsprechende Nachricht aus. Schließlich gibt das Codebeispiel den Für den Informationspuffer zugewiesenen Arbeitsspeicher frei.

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

Anforderungen

Weitere Informationen

CONNECTION_INFO_0

CONNECTION_INFO_1

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

Netzwerkfreigabefunktionen