NetConnectionEnum 関数 (lmshare.h)

サーバー上の共有リソースに対して行われたすべての接続、または特定のコンピューターから確立されたすべての接続を一覧表示します。 この接続を使用するユーザーが複数ある場合は、同じ接続に対して複数の構造体を取得できますが、ユーザー名は異なります。

構文

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

目的の接続の共有名またはコンピューター名を指定する文字列へのポインター。 共有名の場合は、その共有名に対して行われたすべての接続が一覧表示されます。 コンピューター名 (たとえば、2 つの円記号で始まる) の場合、 NetConnectionEnum は、そのコンピューターから指定されたサーバーへの接続をすべて一覧表示します。

_WIN32_WINNTまたはFORCE_UNICODEが定義されている場合、この文字列は Unicode です。

[in] level

データの情報レベルを指定します。 このパラメーターには、次の値のいずれかを指定できます。

[out] bufptr

情報を受信するバッファーのアドレスへのポインター。 このデータの形式は、 level パラメーターの値によって異なります。

このバッファーはシステムによって割り当てられ、 NetApiBufferFree 関数を使用して解放する必要があります。 関数が ERROR_MORE_DATA で失敗した場合でも、バッファーを解放する必要があることに注意してください。

[in] prefmaxlen

返されるデータの推奨される最大長をバイト単位で指定します。 MAX_PREFERRED_LENGTHを指定すると、データに必要なメモリ量が関数によって割り当てられます。 このパラメーターに別の値を指定すると、関数から返されるバイト数を制限できます。 バッファー サイズが不十分で、すべてのエントリを保持できる場合、関数は ERROR_MORE_DATAを返します。 詳細については、「 ネットワーク管理機能バッファー 」および「 ネットワーク管理機能バッファーの長さ」を参照してください。

[out] entriesread

実際に列挙された要素の数を受け取る値へのポインター。

[out] totalentries

現在の再開位置から列挙された可能性があるエントリの合計数を受け取る値へのポインター。 アプリケーションでは、この値のみをヒントとして考慮する必要があることに注意してください。

[in, out] resume_handle

既存の接続検索を続行するために使用される再開ハンドルを含む値へのポインター。 最初の呼び出しではハンドルを 0 にし、後続の呼び出しでは変更せずに残す必要があります。 このパラメーターが NULL の場合、再開ハンドルは格納されません。

戻り値

関数が成功した場合、戻り値は NERR_Success。

関数が失敗した場合、戻り値はシステム エラー コードです。 エラー コードの一覧については、「 システム エラー コード」を参照してください。

解説

NetConnectionEnum 関数を正常に実行するには、管理者、サーバーまたは印刷オペレーター、または Power User グループ メンバーシップが必要です。

例

次のコード サンプルは、 NetConnectionEnum 関数を呼び出して共有リソースに対して行われた接続を一覧表示する方法を示しています。 このサンプルでは、情報レベル 1 (CONNECTION_INFO_1) を指定して NetConnectionEnum を呼び出します。 返すエントリがある場合は、 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;
}

要件

関連項目

CONNECTION_INFO_0

CONNECTION_INFO_1

ネットワーク管理機能

ネットワーク管理の概要

ネットワーク共有関数