SnmpCreateSession, fonction (winsnmp.h)

Article
03/13/2024

[SNMP est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Au lieu de cela, utilisez La gestion à distance Windows, qui est l’implémentation Microsoft de WS-Man.]

La fonction SnmpCreateSession demande à l’implémentation de Microsoft WinSNMP d’ouvrir une session pour l’application WinSNMP. L’application peut spécifier la façon dont l’implémentation doit informer la session WinSNMP des messages SNMP et des événements asynchrones disponibles. L’application peut spécifier un message de notification de fenêtre ou une fonction SNMPAPI_CALLBACK pour notifier la session.

La fonction SnmpCreateSession est un élément de l’API WinSNMP, version 2.0. Lors du développement de nouvelles applications WinSNMP, il est recommandé d’appeler SnmpCreateSession pour ouvrir une session WinSNMP au lieu d’appeler la fonction SnmpOpen .

Syntaxe

HSNMP_SESSION SNMPAPI_CALL SnmpCreateSession(
  [in] HWND             hWnd,
  [in] UINT             wMsg,
  [in] SNMPAPI_CALLBACK fCallBack,
  [in] LPVOID           lpClientData
);

Paramètres

[in] hWnd

Gérez vers une fenêtre de l’application WinSNMP pour notifier lorsqu’une demande asynchrone se termine ou quand une notification d’interruption se produit. Ce paramètre est requis pour les messages de notification de fenêtre pour la session.

[in] wMsg

Spécifie un entier non signé qui identifie le message de notification à envoyer à la fenêtre de l’application WinSNMP. Ce paramètre est requis pour les messages de notification de fenêtre pour la session.

[in] fCallBack

Spécifie l’adresse d’une fonction de SNMPAPI_CALLBACK spécifique à une session définie par l’application . L’implémentation appelle cette fonction pour informer la session WinSNMP lorsque des notifications sont disponibles.

Ce paramètre est requis pour spécifier les notifications de rappel pour la session. Ce paramètre doit avoir la valeur NULL pour spécifier les messages de notification de fenêtre pour la session. Pour plus d’informations, consultez la section Remarques suivante.

[in] lpClientData

Pointeur vers les données définies par l’application à passer à la fonction de rappel spécifiée par le paramètre fCallback . Ce paramètre est facultatif et peut être NULL. Si le paramètre fCallback a la valeur NULL, l’implémentation ignore ce paramètre.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle qui identifie la session WinSNMP que l’implémentation ouvre pour l’application appelante.

Si la fonction échoue, la valeur de retour est SNMPAPI_FAILURE. Pour obtenir des informations d’erreur étendues, appelez SnmpGetLastError. La fonction SnmpGetLastError peut retourner l’une des erreurs suivantes.

Code de retour	Description
SNMPAPI_NOT_INITIALIZED	La fonction SnmpStartup ne s’est pas terminée correctement.
SNMPAPI_ALLOC_ERROR	Une erreur s’est produite lors de l’allocation de mémoire.
SNMPAPI_HWND_INVALID	Le paramètre fCallback a la valeur NULL, mais le paramètre hWnd n’est pas un handle de fenêtre valide.
SNMPAPI_MESSAGE_INVALID	Le paramètre fCallback a la valeur NULL, mais le paramètre wMsg n’est pas une valeur de message valide.
SNMPAPI_MODE_INVALID	Le paramètre fCallback a la valeur NULL et les paramètres hWnd et wMsg sont valides individuellement. Toutefois, les valeurs sont incompatibles entre elles sur la plateforme Windows.
SNMPAPI_OPERATION_INVALID	La combinaison de valeurs de paramètres ne spécifie pas les notifications de rappel ni les messages de notification de fenêtre.
SNMPAPI_OTHER_ERROR	Une erreur inconnue ou non définie s’est produite.

Remarques

La fonction SnmpCreateSession retourne un handle unique à chaque session WinSNMP ouverte au sein de l’application WinSNMP appelante. L’application doit utiliser le handle de session que SnmpCreateSession retourne dans d’autres appels de fonction WinSNMP pour faciliter l’allocation et la répartition des ressources par l’implémentation.

Il est recommandé qu’une application WinSNMP appelle la fonction SnmpClose une fois pour chaque session que l’implémentation ouvre à la suite d’un appel à la fonction SnmpCreateSession . Si une application WinSNMP se termine de manière inattendue, elle doit appeler SnmpCleanup avant de se terminer pour permettre à l’implémentation de libérer toutes les ressources.

Notifications de rappel

Si le paramètre fCallback n’est pas NULL lors d’un appel réussi à la fonction SnmpCreateSession , l’implémentation alerte la session aux notifications à l’aide de la fonction de rappel spécifiée par le paramètre fCallback .

Voici un exemple d’appel à la fonction SnmpCreateSession , demandant que l’implémentation signale à la session les messages et les événements à l’aide de notifications de rappel.

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Messages de notification de fenêtre

La fonction SnmpCreateSession transmet à l’implémentation le handle à une fenêtre d’application et un identificateur de message de notification. Lorsque la fenêtre d’application reçoit le message de notification spécifié par le paramètre wMsg , l’application WinSNMP doit récupérer l’unité de données de protocole entrante (PDU). Pour ce faire, l’application appelle la fonction SnmpRecvMsg avec le handle de session retourné par SnmpCreateSession.

Une application WinSNMP peut ouvrir plusieurs sessions WinSNMP. Si une application ouvre plusieurs sessions à l’aide du même handle de fenêtre, il est recommandé que l’application WinSNMP spécifie un paramètre wMsg unique pour chaque session.

Voici un exemple d’appel à la fonction SnmpCreateSession , demandant que l’implémentation signale la session sur les messages et les événements à l’aide de messages de notification de fenêtre.

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winsnmp.h
Bibliothèque	Wsnmp32.lib
DLL	Wsnmp32.dll