SnmpRegister, 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 SnmpRegister WinSNMP inscrit ou annule l’inscription d’une application WinSNMP pour la réception d’interruption et de notification. L’application peut inscrire et recevoir des interruptions et des notifications, ou annuler et désactiver les interruptions et notifications.

Une application WinSNMP peut inscrire ou annuler l’inscription pour un type d’interruption ou de notification, ou pour toutes les interruptions et notifications, en fonction de la valeur du paramètre de notification .

Syntaxe

SNMPAPI_STATUS SNMPAPI_CALL SnmpRegister(
  [in] HSNMP_SESSION session,
  [in] HSNMP_ENTITY  srcEntity,
  [in] HSNMP_ENTITY  dstEntity,
  [in] HSNMP_CONTEXT context,
  [in] smiLPCOID     notification,
  [in] smiUINT32     state
);

Paramètres

[in] session

Gérez la session WinSNMP qui inscrit ou annule l’inscription pour les interruptions et les notifications.

[in] srcEntity

Gérez l’entité de gestion qui est la source de la demande d’inscription. Cette entité, agissant dans un rôle de gestionnaire SNMP, recevra l’interruption ou la notification.

Étant donné que l’implémentation n’utilise pas ce paramètre pour filtrer les interruptions et les notifications d’atteindre l’application WinSNMP, une application de gestionnaire WinSNMP transmet généralement la valeur NULL dans ce paramètre.

Si ce paramètre a la valeur NULL, l’implémentation de Microsoft WinSNMP inscrit ou annule l’inscription de toutes les sources de demandes d’interruption et de notification.

Notez que le paramètre srcEntity de la fonction SnmpRecvMsg a un rôle différent. Dans cette fonction, srcEntity reçoit un handle à l’entité qui a envoyé l’interruption.

[in] dstEntity

Gérez l’entité de gestion qui est le destinataire de la demande d’inscription. Cette entité, agissant dans un rôle d’agent SNMP, envoie l’interruption ou la notification.

Si ce paramètre a la valeur NULL, l’implémentation inscrit ou annule l’inscription de l’application WinSNMP pour les interruptions et les notifications de toutes les entités de gestion.

Notez que le paramètre dstEntity de la fonction SnmpRecvMsg reçoit un handle pour l’entité de gestion qui s’inscrit pour la notification d’interruption.

[in] context

Gérez le contexte, qui est un ensemble de ressources d’objet managé.

Si ce paramètre a la valeur NULL, l’implémentation inscrit ou annule l’inscription de l’application WinSNMP pour les interruptions et les notifications pour chaque contexte.

[in] notification

Pointeur vers une structure smiOID qui contient la séquence de correspondance de modèle pour un type d’interruption ou de notification. L’implémentation utilise cette séquence pour identifier le type d’interruption ou de notification pour lequel l’application WinSNMP s’inscrit ou se désinscrit. Pour plus d’informations, consultez la section Remarques suivante.

Si ce paramètre a la valeur NULL, l’implémentation inscrit ou annule l’inscription de l’application WinSNMP pour toutes les interruptions et notifications provenant de l’entité de gestion ou des entités spécifiées par le paramètre dstEntity .

[in] state

Spécifie une variable entière longue non signée qui indique si l’application WinSNMP s’inscrit pour recevoir des interruptions et des notifications, ou si elle est en cours de désinscription. Ce paramètre doit être égal à l’une des valeurs suivantes, mais s’il contient une valeur différente, l’implémentation inscrit l’application.

Valeur	Signification
SNMPAPI_OFF	Désactivez les interruptions et les notifications.
SNMPAPI_ON	Inscrivez-vous pour recevoir des interruptions et des notifications.

Valeur retournée

Si la fonction réussit, la valeur de retour est SNMPAPI_SUCCESS.

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 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_ENTITY_INVALID	L’un des paramètres d’entité ou les deux n’est pas valide.
SNMPAPI_CONTEXT_INVALID	Le paramètre de contexte n’est pas valide.
SNMPAPI_OID_INVALID	Le paramètre de notification n’est pas valide.
SNMPAPI_TL_NOT_INITIALIZED	La couche de transport réseau n’a pas été initialisée ou le service SNMPTRAP.EXE n’a pas pu être démarré.
SNMPAPI_TL_IN_USE	Le port d’interruption n’est pas disponible.
SNMPAPI_TL_NOT_AVAILABLE	Le sous-système réseau a échoué.
SNMPAPI_OTHER_ERROR	Une erreur inconnue ou non définie s’est produite.

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

Remarques

En général, une application de gestionnaire WinSNMP, plutôt qu’une application agent, appelle la fonction SnmpRegister .

Il est important de noter que pour les utilisateurs qui ne sont pas administrateurs, la fonction SnmpRegister réussit sur Windows 2000 et Windows XP uniquement si le service d’interruption SNMP a été démarré.

Si une application WinSNMP transmet la valeur NULL dans un appel à la fonction SnmpRegister dans les paramètres srcEntity, dstEntity, context ou notification , l’implémentation n’utilise pas ce paramètre pour filtrer les interruptions et les notifications dans l’accès à l’application WinSNMP. Si une application transmet la valeur NULL dans tous les paramètres mentionnés précédemment, l’implémentation remet toutes les notifications reçues à la session.

Si une application WinSNMP s’inscrit pour recevoir un type spécifique d’interruption ou de notification, elle doit définir un identificateur d’objet, c’est-à-dire une structure smiOID , qui correspond à ce type d’interruption. Le paramètre de notification doit pointer vers cette structure. RFC 1907, « Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2) », définit les identificateurs d’objets d’interruption et de notification. Pour plus d’informations, consultez Gestion des interruptions et des notifications et Traduction des interruptions de SNMPv1 en SNMPv2C.

L’implémentation utilise la valeur du paramètre de notification comme modèle pour faire correspondre les notifications et les interruptions reçues. Par exemple, si l’application WinSNMP transmet n nombre de sous-identificateurs dans le paramètre de notification , et que les premiers n sous-identificateurs dans une interruption reçue correspondent à tous les sous-identificateurs passés, l’identificateur d’objet d’interruption est une correspondance. Si une interruption reçue a moins de sous-identificateurs que n, l’identificateur d’objet ne correspond pas. En cas de correspondance, l’implémentation envoie l’interruption ou la notification à l’application WinSNMP.

Si tout ou partie des paramètres dstEntity, srcEntity ou de contexte ont la valeur NULL, l’implémentation peut avoir besoin d’allouer des ressources lors d’un appel ultérieur à la fonction SnmpRecvMsg , pour les paramètres correspondants de cette fonction. Lorsque l’application WinSNMP n’a plus besoin des ressources retournées par SnmpRecvMsg , l’application doit libérer les ressources individuelles avec la fonction qui correspond à la ressource. Pour plus d’informations, consultez SnmpFreeEntity et SnmpFreeContext.

Pour plus d’informations, consultez Inscriptions à plusieurs interruptions.

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