NetServerTransportEnum-Funktion (lmserver.h)

Artikel
02/28/2024

Die NetServerTransportEnum-Funktion stellt Informationen zu Transportprotokollen bereit, die vom Server verwaltet werden.

Syntax

NET_API_STATUS NET_API_FUNCTION NetServerTransportEnum(
  [in]      LMSTR   servername,
  [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.

[in] level

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

Wert	Bedeutung
0	Gibt Informationen zum Transportprotokoll zurück, einschließlich Name, Adresse und Standort im Netzwerk. Der bufptr-Parameter verweist auf ein Array von SERVER_TRANSPORT_INFO_0 Strukturen.
1	Gibt Informationen zum Transportprotokoll zurück, einschließlich Name, Adresse, Netzwerkstandort und Domäne. Der bufptr-Parameter verweist auf ein Array von SERVER_TRANSPORT_INFO_1 Strukturen.

[out] bufptr

Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des level-Parameters ab. Dieser Puffer wird vom System zugeordnet 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 er die Anzahl der Bytes einschränken, die die Funktion zurückgibt. 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 aufgezählten Elemente empfängt.

[out] totalentries

Zeiger auf einen Wert, der die Gesamtzahl der Einträge empfängt, die aus der aktuellen Position des Lebenslaufs hätten aufgezählt werden können. 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 Servertransportsuche fortzusetzen. Das Handle sollte beim ersten Aufruf null 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, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Rückgabecode	Beschreibung
ERROR_INVALID_LEVEL	Der für den level-Parameter angegebene Wert ist ungültig.
ERROR_MORE_DATA	Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen.
ERROR_NOT_ENOUGH_MEMORY	Nicht genügend Arbeitsspeicher ist verfügbar.
NERR_BufTooSmall	Der bereitgestellte Puffer ist zu klein.

Hinweise

Nur authentifizierte Benutzer können diese Funktion erfolgreich aufrufen. Windows XP/2000: Für die erfolgreiche Ausführung dieser Funktion ist keine spezielle Gruppenmitgliedschaft erforderlich.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Mithilfe eines Aufrufs der NetServerTransportEnum-Funktion Informationen zu Transportprotokollen abgerufen werden, die vom Server verwaltet werden. Im Beispiel wird NetServerTransportEnum aufgerufen, wobei die Informationsebene 0 ( SERVER_TRANSPORT_INFO_0) angegeben wird. Im Beispiel werden der Name jedes Transportprotokolls und die Gesamtzahl der Aufzählungen ausgegeben. Schließlich gibt das Codebeispiel den für den Informationspuffer zugeordneten Arbeitsspeicher frei.

#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_TRANSPORT_INFO_0 pBuf = NULL;
   LPSERVER_TRANSPORT_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;
   DWORD i;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = (LPTSTR) argv[1];
   //
   // Call the NetServerTransportEnum function; specify level 0.
   //
   do // begin do
   {
      nStatus = NetServerTransportEnum(pszServerName,
                                       dwLevel,
                                       (LPBYTE *) &pBuf,
                                       dwPrefMaxLen,
                                       &dwEntriesRead,
                                       &dwTotalEntries,
                                       &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries;
            //  process access errors.
            //
            for (i = 0; i < dwEntriesRead; i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the transport protocol name. 
               //
               wprintf(L"\tTransport: %s\n", pTmpBuf->svti0_transportname);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);

      //
      // Free the allocated buffer.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   // 
   // Continue to call NetServerTransportEnum while 
   //  there are more entries. 
   // 
   }
   while (nStatus == ERROR_MORE_DATA); // end do

   // Check again for an allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of transports enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmserver.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll