NetSessionEnum 関数 (lmshare.h)
サーバーで確立されたセッションに関する情報を提供します。
構文
NET_API_STATUS NET_API_FUNCTION NetSessionEnum(
[in] LMSTR servername,
[in] LMSTR UncClientName,
[in] LMSTR username,
[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] UncClientName
情報を返すコンピューター セッションの名前を指定する文字列へのポインター。 このパラメーターが NULL の場合、 NetSessionEnum はサーバー上のすべてのコンピューター セッションの情報を返します。
[in] username
情報を返すユーザーの名前を指定する文字列へのポインター。 このパラメーターが NULL の場合、 NetSessionEnum はすべてのユーザーの情報を返します。
[in] level
データの情報レベルを指定します。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 説明 |
|---|---|
|
セッションを確立したコンピューターの名前を返します。 bufptr パラメーターは、SESSION_INFO_0構造体の配列を指します。 |
|
コンピューターの名前、ユーザーの名前、コンピューター上のファイル、パイプ、およびデバイスを開きます。 bufptr パラメーターは、SESSION_INFO_1構造体の配列を指します。 |
|
レベル 1 に示されている情報に加えて、クライアントの種類とユーザーがセッションを確立した方法を返します。 bufptr パラメーターは、SESSION_INFO_2構造体の配列を指します。 |
|
コンピューターの名前、ユーザーの名前、セッションのアクティブ時間とアイドル時間を返します。 bufptr パラメーターは、SESSION_INFO_10構造体の配列を指します。 |
|
コンピューターの名前を返します。ユーザーの名前。コンピューター上のファイル、パイプ、およびデバイスを開く。クライアントが使用しているトランスポートの名前。 bufptr パラメーターは、SESSION_INFO_502構造体の配列を指します。 |
[out] bufptr
データを受信するバッファーへのポインター。 このデータの形式は 、level パラメーターの値によって異なります。
このバッファーはシステムによって割り当てられ、 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。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| リターン コード | 説明 |
|---|---|
|
ユーザーには、要求された情報へのアクセス権がありません。 |
|
level パラメーターに指定された値が無効です。 |
|
指定されたパラメーターが無効です。 |
|
その他のエントリを使用できます。 すべてのエントリを受信するのに十分な大きさのバッファーを指定します。 |
|
十分なメモリがありません。 |
|
コンピューター名を持つセッションが存在しません。 |
|
コンピューター名が無効です。 |
|
ユーザー名が見つかりませんでした。 |
解説
レベル 1 またはレベル 2 で NetSessionEnum 関数を正常に実行できるのは、Administrators または Server Operators ローカル グループのメンバーだけです。
Active Directory のプログラミングを行う場合は、特定の Active Directory サービス インターフェイス (ADSI) メソッドを呼び出して、ネットワーク管理セッション関数を呼び出すことで実現できるのと同じ機能を実現できます。 詳細については、「 IADsSession 」および「 IADsFileServiceOperations」を参照してください。
例
次のコード サンプルは、 NetSessionEnum 関数の呼び出しを使用して現在のセッションに関する情報を取得する方法を示しています。 このサンプルでは、情報レベル 10 ( SESSION_INFO_10) を指定して NetSessionEnum を呼び出します。 このサンプルでは、エントリをループ処理し、取得した情報を出力します。 最後に、列挙されたセッションの合計数を出力し、情報バッファーに割り当てられたメモリを解放します。
#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[])
{
LPSESSION_INFO_10 pBuf = NULL;
LPSESSION_INFO_10 pTmpBuf;
DWORD dwLevel = 10;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
LPTSTR pszServerName = NULL;
LPTSTR pszClientName = NULL;
LPTSTR pszUserName = NULL;
NET_API_STATUS nStatus;
//
// Check command line arguments.
//
if (argc > 4)
{
wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
exit(1);
}
if (argc >= 2)
pszServerName = argv[1];
if (argc >= 3)
pszClientName = argv[2];
if (argc == 4)
pszUserName = argv[3];
//
// Call the NetSessionEnum function, specifying level 10.
//
do // begin do
{
nStatus = NetSessionEnum(pszServerName,
pszClientName,
pszUserName,
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.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the retrieved data.
//
wprintf(L"\n\tClient: %s\n", pTmpBuf->sesi10_cname);
wprintf(L"\tUser: %s\n", pTmpBuf->sesi10_username);
printf("\tActive: %d\n", pTmpBuf->sesi10_time);
printf("\tIdle: %d\n", pTmpBuf->sesi10_idle_time);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, indicate a system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
//
// Continue to call NetSessionEnum 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 sessions enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
要件
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | lmshare.h (Lm.h を含む) |
| Library | Netapi32.lib |
| [DLL] | Netapi32.dll |