NetSessionEnum-Funktion (lmshare.h)
Stellt Informationen zu Sitzungen bereit, die auf einem Server eingerichtet wurden.
Syntax
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
);
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] UncClientName
Zeiger auf eine Zeichenfolge, die den Namen der Computersitzung angibt, für die Informationen zurückgegeben werden sollen. Wenn dieser Parameter NULL ist, gibt NetSessionEnum Informationen für alle Computersitzungen auf dem Server zurück.
[in] username
Zeiger auf eine Zeichenfolge, die den Namen des Benutzers angibt, für den Informationen zurückgegeben werden sollen. Wenn dieser Parameter NULL ist, gibt NetSessionEnum Informationen für alle Benutzer zurück.
[in] level
Gibt die Informationsebene der Daten an. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Gibt den Namen des Computers zurück, der die Sitzung eingerichtet hat. Der bufptr-Parameter verweist auf ein Array von SESSION_INFO_0 Strukturen. |
|
Geben Sie den Namen des Computers, den Namen des Benutzers und geöffnete Dateien, Pipes und Geräte auf dem Computer zurück. Der bufptr-Parameter verweist auf ein Array von SESSION_INFO_1 Strukturen. |
|
Geben Sie zusätzlich zu den für Ebene 1 angegebenen Informationen den Clienttyp und die Einrichtung der Sitzung durch den Benutzer zurück. Der bufptr-Parameter verweist auf ein Array von SESSION_INFO_2 Strukturen. |
|
Gibt den Namen des Computers, den Namen des Benutzers und die Aktiv- und Leerlaufzeiten für die Sitzung zurück. Der bufptr-Parameter verweist auf ein Array von SESSION_INFO_10 Strukturen. |
|
Gibt den Namen des Computers zurück. Name des Benutzers; Dateien, Pipes und Geräte auf dem Computer öffnen; und den Namen des Transports, den der Client verwendet. Der bufptr-Parameter verweist auf ein Array von SESSION_INFO_502 Strukturen. |
[out] bufptr
Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab.
Dieser Puffer wird vom System zugewiesen 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 die Anzahl der Von der Funktion zurückgegebenen Bytes eingeschränkt werden. 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 aufgelisteten Elemente empfängt.
[out] totalentries
Zeiger auf einen Wert, der die Gesamtanzahl von Einträgen empfängt, die aus der aktuellen Fortsetzenposition aufgezählt worden sein könnten. 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 Sitzungssuche fortzusetzen. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn resume_handleNULL 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 |
|---|---|
|
Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen. |
|
Der für den Levelparameter angegebene Wert ist ungültig. |
|
Der angegebene Parameter ist ungültig. |
|
Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen. |
|
Es ist nicht genügend Arbeitsspeicher verfügbar. |
|
Eine Sitzung mit dem Computernamen ist nicht vorhanden. |
|
Der Computername ist ungültig. |
|
Der Benutzername konnte nicht gefunden werden. |
Hinweise
Nur Mitglieder der lokalen Gruppe Administratoren oder Serveroperatoren können die NetSessionEnum-Funktion auf Ebene 1 oder Ebene 2 erfolgreich ausführen.
Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Netzwerkverwaltungssitzungsfunktionen erreichen können. Weitere Informationen finden Sie unter IADsSession und IADsFileServiceOperations.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie Sie Mithilfe eines Aufrufs der NetSessionEnum-Funktion Informationen zu aktuellen Sitzungen abrufen. Im Beispiel wird NetSessionEnum aufgerufen, wobei die Informationsebene 10 (SESSION_INFO_10) angegeben wird. Das Beispiel durchläuft die Einträge und gibt die abgerufenen Informationen aus. Schließlich gibt der Code die Gesamtzahl der aufgezählten Sitzungen aus und gibt den für den Informationspuffer zugewiesenen 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[])
{
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;
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | lmshare.h (lm.h einschließen) |
| Bibliothek | Netapi32.lib |
| DLL | Netapi32.dll |