Struct ipworkssnmp::SNMPTrapMgr

Properties   Methods   Events   Config Settings   Errors  

The SNMPTrapMgr struct provides a UDP-based listening point for SNMP traps.

Syntax

ipworkssnmp::SNMPTrapMgr

Remarks

The SNMPTrapMgr struct provides a UDP-based listening point for SNMP traps and informs as specified by the SNMP RFCs. The struct supports v1, v2c, and v3 traps.

SNMP over DTLS is also supported when ssl_enabled is set to True. The SSLCert properties are used to select a certificate for the server. The on_ssl_status event provides information about the DTLS handshake. When client authentication is required, the ssl_authenticate_clients property can be set to True and the on_ssl_client_authentication event can be used to examine client credentials.

The struct provides both encoding/decoding and transport capabilities, making the task of developing a custom SNMP Trap manager as simple as setting a few key properties and handling a few events. SNMP data, such as for instance SNMP object id-s (OID-s) are exchanged as text strings, thus further simplifying the task of handling them.

The struct is activated/deactivated by calling the activate or deactivate method. These methods enable or disable sending and receiving. The activation status can be found in the active property.

Messages are received through events such as on_trap, on_inform_request, or on_discovery_request.

SNMP OIDs, types, and values are provided in the objects collection of SNMP objects for both sent and received packets.

SNMPv3 USM security passwords are requested through the on_get_user_password event, and event parameters such as User and SecurityLevel provide information about the security attributes of received requests, and enable granular decision capability about what to provide and what not to provide.

The add_user, remove_user, show_cache, clear_cache, add_engine, and remove_engine methods are used to manage an internal authentication cache. This internal cache can be used as an alternative to the on_get_user_password event, automatically checking the cache against the security parameters provided in the request signature.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksSNMP. Due to this, the SNMPTrapMgr struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of SNMPTrapMgr when you have finished using the instance.

Property List

---

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

accept_data property (SNMPTrapMgr Struct)

Enables or disables data reception.

Syntax

fn accept_data(&self ) -> Result<bool, IPWorksSNMPError> 

Default Value

true

Remarks

Setting the property to False temporarily disables data reception. Setting the property to True re-enables data reception.

This property is read-only.

Data Type

bool

active property (SNMPTrapMgr Struct)

Indicates whether the struct is active.

Syntax

fn active(&self ) -> Result<bool, IPWorksSNMPError> 

Default Value

false

Remarks

This property indicates whether the struct is currently active and can send or receive data.

The struct will be automatically activated if it is not already and you attempt to perform an operation which requires the struct to be active.

Use the activate and deactivate methods to control whether the struct is active.

This property is read-only.

Data Type

bool

local_engine_id property (SNMPTrapMgr Struct)

The Engine Id (for SNMPv3).

Syntax

fn local_engine_id(&self ) -> Result<Vec<u8>, IPWorksSNMPError> 
fn set_local_engine_id(&self, value : Vec<u8>) ->  Option<IPWorksSNMPError> 
fn set_local_engine_id_ref(&self, value : &[u8]) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

This property is necessary for properly handling on_inform_request packets.

Data Type

Vec

local_host property (SNMPTrapMgr Struct)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

fn local_host(&self ) -> Result<String, IPWorksSNMPError> 
fn set_local_host(&self, value : &str) ->  Option<IPWorksSNMPError> 
fn set_local_host_ref(&self, value : &String) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

This property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the struct initiate connections (or accept in the case of server structs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the struct is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: local_host is not persistent. You must always set it in code, and never in the property window.

Data Type

String

local_port property (SNMPTrapMgr Struct)

The port in the local host where the struct is bound to.

Syntax

fn local_port(&self ) -> Result<i32, IPWorksSNMPError> 
fn set_local_port(&self, value : i32) ->  Option<IPWorksSNMPError> 

Default Value

162

Remarks

The local_port property must be set before the struct is activated (active is set to True). It instructs the struct to bind to a specific port (or communication endpoint) in the local machine.

The default port is 162 (standard trap port). If that port is busy, an error will be returned, unless the ForceLocalPort configuration setting is set to False, in which case a random port will be chosen.

local_port cannot be changed once the struct is active. Any attempt to set the local_port property when the struct is active will generate an error.

NOTE: on macOS and iOS, root permissions are required to set local_port to any value below 1024.

Data Type

i32

obj_count property (SNMPTrapMgr Struct)

The number of records in the Obj arrays.

Syntax

fn obj_count(&self ) -> Result<i32, IPWorksSNMPError> 
fn set_obj_count(&self, value : i32) ->  Option<IPWorksSNMPError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• obj_id
• obj_type
• obj_type_string
• obj_value

The array indices start at 0 and end at obj_count - 1.

Data Type

i32

obj_type property (SNMPTrapMgr Struct)

The current object's type.

Syntax

fn obj_type(&self , ObjIndex : i32) -> Result<i32, IPWorksSNMPError> 
fn set_obj_type(&self, ObjIndex : i32, value : i32) ->  Option<IPWorksSNMPError> 

Possible Values

2   // Integer
4   // OctetString
5   // Null
6   // ObjectId
64   // IPAddress
65   // Counter32
66   // Gauge32
67   // TimeTicks
68   // Opaque
69   // NSAP
70   // Counter64
71   // UnsignedInteger32
128   // NoSuchObject
129   // NoSuchInstance
130   // EndOfMibView

Default Value

5

Remarks

The current object's type. The default type is NULL (5).

The corresponding object id and value are specified by the obj_oid and obj_value properties.

Possible object type values include:

The struct also supports the following artificial object values used to designate error conditions:

The ObjIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ObjCount property.

Data Type

i32

obj_id property (SNMPTrapMgr Struct)

The current object's id which is encoded as a string of numbers separated by periods.

Syntax

fn obj_id(&self , ObjIndex : i32) -> Result<String, IPWorksSNMPError> 
fn set_obj_id(&self, ObjIndex : i32, value : &str) ->  Option<IPWorksSNMPError> 
fn set_obj_id_ref(&self, ObjIndex : i32, value : &String) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

The current object's id which is encoded as a string of numbers separated by periods. For instance: "1.3.6.1.2.1.1.1.0" (OID for "system description").

The corresponding object type and value (if any) are specified by the obj_object_type and obj_value properties.

Example

SNMPControl.ObjCount = 1 SNMPControl.ObjId(0) = "1.3.6.1.2.1.1.1.0"

The ObjIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ObjCount property.

Data Type

String

obj_type_string property (SNMPTrapMgr Struct)

A string representation of the current object's ObjectType .

Syntax

fn obj_type_string(&self , ObjIndex : i32) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

A string representation of the current object's obj_object_type.

The corresponding object id and value are specified by the obj_oid and obj_value properties.

The ObjIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ObjCount property.

This property is read-only.

Data Type

String

obj_value property (SNMPTrapMgr Struct)

The current object's value.

Syntax

fn obj_value(&self , ObjIndex : i32) -> Result<Vec<u8>, IPWorksSNMPError> 
fn set_obj_value(&self, ObjIndex : i32, value : Vec<u8>) ->  Option<IPWorksSNMPError> 
fn set_obj_value_ref(&self, ObjIndex : i32, value : &[u8]) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

The current object's value. The corresponding object id and type are specified by the obj_oid and obj_object_type properties.

Example

SNMPControl.ObjCount = 1 SNMPControl.ObjId(0) = "1.3.6.1.2.1.1.1.0" SNMPControl.ObjValue(0) = "New Value"

The ObjIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ObjCount property.

Data Type

Vec

request_id property (SNMPTrapMgr Struct)

The request-id to mark outgoing packets with.

Syntax

fn request_id(&self ) -> Result<i32, IPWorksSNMPError> 
fn set_request_id(&self, value : i32) ->  Option<IPWorksSNMPError> 

Default Value

1

Remarks

If a custom value is needed for request_id, the property must be set before sending the request. The struct increments request_id automatically after sending each packet.

Data Type

i32

ssl_authenticate_clients property (SNMPTrapMgr Struct)

If set to True, the server asks the client(s) for a certificate.

Syntax

fn ssl_authenticate_clients(&self ) -> Result<bool, IPWorksSNMPError> 
fn set_ssl_authenticate_clients(&self, value : bool) ->  Option<IPWorksSNMPError> 

Default Value

false

Remarks

This property is used in conjunction with the on_ssl_client_authentication event. Please refer to the documentation of the on_ssl_client_authentication event for details.

Data Type

bool

ssl_cert_effective_date property (SNMPTrapMgr Struct)

The date on which this certificate becomes valid.

Syntax

fn ssl_cert_effective_date(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_expiration_date property (SNMPTrapMgr Struct)

The date on which the certificate expires.

Syntax

fn ssl_cert_expiration_date(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

Data Type

String

ssl_cert_extended_key_usage property (SNMPTrapMgr Struct)

A comma-delimited list of extended key usage identifiers.

Syntax

fn ssl_cert_extended_key_usage(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

Data Type

String

ssl_cert_fingerprint property (SNMPTrapMgr Struct)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha1 property (SNMPTrapMgr Struct)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha1(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

Data Type

String

ssl_cert_fingerprint_sha256 property (SNMPTrapMgr Struct)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

fn ssl_cert_fingerprint_sha256(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

Data Type

String

ssl_cert_issuer property (SNMPTrapMgr Struct)

The issuer of the certificate.

Syntax

fn ssl_cert_issuer(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

Data Type

String

ssl_cert_private_key property (SNMPTrapMgr Struct)

The private key of the certificate (if available).

Syntax

fn ssl_cert_private_key(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

NOTE: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

Data Type

String

ssl_cert_private_key_available property (SNMPTrapMgr Struct)

Whether a PrivateKey is available for the selected certificate.

Syntax

fn ssl_cert_private_key_available(&self ) -> Result<bool, IPWorksSNMPError> 

Default Value

false

Remarks

Whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

Data Type

bool

ssl_cert_private_key_container property (SNMPTrapMgr Struct)

The name of the PrivateKey container for the certificate (if available).

Syntax

fn ssl_cert_private_key_container(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

Data Type

String

ssl_cert_public_key property (SNMPTrapMgr Struct)

The public key of the certificate.

Syntax

fn ssl_cert_public_key(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

Data Type

String

ssl_cert_public_key_algorithm property (SNMPTrapMgr Struct)

The textual description of the certificate's public key algorithm.

Syntax

fn ssl_cert_public_key_algorithm(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_public_key_length property (SNMPTrapMgr Struct)

The length of the certificate's public key (in bits).

Syntax

fn ssl_cert_public_key_length(&self ) -> Result<i32, IPWorksSNMPError> 

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

Data Type

i32

ssl_cert_serial_number property (SNMPTrapMgr Struct)

The serial number of the certificate encoded as a string.

Syntax

fn ssl_cert_serial_number(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

Data Type

String

ssl_cert_signature_algorithm property (SNMPTrapMgr Struct)

The text description of the certificate's signature algorithm.

Syntax

fn ssl_cert_signature_algorithm(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

Data Type

String

ssl_cert_store property (SNMPTrapMgr Struct)

The name of the certificate store for the client certificate.

Syntax

fn ssl_cert_store(&self ) -> Result<Vec<u8>, IPWorksSNMPError> 
fn set_ssl_cert_store(&self, value : Vec<u8>) ->  Option<IPWorksSNMPError> 
fn set_ssl_cert_store_ref(&self, value : &[u8]) ->  Option<IPWorksSNMPError> 

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password-protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

Data Type

Vec

ssl_cert_store_password property (SNMPTrapMgr Struct)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

fn ssl_cert_store_password(&self ) -> Result<String, IPWorksSNMPError> 
fn set_ssl_cert_store_password(&self, value : &str) ->  Option<IPWorksSNMPError> 
fn set_ssl_cert_store_password_ref(&self, value : &String) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Data Type

String

ssl_cert_store_type property (SNMPTrapMgr Struct)

The type of certificate store for this certificate.

Syntax

fn ssl_cert_store_type(&self ) -> Result<i32, IPWorksSNMPError> 
fn set_ssl_cert_store_type(&self, value : i32) ->  Option<IPWorksSNMPError> 

Possible Values

0   // User
1   // Machine
2   // PFXFile
3   // PFXBlob
4   // JKSFile
5   // JKSBlob
6   // PEMKeyFile
7   // PEMKeyBlob
8   // PublicKeyFile
9   // PublicKeyBlob
10   // SSHPublicKeyBlob
11   // P7BFile
12   // P7BBlob
13   // SSHPublicKeyFile
14   // PPKFile
15   // PPKBlob
16   // XMLFile
17   // XMLBlob
18   // JWKFile
19   // JWKBlob
20   // SecurityKey
21   // BCFKSFile
22   // BCFKSBlob
23   // PKCS11
99   // Auto

Default Value

0

Remarks

The type of certificate store for this certificate.

The struct supports both public and private keys in a variety of formats. When the cstAuto value is used, the struct will automatically determine the type. This property can take one of the following values:

Data Type

i32

ssl_cert_subject_alt_names property (SNMPTrapMgr Struct)

Comma-separated lists of alternative subject names for the certificate.

Syntax

fn ssl_cert_subject_alt_names(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_md5 property (SNMPTrapMgr Struct)

The MD5 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_md5(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha1 property (SNMPTrapMgr Struct)

The SHA-1 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha1(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_thumbprint_sha256 property (SNMPTrapMgr Struct)

The SHA-256 hash of the certificate.

Syntax

fn ssl_cert_thumbprint_sha256(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

Data Type

String

ssl_cert_usage property (SNMPTrapMgr Struct)

The text description of UsageFlags .

Syntax

fn ssl_cert_usage(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The text description of ssl_cert_usage_flags.

This value will be one or more of the following strings and will be separated by commas:

• Digital Signature
• Non-Repudiation
• Key Encipherment
• Data Encipherment
• Key Agreement
• Certificate Signing
• CRL Signing
• Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

Data Type

String

ssl_cert_usage_flags property (SNMPTrapMgr Struct)

The flags that show intended use for the certificate.

Syntax

fn ssl_cert_usage_flags(&self ) -> Result<i32, IPWorksSNMPError> 

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

Data Type

i32

ssl_cert_version property (SNMPTrapMgr Struct)

The certificate's version number.

Syntax

fn ssl_cert_version(&self ) -> Result<String, IPWorksSNMPError> 

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

Data Type

String

ssl_cert_subject property (SNMPTrapMgr Struct)

The subject of the certificate used for client authentication.

Syntax

fn ssl_cert_subject(&self ) -> Result<String, IPWorksSNMPError> 
fn set_ssl_cert_subject(&self, value : &str) ->  Option<IPWorksSNMPError> 
fn set_ssl_cert_subject_ref(&self, value : &String) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=example@email.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

Data Type

String

ssl_cert_encoded property (SNMPTrapMgr Struct)

The certificate (PEM/Base64 encoded).

Syntax

fn ssl_cert_encoded(&self ) -> Result<Vec<u8>, IPWorksSNMPError> 
fn set_ssl_cert_encoded(&self, value : Vec<u8>) ->  Option<IPWorksSNMPError> 
fn set_ssl_cert_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksSNMPError> 

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

Data Type

Vec

ssl_enabled property (SNMPTrapMgr Struct)

Whether DTLS is enabled.

Syntax

fn ssl_enabled(&self ) -> Result<bool, IPWorksSNMPError> 
fn set_ssl_enabled(&self, value : bool) ->  Option<IPWorksSNMPError> 

Default Value

false

Remarks

This setting specifies whether DTLS is enabled in the struct. When False (default) the struct operates in plaintext mode. When True DTLS is enabled.

Data Type

bool

activate method (SNMPTrapMgr Struct)

Activates the struct.

Syntax

fn activate(&self) -> Result<(), IPWorksSNMPError>

Remarks

This method activates the component and will allow it to send or receive data.

The struct will be automatically activated if it is not already and you attempt to perform an operation which requires the struct to be active.

NOTE: Use the active property to check whether the component is active.

add_engine method (SNMPTrapMgr Struct)

Adds the engine specified by EngineId to the internal authentication cache.

Syntax

fn add_engine(&self, engine_id : &[u8], engine_boots : i32, engine_time : i32) -> Result<(), IPWorksSNMPError>

Remarks

The internal authentication cache can be used as an alternative to the on_get_user_password event, automatically checking the cache against the security parameters provided in the request signature.

The show_cache method is used to show the contents of the internal authentication cache.

The clear_cache method can be used to completely clear the cache.

If the engine parameters are unknown, the SNMPMgr struct's Discover method can be used to perform a discovery with the agent. The RemoteEngineId, RemoteEngineTime, and RemoteEngineBoots properties will hold the values that can then be passed to this method.

add_user method (SNMPTrapMgr Struct)

Adds a user for the engine specified by EngineId to the internal authentication cache.

Syntax

fn add_user(&self, user : &str, engine_id : &[u8], authentication_protocol : i32, authentication_password : &str, encryption_algorithm : i32, encryption_password : &str) -> Result<(), IPWorksSNMPError>

Remarks

The internal authentication cache can be used as an alternative to the on_get_user_password event, automatically checking the cache against the security parameters provided in the request signature.

The show_cache method is used to show the contents of the internal authentication cache.

The clear_cache method can be used to completely clear the cache.

Valid Authentication Protocols are:

Valid Encryption Algorithms are:

clear_cache method (SNMPTrapMgr Struct)

Clears the internal authentication database.

Syntax

fn clear_cache(&self) -> Result<(), IPWorksSNMPError>

Remarks

All user and engine records are removed from the internal authentication cache as a result of this call.

config method (SNMPTrapMgr Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksSNMPError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

deactivate method (SNMPTrapMgr Struct)

Deactivates the struct.

Syntax

fn deactivate(&self) -> Result<(), IPWorksSNMPError>

Remarks

This method deactivates the component and will prohibit it from sending and receiving data.

NOTE: Use the active property to check whether the component is active.

do_events method (SNMPTrapMgr Struct)

This method processes events from the internal message queue.

Syntax

fn do_events(&self) -> Result<(), IPWorksSNMPError>

Remarks

When do_events is called, the struct processes any available events. If no events are available, it waits for a preset period of time, and then returns.

hash_passwords method (SNMPTrapMgr Struct)

Hashes all passwords in the cache.

Syntax

fn hash_passwords(&self) -> Result<(), IPWorksSNMPError>

Remarks

Forces computation of all passwords hashes in the cache. Used together with the on_hash_password event to enable implementations of external password hash storage.

pause_data method (SNMPTrapMgr Struct)

This method pauses data reception.

Syntax

fn pause_data(&self) -> Result<(), IPWorksSNMPError>

Remarks

This method pauses data reception when called. While data reception is paused, the on_data_in event will not fire. Call process_data to reenable data reception.

process_data method (SNMPTrapMgr Struct)

This method reenables data reception after a call to PauseData .

Syntax

fn process_data(&self) -> Result<(), IPWorksSNMPError>

Remarks

This method reenables data reception after a previous call to pause_data. When pause_data is called, the on_data_in event will not fire. To reenable data reception and allow on_data_in to fire, call this method.

NOTE: This method is used only after previously calling pause_data. It does not need to be called to process incoming data by default.

remove_engine method (SNMPTrapMgr Struct)

Removes the engine specified by EngineId from the internal authentication cache.

Syntax

fn remove_engine(&self, engine_id : &[u8]) -> Result<(), IPWorksSNMPError>

Remarks

The internal authentication cache can be used as an alternative to the on_get_user_password event, automatically checking the cache against the security parameters provided in the request signature.

The show_cache method is used to show the contents of the internal authentication cache.

The clear_cache method can be used to completely clear the cache.

remove_user method (SNMPTrapMgr Struct)

Removes the user specified by User of the engine specified by EngineId from the internal authentication cache.

Syntax

fn remove_user(&self, user : &str, engine_id : &[u8]) -> Result<(), IPWorksSNMPError>

Remarks

The internal authentication cache can be used as an alternative to the on_get_user_password event, automatically checking the cache against the security parameters provided in the request signature.

The show_cache method is used to show the contents of the internal authentication cache.

The clear_cache method can be used to completely clear the cache.

reset method (SNMPTrapMgr Struct)

Clears the object arrays.

Syntax

fn reset(&self) -> Result<(), IPWorksSNMPError>

Remarks

Clears the object arrays, and sets the trap and error properties to their default values. This is useful for reinitializing all the properties that are used to create outgoing packets before building a new packet.

Note: snmp_version will be reset to snmpverV2c (2).

show_cache method (SNMPTrapMgr Struct)

Lists all entries in the internal user and engine database.

Syntax

fn show_cache(&self) -> Result<(), IPWorksSNMPError>

Remarks

A on_cache_entry event is fired for every record in the database.

value method (SNMPTrapMgr Struct)

Returns the value corresponding to an OID.

Syntax

fn value(&self, oid : &str) ->  Result<String, IPWorksSNMPError>

Remarks

If the OID does not exist in the objects collection, a trappable error is generated.

Please refer to the SNMPObject type for more information.

on_bad_packet event (SNMPTrapMgr Struct)

Fired for erroneous and/or malformed messages.

Syntax

// SNMPTrapMgrBadPacketEventArgs carries the SNMPTrapMgr BadPacket event's parameters.
pub struct SNMPTrapMgrBadPacketEventArgs {
  fn packet(&self) -> &[u8]
  fn source_address(&self) -> &String
  fn source_port(&self) -> i32
  fn error_code(&self) -> i32
  fn error_description(&self) -> &String
  fn report(&self) -> bool
  fn set_report(&self, value : bool)
}

// SNMPTrapMgrBadPacketEvent defines the signature of the SNMPTrapMgr BadPacket event's handler function.
pub trait SNMPTrapMgrBadPacketEvent {
  fn on_bad_packet(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrBadPacketEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_bad_packet(&self) -> &'a dyn SNMPTrapMgrBadPacketEvent;
  pub fn set_on_bad_packet(&mut self, value : &'a dyn SNMPTrapMgrBadPacketEvent);
  ...
}

Remarks

The full message is provided in the Packet parameter.

The on_bad_packet event is also fired when authentication fails for received packets due to a bad password or other reasons.

If the Report parameter is set to True, an unauthenticated error report will be sent to the client, otherwise the packet will be silently ignored.

Please refer to the on_get_user_password event for more information concerning SNMPv3 authentication.

on_cache_entry event (SNMPTrapMgr Struct)

Shows engines and users in the internal cache.

Syntax

// SNMPTrapMgrCacheEntryEventArgs carries the SNMPTrapMgr CacheEntry event's parameters.
pub struct SNMPTrapMgrCacheEntryEventArgs {
  fn engine_id(&self) -> &[u8]
  fn engine_boots(&self) -> i32
  fn engine_time(&self) -> i32
  fn user(&self) -> &String
  fn authentication_protocol(&self) -> &String
  fn authentication_password(&self) -> &String
  fn encryption_algorithm(&self) -> &String
  fn encryption_password(&self) -> &String
}

// SNMPTrapMgrCacheEntryEvent defines the signature of the SNMPTrapMgr CacheEntry event's handler function.
pub trait SNMPTrapMgrCacheEntryEvent {
  fn on_cache_entry(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrCacheEntryEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_cache_entry(&self) -> &'a dyn SNMPTrapMgrCacheEntryEvent;
  pub fn set_on_cache_entry(&mut self, value : &'a dyn SNMPTrapMgrCacheEntryEvent);
  ...
}

Remarks

on_cache_entry events are triggered by a call to show_cache. One event is fired for each user and engine. If there are no users for a particular engine, a single event is fired with the engine information, but empty values for user information.

on_check_engine event (SNMPTrapMgr Struct)

Fired to check engine parameters (timeliness, etc.).

Syntax

// SNMPTrapMgrCheckEngineEventArgs carries the SNMPTrapMgr CheckEngine event's parameters.
pub struct SNMPTrapMgrCheckEngineEventArgs {
  fn engine_id(&self) -> &[u8]
  fn engine_boots(&self) -> i32
  fn engine_time(&self) -> i32
  fn user(&self) -> &String
  fn security_level(&self) -> i32
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn is_new(&self) -> bool
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// SNMPTrapMgrCheckEngineEvent defines the signature of the SNMPTrapMgr CheckEngine event's handler function.
pub trait SNMPTrapMgrCheckEngineEvent {
  fn on_check_engine(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrCheckEngineEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_check_engine(&self) -> &'a dyn SNMPTrapMgrCheckEngineEvent;
  pub fn set_on_check_engine(&mut self, value : &'a dyn SNMPTrapMgrCheckEngineEvent);
  ...
}

Remarks

The Accept parameter determines if the engine will be accepted or not. If you set Accept to False prior to exiting the event, the processing on the message will stop and a on_bad_packet event will be fired.

The default value of Accept is True if and only if:

a) the engine already exists in the internal authentication cache (the IsNew parameter is False) and the timeliness has been verified;

b) the engine does not exist in the internal authentication cache (the IsNew parameter is True), but the packet has been authenticated by the struct (SecurityLevel >= 1).

In all other cases, the default value for Accept is False, and you are responsible for accepting or not accepting the engine based on other considerations.

If Accept is true upon event exit, then:

a) if the engine already exists in the internal authentication cache, its time is updated to reflect the new time and the processing of the packet continues;

b) if the engine does not exist in the internal authentication cache, it is added there and if User is authenticated, the User will be added too.

on_connected event (SNMPTrapMgr Struct)

Fired immediately after a connection completes (or fails).

Syntax

// SNMPTrapMgrConnectedEventArgs carries the SNMPTrapMgr Connected event's parameters.
pub struct SNMPTrapMgrConnectedEventArgs {
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// SNMPTrapMgrConnectedEvent defines the signature of the SNMPTrapMgr Connected event's handler function.
pub trait SNMPTrapMgrConnectedEvent {
  fn on_connected(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrConnectedEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_connected(&self) -> &'a dyn SNMPTrapMgrConnectedEvent;
  pub fn set_on_connected(&mut self, value : &'a dyn SNMPTrapMgrConnectedEvent);
  ...
}

Remarks

This event fires after a connection completes or fails.

StatusCode is the value returned by the system TCP/IP stack. This will be 0 if the connection was successful.

Description contains a human readable description of the status. This will be "OK" if the connection was successful.

RemoteAddress is the IP address of the remote host.

RemotePort is the port on the remote host.

on_disconnected event (SNMPTrapMgr Struct)

Fired when a connection is closed.

Syntax

// SNMPTrapMgrDisconnectedEventArgs carries the SNMPTrapMgr Disconnected event's parameters.
pub struct SNMPTrapMgrDisconnectedEventArgs {
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn status_code(&self) -> i32
  fn description(&self) -> &String
}

// SNMPTrapMgrDisconnectedEvent defines the signature of the SNMPTrapMgr Disconnected event's handler function.
pub trait SNMPTrapMgrDisconnectedEvent {
  fn on_disconnected(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrDisconnectedEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_disconnected(&self) -> &'a dyn SNMPTrapMgrDisconnectedEvent;
  pub fn set_on_disconnected(&mut self, value : &'a dyn SNMPTrapMgrDisconnectedEvent);
  ...
}

Remarks

This event fires after a connection is broken.

StatusCode is the value returned by the system TCP/IP stack. This will be 0 if the connection was broken normally.

Description contains a human readable description of the status. This will be "OK" if the connection was broken normally.

RemoteAddress is the IP address of the remote host.

RemotePort is the port on the remote host.

on_discovery_request event (SNMPTrapMgr Struct)

Fired when an SNMPv3 discovery packet is received.

Syntax

// SNMPTrapMgrDiscoveryRequestEventArgs carries the SNMPTrapMgr DiscoveryRequest event's parameters.
pub struct SNMPTrapMgrDiscoveryRequestEventArgs {
  fn engine_id(&self) -> &[u8]
  fn engine_boots(&self) -> i32
  fn engine_time(&self) -> i32
  fn user(&self) -> &String
  fn security_level(&self) -> i32
  fn source_address(&self) -> &String
  fn source_port(&self) -> i32
  fn respond(&self) -> bool
  fn set_respond(&self, value : bool)
}

// SNMPTrapMgrDiscoveryRequestEvent defines the signature of the SNMPTrapMgr DiscoveryRequest event's handler function.
pub trait SNMPTrapMgrDiscoveryRequestEvent {
  fn on_discovery_request(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrDiscoveryRequestEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_discovery_request(&self) -> &'a dyn SNMPTrapMgrDiscoveryRequestEvent;
  pub fn set_on_discovery_request(&mut self, value : &'a dyn SNMPTrapMgrDiscoveryRequestEvent);
  ...
}

Remarks

EngineId, EngineBoots, EngineTime, and User are the values received from SourceAddress.

For SNMPv3, the User parameter shows the user that was supplied with the packet. This parameter MUST be used together with the SecurityLevel parameter which shows the level of security in the message.

The SecurityLevel parameter shows whether the request has been authenticated. If SecurityLevel is 0, the request has NOT been authenticated (i.e. the packet signature has not been verified). For an authenticated, non encrypted request, SecurityLevel is 1. For an authenticated and encrypted request, SecurityLevel is 2.

Respond is True by default, and will automatically send a response using the value in local_engine_id. To suppress the response, set Respond to False.

The value returned to SourceAddress for EngineBoots is always 0, and EngineTime is the number of seconds since January 1st, 1970 (GMT).

on_error event (SNMPTrapMgr Struct)

Fired when information is available about errors during data delivery.

Syntax

// SNMPTrapMgrErrorEventArgs carries the SNMPTrapMgr Error event's parameters.
pub struct SNMPTrapMgrErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// SNMPTrapMgrErrorEvent defines the signature of the SNMPTrapMgr Error event's handler function.
pub trait SNMPTrapMgrErrorEvent {
  fn on_error(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrErrorEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_error(&self) -> &'a dyn SNMPTrapMgrErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn SNMPTrapMgrErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_get_user_password event (SNMPTrapMgr Struct)

Retrieves a password associated with a user.

Syntax

// SNMPTrapMgrGetUserPasswordEventArgs carries the SNMPTrapMgr GetUserPassword event's parameters.
pub struct SNMPTrapMgrGetUserPasswordEventArgs {
  fn password_type(&self) -> i32
  fn user(&self) -> &String
  fn engine_id(&self) -> &[u8]
  fn password(&self) -> &String
  fn set_password(&self, value : &str)
  fn set_password_ref(&self, value : &String)
  fn algorithm(&self) -> i32
  fn set_algorithm(&self, value : i32)
}

// SNMPTrapMgrGetUserPasswordEvent defines the signature of the SNMPTrapMgr GetUserPassword event's handler function.
pub trait SNMPTrapMgrGetUserPasswordEvent {
  fn on_get_user_password(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrGetUserPasswordEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_get_user_password(&self) -> &'a dyn SNMPTrapMgrGetUserPasswordEvent;
  pub fn set_on_get_user_password(&mut self, value : &'a dyn SNMPTrapMgrGetUserPasswordEvent);
  ...
}

Remarks

The on_get_user_password event is fired after initial inspection of SNMPv3 requests.

The type of password required is provided in the PasswordType parameter: 1 for authentication, and 2 for encryption (privacy).

The password corresponding to User and EngineId must be provided in the Password parameter. If the password is valid, processing will continue to other events such as on_get_request, on_set_request, etc.

If the PasswordType parameter is 1 (authentication is used), the Algorithm parameter can be set. Possible values are:

If the PasswordType parameter is 2 (encryption is used), the Algorithm parameter must also be set. Possible values are:

If the password does not match the signature in the request, a on_bad_packet event will be fired, at which point you can decide whether to report the error to the client (see the description of the on_bad_packet event for more information).

If the User is invalid or unknown, set the password to empty string (default) to ignore the request. This will result in a on_bad_packet event being fired, at which point you can decide whether to report the error to the client or not.

on_get_user_security_level event (SNMPTrapMgr Struct)

Sets the security level for an incoming packet.

Syntax

// SNMPTrapMgrGetUserSecurityLevelEventArgs carries the SNMPTrapMgr GetUserSecurityLevel event's parameters.
pub struct SNMPTrapMgrGetUserSecurityLevelEventArgs {
  fn user(&self) -> &String
  fn engine_id(&self) -> &[u8]
  fn security_level(&self) -> i32
  fn set_security_level(&self, value : i32)
}

// SNMPTrapMgrGetUserSecurityLevelEvent defines the signature of the SNMPTrapMgr GetUserSecurityLevel event's handler function.
pub trait SNMPTrapMgrGetUserSecurityLevelEvent {
  fn on_get_user_security_level(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrGetUserSecurityLevelEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_get_user_security_level(&self) -> &'a dyn SNMPTrapMgrGetUserSecurityLevelEvent;
  pub fn set_on_get_user_security_level(&mut self, value : &'a dyn SNMPTrapMgrGetUserSecurityLevelEvent);
  ...
}

Remarks

The on_get_user_security_level event is fired after the first inspection of each SNMPv3 request. The SecurityLevel parameter determines the level of security for the message.

On entry, the SecurityLevel parameter contains the default security level for User if the user is located in the internal cache, or if the User is not found in the cache, the SecurityLevel will be -1.

The value of SecurityLevel upon exiting the event, determines how the message will be processed:

on_hash_password event (SNMPTrapMgr Struct)

Fired before and after a password is hashed.

Syntax

// SNMPTrapMgrHashPasswordEventArgs carries the SNMPTrapMgr HashPassword event's parameters.
pub struct SNMPTrapMgrHashPasswordEventArgs {
  fn password(&self) -> &String
  fn auth_algorithm(&self) -> i32
  fn hash(&self) -> &String
  fn set_hash(&self, value : &str)
  fn set_hash_ref(&self, value : &String)
}

// SNMPTrapMgrHashPasswordEvent defines the signature of the SNMPTrapMgr HashPassword event's handler function.
pub trait SNMPTrapMgrHashPasswordEvent {
  fn on_hash_password(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrHashPasswordEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_hash_password(&self) -> &'a dyn SNMPTrapMgrHashPasswordEvent;
  pub fn set_on_hash_password(&mut self, value : &'a dyn SNMPTrapMgrHashPasswordEvent);
  ...
}

Remarks

SNMPv3 passwords are hashed in order to obtain authentication and encryption keys. This is an expensive operation, and in certain situations it may be preferable to store the hashed passwords externally and supply them on demand.

If a hash is required, the event fires with an empty string in the Hash parameter. In this case, you can choose to supply a value for the hash and stop the struct from computing the hash.

The event also fires every time a hash is computed. In this case, the Hash parameter contains the value of the computed hash.

AuthAlgorithm contains either 1 for HMAC-MD5-96, 2 for HMAC-SHA-96 or 3 for HMAC-192-SHA-256

on_inform_request event (SNMPTrapMgr Struct)

Fired when an InformRequest packet is received.

Syntax

// SNMPTrapMgrInformRequestEventArgs carries the SNMPTrapMgr InformRequest event's parameters.
pub struct SNMPTrapMgrInformRequestEventArgs {
  fn request_id(&self) -> i32
  fn snmp_version(&self) -> i32
  fn community(&self) -> &String
  fn user(&self) -> &String
  fn security_level(&self) -> i32
  fn source_address(&self) -> &String
  fn source_port(&self) -> i32
  fn error_index(&self) -> i32
  fn set_error_index(&self, value : i32)
  fn error_status(&self) -> i32
  fn set_error_status(&self, value : i32)
  fn error_description(&self) -> &String
  fn respond(&self) -> bool
  fn set_respond(&self, value : bool)
}

// SNMPTrapMgrInformRequestEvent defines the signature of the SNMPTrapMgr InformRequest event's handler function.
pub trait SNMPTrapMgrInformRequestEvent {
  fn on_inform_request(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrInformRequestEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_inform_request(&self) -> &'a dyn SNMPTrapMgrInformRequestEvent;
  pub fn set_on_inform_request(&mut self, value : &'a dyn SNMPTrapMgrInformRequestEvent);
  ...
}

Remarks

For SNMPv3, the User parameter shows the user that was supplied with the packet. This parameter MUST be used together with the SecurityLevel parameter which shows the level of security in the message.

The SecurityLevel parameter shows whether the request has been authenticated. If SecurityLevel is 0, the request has NOT been authenticated (i.e. the packet signature has not been verified). For an authenticated, non encrypted request, SecurityLevel is 1. For an authenticated and encrypted request, SecurityLevel is 2.

The user in an InformRequest packet (SNMPv3) must be a valid user in the internal authentication cache (see the add_user method and the on_check_engine event for more information). If not, the request is rejected, and a on_bad_packet event is fired before on_inform_request is fired.

The list of variables in the SNMP packet, including optional values and types, is provided through the objects collection. Each object is of type SNMPObject. This type describes the obj_id, obj_type, and obj_value of each SNMP object. These variables must be copied to another location before the event has completed executing, or they may be overridden by other events.

The SourceAddress and SourcePort parameters show the address and port of the sender as reported by the TCP/IP stack.

The MessageId parameter identifies the received request.

For SNMPv3, the User parameter shows the user that was supplied with the packet. This parameter MUST be used together with the SecurityLevel parameter which shows the level of security in the message.

The SecurityLevel parameter shows whether the request has been authenticated. If SecurityLevel is 0, the request has NOT been authenticated (i.e. the packet signature has not been verified). For an authenticated, non encrypted request, SecurityLevel is 1. For an authenticated and encrypted request, SecurityLevel is 2.

To send a response, the Respond parameter must be set to true. By default, this value is false, which means no response will be sent. The ErrorStatus parameter may also be set to a valid SNMP status code (the default value is 0, which represents no error).

The following is a list of valid SNMP status code values:

The ErrorIndex parameter indicates the index of the first variable (object) that caused an error. The default value is 0.

Variable indexes start with 0. ErrorIndex has no meaning when ErrorStatus is 0 (no error).

on_packet_trace event (SNMPTrapMgr Struct)

Fired for every packet sent or received.

Syntax

// SNMPTrapMgrPacketTraceEventArgs carries the SNMPTrapMgr PacketTrace event's parameters.
pub struct SNMPTrapMgrPacketTraceEventArgs {
  fn packet(&self) -> &[u8]
  fn direction(&self) -> i32
  fn packet_address(&self) -> &String
  fn packet_port(&self) -> i32
}

// SNMPTrapMgrPacketTraceEvent defines the signature of the SNMPTrapMgr PacketTrace event's handler function.
pub trait SNMPTrapMgrPacketTraceEvent {
  fn on_packet_trace(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrPacketTraceEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_packet_trace(&self) -> &'a dyn SNMPTrapMgrPacketTraceEvent;
  pub fn set_on_packet_trace(&mut self, value : &'a dyn SNMPTrapMgrPacketTraceEvent);
  ...
}

Remarks

The on_packet_trace event shows all the packets sent or received by the struct.

Packet contains the full contents of the datagram.

Direction shows the direction of the packet: 1 for incoming packets, and 2 for outgoing packets.

In the case of an incoming packet, PacketAddress and PacketPort identify the source of the packet.

In the case of an outgoing packet, PacketAddress and PacketPort identify the destination of the packet.

on_ssl_client_authentication event (SNMPTrapMgr Struct)

Fired when the client presents its credentials to the server.

Syntax

// SNMPTrapMgrSSLClientAuthenticationEventArgs carries the SNMPTrapMgr SSLClientAuthentication event's parameters.
pub struct SNMPTrapMgrSSLClientAuthenticationEventArgs {
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn cert_encoded(&self) -> &[u8]
  fn cert_subject(&self) -> &String
  fn cert_issuer(&self) -> &String
  fn status(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// SNMPTrapMgrSSLClientAuthenticationEvent defines the signature of the SNMPTrapMgr SSLClientAuthentication event's handler function.
pub trait SNMPTrapMgrSSLClientAuthenticationEvent {
  fn on_ssl_client_authentication(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrSSLClientAuthenticationEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_ssl_client_authentication(&self) -> &'a dyn SNMPTrapMgrSSLClientAuthenticationEvent;
  pub fn set_on_ssl_client_authentication(&mut self, value : &'a dyn SNMPTrapMgrSSLClientAuthenticationEvent);
  ...
}

Remarks

This event fires when a client connects to the struct and presents a certificate for authentication. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK").

RemoteAddress is the IP address of the connecting client.

RemotePort is the source port of the connecting client.

CertEncoded is the base64 encoded certificate presented by the client.

CertSubject is the subject of the certificate presented by the client.

CertIssuer is the subject of the issuer of the certificate presented by the client.

Status is the status of the certificate.

Accept defines whether the certificate is accepted.

on_ssl_status event (SNMPTrapMgr Struct)

Shows the progress of the secure connection.

Syntax

// SNMPTrapMgrSSLStatusEventArgs carries the SNMPTrapMgr SSLStatus event's parameters.
pub struct SNMPTrapMgrSSLStatusEventArgs {
  fn remote_address(&self) -> &String
  fn remote_port(&self) -> i32
  fn message(&self) -> &String
}

// SNMPTrapMgrSSLStatusEvent defines the signature of the SNMPTrapMgr SSLStatus event's handler function.
pub trait SNMPTrapMgrSSLStatusEvent {
  fn on_ssl_status(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrSSLStatusEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_ssl_status(&self) -> &'a dyn SNMPTrapMgrSSLStatusEvent;
  pub fn set_on_ssl_status(&mut self, value : &'a dyn SNMPTrapMgrSSLStatusEvent);
  ...
}

Remarks

The event is fired for informational and logging purposes only. It is used to track the progress of the connection.

RemoteAddress is the IP address of the remote machine.

RemotePort is the port of the remote machine.

Message is the log message.

on_trap event (SNMPTrapMgr Struct)

Fired when a SNMP trap packet is received.

Syntax

// SNMPTrapMgrTrapEventArgs carries the SNMPTrapMgr Trap event's parameters.
pub struct SNMPTrapMgrTrapEventArgs {
  fn request_id(&self) -> i32
  fn snmp_version(&self) -> i32
  fn community(&self) -> &String
  fn user(&self) -> &String
  fn security_level(&self) -> i32
  fn trap_oid(&self) -> &String
  fn time_stamp(&self) -> i64
  fn agent_address(&self) -> &String
  fn source_address(&self) -> &String
  fn source_port(&self) -> i32
}

// SNMPTrapMgrTrapEvent defines the signature of the SNMPTrapMgr Trap event's handler function.
pub trait SNMPTrapMgrTrapEvent {
  fn on_trap(&self, sender : SNMPTrapMgr, e : &mut SNMPTrapMgrTrapEventArgs);
}

impl <'a> SNMPTrapMgr<'a> {
  pub fn on_trap(&self) -> &'a dyn SNMPTrapMgrTrapEvent;
  pub fn set_on_trap(&mut self, value : &'a dyn SNMPTrapMgrTrapEvent);
  ...
}

Remarks

The TrapOID and TimeStamp parameters contain the Trap OID and TimeStamp. In the case of an SNMPv1 trap, there are two possible scenarios:

First, if the enterprise of the trap is "1.3.6.1.6.3.1.1.5", TrapOID will be a concatenation of TrapEnterprise and GenericTrap + 1. For instance a TrapOID of "1.3.6.1.6.3.1.1.5.5" has a TrapEnterprise of "1.3.6.1.6.3.1.1.5" and a GenericTrap of "4".

Second, In all other cases TrapOID will be a concatenation of the values for TrapEnterprise, GenericTrap, and SpecificTrap, separated by '.'.

For SNMPv2 and above, they are read from the variable-value list (if available).

For SNMPv3, the User parameter shows the user that was supplied with the packet. This parameter MUST be used together with the SecurityLevel parameter which shows the level of security in the message.

The SecurityLevel parameter shows whether the request has been authenticated. If SecurityLevel is 0, the request has NOT been authenticated (i.e. the packet signature has not been verified). For an authenticated, non encrypted request, SecurityLevel is 1. For an authenticated and encrypted request, SecurityLevel is 2.

The list of variables in the SNMP packet, including optional values and types, is provided through the objects collection. Each object is of type SNMPObject. This type describes the obj_id, obj_type, and obj_value of each SNMP object. These variables must be copied to another location before the event has completed executing, or they may be overridden by other events.

The SourceAddress and SourcePort parameters show the address and port of the sender as reported by the TCP/IP stack.

Some parameters are only applicable depending on the SNMPVersion value. The table below shows which parameters are applicable to which SNMP versions.

Config Settings (SNMPTrapMgr Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

SNMPTrapMgr Config Settings

UDP Config Settings

Socket Config Settings

Base Config Settings

Trappable Errors (SNMPTrapMgr Struct)

SNMPTrapMgr Errors

The class may also return one of the following error codes, which are inherited from other classes.

UDP Errors

SSL Errors

TCP/IP Errors