NetSessionEnum, fonction (lmshare.h)
Fournit des informations sur les sessions établies sur un serveur.
Syntaxe
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
);
Paramètres
[in] servername
Pointeur vers une chaîne qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.
[in] UncClientName
Pointeur vers une chaîne qui spécifie le nom de la session d’ordinateur pour laquelle les informations doivent être retournées. Si ce paramètre a la valeur NULL, NetSessionEnum retourne des informations pour toutes les sessions d’ordinateur sur le serveur.
[in] username
Pointeur vers une chaîne qui spécifie le nom de l’utilisateur pour lequel les informations doivent être retournées. Si ce paramètre a la valeur NULL, NetSessionEnum retourne des informations pour tous les utilisateurs.
[in] level
Spécifie le niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Retourne le nom de l’ordinateur qui a établi la session. Le paramètre bufptr pointe vers un tableau de structures SESSION_INFO_0 . |
|
Retournez le nom de l’ordinateur, le nom de l’utilisateur et ouvrez les fichiers, les canaux et les appareils sur l’ordinateur. Le paramètre bufptr pointe vers un tableau de structures SESSION_INFO_1 . |
|
En plus des informations indiquées pour le niveau 1, retournez le type de client et la façon dont l’utilisateur a établi la session. Le paramètre bufptr pointe vers un tableau de structures SESSION_INFO_2 . |
|
Retourne le nom de l’ordinateur, le nom de l’utilisateur et les heures d’activité et d’inactivité de la session. Le paramètre bufptr pointe vers un tableau de structures SESSION_INFO_10 . |
|
Retourne le nom de l’ordinateur ; nom de l’utilisateur ; ouvrir des fichiers, des canaux et des appareils sur l’ordinateur ; et le nom du transport utilisé par le client. Le paramètre bufptr pointe vers un tableau de structures SESSION_INFO_502 . |
[out] bufptr
Pointeur vers la mémoire tampon qui reçoit les données. Le format de ces données dépend de la valeur du paramètre level .
Cette mémoire tampon est allouée par le système et doit être libérée à l’aide de la fonction NetApiBufferFree . Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA.
[in] prefmaxlen
Spécifie la longueur maximale par défaut des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour les données. Si vous spécifiez une autre valeur dans ce paramètre, cela peut limiter le nombre d’octets retournés par la fonction. Si la taille de la mémoire tampon est insuffisante pour contenir toutes les entrées, la fonction retourne ERROR_MORE_DATA. Pour plus d’informations, consultez Mémoires tampons de fonction de gestionréseau et Longueurs de mémoire tampon des fonctions de gestion réseau.
[out] entriesread
Pointeur vers une valeur qui reçoit le nombre d’éléments réellement énumérés.
[out] totalentries
Pointeur vers une valeur qui reçoit le nombre total d’entrées qui auraient pu être énumérées à partir de la position de reprise actuelle. Notez que les applications doivent considérer cette valeur uniquement comme un indicateur.
[in, out] resume_handle
Pointeur vers une valeur qui contient un handle de cv utilisé pour poursuivre une recherche de session existante. Le handle doit être égal à zéro lors du premier appel et laisser inchangé pour les appels suivants. Si resume_handle a la valeur NULL, aucun handle de reprise n’est stocké.
Valeur retournée
Si la fonction réussit, la valeur de retour est NERR_Success.
Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
|
L’utilisateur n’a pas accès aux informations demandées. |
|
La valeur spécifiée pour le paramètre level n’est pas valide. |
|
Le paramètre spécifié n’est pas valide. |
|
D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées. |
|
La mémoire disponible est insuffisante. |
|
Il n’existe pas de session avec le nom de l’ordinateur. |
|
Le nom de l’ordinateur n’est pas valide. |
|
Le nom d’utilisateur est introuvable. |
Notes
Seuls les membres du groupe local Administrateurs ou Opérateurs de serveur peuvent exécuter correctement la fonction NetSessionEnum au niveau 1 ou 2.
Si vous programmez pour Active Directory, vous pouvez peut-être appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir les mêmes fonctionnalités que celles que vous pouvez obtenir en appelant les fonctions de session de gestion réseau. Pour plus d’informations, consultez IADsSession et IADsFileServiceOperations.
Exemples
L’exemple de code suivant montre comment récupérer des informations sur les sessions actuelles à l’aide d’un appel à la fonction NetSessionEnum . L’exemple appelle NetSessionEnum, en spécifiant le niveau d’informations 10 ( SESSION_INFO_10). L’exemple effectue une boucle dans les entrées et imprime les informations récupérées. Enfin, le code imprime le nombre total de sessions énumérées et libère la mémoire allouée pour la mémoire tampon d’informations.
#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;
}
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | lmshare.h (include Lm.h) |
| Bibliothèque | Netapi32.lib |
| DLL | Netapi32.dll |