NetConnectionEnum 函式 (lmshare.h)

發行項
08/24/2023

列出與伺服器上共用資源建立的所有連線，或從特定電腦建立的所有連線。如果有一個以上的使用者使用此連線，則可以取得相同連線的多個結構，但有不同的使用者名稱。

語法

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

參數

[in] servername

字串的指標，指定要在其中執行函式之遠端伺服器的 DNS 或 NetBIOS 名稱。如果此參數為 Null，則會使用本機電腦。

如果 已定義_WIN32_WINNT 或 FORCE_UNICODE ，則此字串為 Unicode。

[in] qualifier

字串的指標，指定相關連接的共用名稱或電腦名稱稱。如果是共用名稱，則會列出對該共用名稱所做的所有連線。例如，如果它是電腦名稱稱 (，它會以兩個反斜線字元開頭) ，則 NetConnectionEnum 會列出從該電腦到指定伺服器的所有連線。

如果 已定義_WIN32_WINNT 或 FORCE_UNICODE ，則此字串為 Unicode。

[in] level

指定資料的資訊層級。此參數可以是下列其中一個值。

值	意義
0	傳回連線識別碼。 bufptr參數是CONNECTION_INFO_0結構的陣列指標。
1	傳回連接識別碼和連接資訊。 bufptr參數是CONNECTION_INFO_1結構的陣列指標。

[out] bufptr

接收資訊的緩衝區位址指標。此資料的格式取決於 level 參數的值。

此緩衝區是由系統所配置，必須使用 NetApiBufferFree 函式釋放。請注意，即使函式因 ERROR_MORE_DATA而失敗，您仍必須釋放緩衝區。

[in] prefmaxlen

指定所傳回資料的慣用最大長度，以位元組為單位。如果您指定 MAX_PREFERRED_LENGTH，函式會配置資料所需的記憶體數量。如果您在此參數中指定另一個值，它可以限制函式傳回的位元組數目。如果緩衝區大小不足以保存所有專案，函式會 傳回ERROR_MORE_DATA。如需詳細資訊，請參閱網路管理功能緩衝區和網路管理函式緩衝區長度。

[out] entriesread

值指標，這個值會接收實際列舉的專案計數。

[out] totalentries

值的指標，這個值會接收可能已從目前繼續位置列舉的專案總數。請注意，應用程式應該只將此值視為提示。

[in, out] resume_handle

值的指標，其中包含用來繼續現有連接搜尋的繼續控制碼。第一次呼叫時，控制碼應該是零，後續呼叫則保持不變。如果此參數為 Null，則不會儲存任何繼續控制碼。

傳回值

如果函式成功，傳回值會 NERR_Success。

如果函式失敗，則傳回值是系統錯誤碼。如需錯誤碼的清單，請參閱系統錯誤碼。

備註

需要系統管理員、伺服器或列印操作員或 Power User 群組成員資格，才能成功執行 NetConnectionEnum 函式。

範例

下列程式碼範例示範如何使用 對 NetConnectionEnum 函式的呼叫，列出對共用資源的連線。此範例會呼叫 NetConnectionEnum，並指定資訊層級 1 (CONNECTION_INFO_1) 。如果有專案可傳回，則會列印 coni1_username 和 coni1_netname 成員的值。如果沒有要傳回的專案，範例會列印適當的訊息。最後，程式碼範例會釋放配置給資訊緩衝區的記憶體。

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

需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	lmshare.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll