NetServerDiskEnum 関数 (lmserver.h)

NetServerDiskEnum 関数は、サーバー上のディスク ドライブの一覧を取得します。 この関数は、3 文字の文字列 (ドライブ文字、コロン、終端の null 文字) の配列を返します。

構文

NET_API_STATUS NET_API_FUNCTION NetServerDiskEnum(
  [in]      LMSTR   servername,
  [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 の場合は、ローカル コンピューターが使用されます。

[in] level

必要な情報のレベル。 0 の値だけが有効なレベルです。

[out] bufptr

データを受信するバッファーへのポインター。 データは、3 文字の文字列 (ドライブ文字、コロン、終端の null 文字) の配列です。 このバッファーはシステムによって割り当てられ、 NetApiBufferFree 関数を使用して解放する必要があります。 関数がERROR_MORE_DATAで失敗した場合でも、バッファーを解放する必要があることに注意してください。

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

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

[in, out] resume_handle

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

戻り値

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

関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。

解説

リモート コンピューターで NetServerDiskEnum 関数を正常に実行できるのは、Administrators または Server Operators ローカル グループのメンバーだけです。

Active Directory のプログラミングを行う場合は、特定の Active Directory サービス インターフェイス (ADSI) メソッドを呼び出して、ネットワーク管理サーバー関数を呼び出すことで実現できるのと同じ結果を得ることができます。 詳細については、「 IADsComputer インターフェイス リファレンス」を参照してください。

例

次のコード サンプルでは、 NetServerDiskEnum 関数を呼び出して、サーバー上のディスク ドライブの一覧を取得する方法を示します。 このサンプルでは、情報レベル 0 (必須) を指定して NetServerDiskEnum を呼び出します。 返すエントリがあり、ユーザーが情報にアクセスできる場合は、ドライブの一覧を 3 文字の文字列 (ドライブ文字、コロン、終端の null 文字) の形式で出力します。 また、このサンプルでは、使用可能なエントリの合計数と、実際に列挙されたエントリの数に関するヒントも出力されます。 最後に、コード サンプルでは、バッファーに割り当てられたメモリを解放します。

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h> 
#include <lm.h>

#pragma comment(lib, "netapi32.lib")

int wmain(int argc, wchar_t *argv[])
{
   const int ENTRY_SIZE = 3; // Drive letter, colon, NULL
   LPTSTR pBuf = NULL;
   DWORD dwLevel = 0; // level must be zero
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   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 NetServerDiskEnum function.
   //
   nStatus = NetServerDiskEnum(pszServerName,
                               dwLevel,
                               (LPBYTE *) &pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               NULL);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPTSTR pTmpBuf;

      if ((pTmpBuf = pBuf) != NULL)
      {
         DWORD i;
         DWORD dwTotalCount = 0;
         //
         // Loop through the entries.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               // On a remote computer, only members of the
               //  Administrators or the Server Operators 
               //  local group can execute NetServerDiskEnum.
               //
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Print drive letter, colon, NULL for each drive;
            //   the number of entries actually enumerated; and
            //   the total number of entries available.
            //
            fwprintf(stdout, L"\tDisk: %S\n", pTmpBuf);

            pTmpBuf += ENTRY_SIZE;
            dwTotalCount++;
         }

         fprintf(stderr, "\nEntries enumerated: %d\n", dwTotalCount);
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

要件

関連項目

IADsComputer

NetServerEnum

ネットワーク管理機能

ネットワーク管理の概要

サーバー関数