SnmpRecvMsg, fonction (winsnmp.h)

Article
08/27/2023

[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. Utilisez plutôt Windows Remote Management, qui est l’implémentation Microsoft de WS-Man.]

La fonction SnmpRecvMsg WinSNMP récupère les résultats d’une requête asynchrone terminée envoyée par un appel à la fonction SnmpSendMsg , sous la forme d’un message SNMP. La fonction SnmpRecvMsg retourne également les données d’interruption en suspens et les notifications inscrites pour une session WinSNMP.

Syntaxe

SNMPAPI_STATUS SNMPAPI_CALL SnmpRecvMsg(
  [in]  HSNMP_SESSION   session,
  [out] LPHSNMP_ENTITY  srcEntity,
  [out] LPHSNMP_ENTITY  dstEntity,
  [out] LPHSNMP_CONTEXT context,
  [out] LPHSNMP_PDU     PDU
);

Paramètres

[in] session

Gérez la session WinSNMP.

[out] srcEntity

Pointeur vers une variable qui reçoit un handle vers l’entité qui envoie le message. Notez que le paramètre srcEntity de la fonction SnmpRegister spécifie un handle pour l’entité de gestion qui s’inscrit pour la notification d’interruption.

[out] dstEntity

Pointeur vers une variable qui reçoit un handle vers l’entité qui reçoit le message. Notez que le paramètre dstEntity de la fonction SnmpRegister spécifie un handle à l’entité de gestion qui envoie des interruptions.

[out] context

Pointeur vers une variable qui reçoit un handle vers le contexte, qui est un ensemble de ressources d’objet managé. L’entité spécifiée par le paramètre srcEntity émet le message à partir de ce contexte.

[out] PDU

Pointeur vers une variable qui reçoit un handle vers le composant d’unité de données de protocole (PDU) du message.

Valeur retournée

Si la fonction réussit, la valeur de retour est SNMPAPI_SUCCESS et les paramètres de sortie contiennent les valeurs indiquées dans les descriptions de paramètres précédentes.

Si la fonction échoue, la valeur de retour est SNMPAPI_FAILURE. Si la fonction échoue avec un code d’erreur étendu qui indique une erreur de couche de transport réseau, c’est-à-dire une erreur qui commence par SNMPAPI_TL_, les paramètres de sortie contiennent également les valeurs indiquées précédemment pour permettre à l’application WinSNMP de récupérer normalement.

Pour obtenir des informations d’erreur étendues, appelez SnmpGetLastError. La fonction SnmpGetLastError peut retourner l’une des erreurs winSNMP ou de la couche de transport réseau 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_SESSION_INVALID	Le paramètre de session n’est pas valide.
SNMPAPI_NOOP	La session spécifiée n’a aucun message dans sa file d’attente pour l’instant.
SNMPAPI_TL_NOT_INITIALIZED	La couche de transport réseau n’a pas été initialisée.
SNMPAPI_TL_NOT_SUPPORTED	La couche de transport réseau ne prend pas en charge le protocole SNMP.
SNMPAPI_TL_NOT_AVAILABLE	Le sous-système réseau a échoué.
SNMPAPI_TL_RESOURCE_ERROR	Une erreur de ressource s’est produite dans la couche de transport réseau.
SNMPAPI_TL_UNDELIVERABLE	L’entité spécifiée par le paramètre dstEntity n’est pas disponible.
SNMPAPI_TL_SRC_INVALID	L’entité spécifiée par le paramètre srcEntity n’a pas été initialisée.
SNMPAPI_TL_INVALID_PARAM	Un appel de fonction de la couche de transport réseau a reçu un paramètre d’entrée non valide.
SNMPAPI_TL_PDU_TOO_BIG	La PDU est trop grande pour que la couche de transport réseau envoie ou reçoit.
SNMPAPI_TL_OTHER	Une erreur de couche de transport réseau non définie s’est produite.
SNMPAPI_OTHER_ERROR	Une erreur inconnue ou non définie s’est produite.

Pour plus d’informations, consultez Erreurs de transport réseau.

Remarques

La fonction SnmpCreateSession transmet un handle de fenêtre d’application et un identificateur de message de notification à l’implémentation Microsoft WinSNMP. Lorsque la fenêtre d’application reçoit le message de notification spécifié par le paramètre wMsg , l’application WinSNMP doit appeler la fonction SnmpRecvMsg avec le handle de session retourné par SnmpCreateSession pour récupérer une unité de données de protocole entrante (PDU). Pour plus d’informations, consultez À propos des messages SNMP.

La fonction SnmpRecvMsg instancie quatre objets et alloue leurs ressources : deux handles d’entité, un handle de contexte et un handle PDU. Le handle du composant de liste de liaisons de variables de la PDU retournée n’est pas instancié tant que l’application WinSNMP n’appelle pas la fonction SnmpGetPduData . Lorsqu’elle n’a plus besoin des ressources retournées par SnmpRecvMsg , l’application WinSNMP doit libérer les ressources individuelles à l’aide de la fonction WinSNMP qui correspond à la ressource. Pour plus d’informations, consultez SnmpFreePdu, SnmpFreeEntity et SnmpFreeContext.

Lorsque l’implémentation reçoit des interruptions d’une entité fonctionnant sous l’infrastructure SNMP version 1 (SNMPv1), elle traduit les interruptions au format SNMP version 2C (SNMPv2C). Par conséquent, lorsque SnmpRecvMsg délivre une interruption, il est toujours au format SNMPv2C. Pour plus d’informations, consultez Traduire des interruptions de SNMPv1 en tâches de programmation SNMPv2C et WinSNMP.

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