From 7558861af77de9405decc8d88b2c799e15f266da Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Tue, 10 Sep 2013 10:18:53 +0200 Subject: [snmp/manager] Improve handling of unexpected/invalid snmpm_user callbacks Improved handling of unexpected return values from snmpm_user callback functions. Violations of the documented API (crashes or invalid return values) will now result in an error message. Updated doc for snmpm_user bahaviour and some other stuff. Add more (common) type defs. Update manager example. Fixed manager test(s). Fixed unused vars in (manager) test suite. Make test user follow defined behaviour. --- lib/snmp/doc/src/notes.xml | 85 ++++++++++++++++++ lib/snmp/doc/src/snmpm_user.xml | 187 +++++++++++++++++++++++----------------- 2 files changed, 191 insertions(+), 81 deletions(-) (limited to 'lib/snmp/doc') diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml index 21c417f0c1..646e3027d6 100644 --- a/lib/snmp/doc/src/notes.xml +++ b/lib/snmp/doc/src/notes.xml @@ -33,6 +33,91 @@ +
+ SNMP Development Toolkit 4.25 +

Version 4.25 supports code replacement in runtime from/to + version 4.24.1, 4.24, 4.23.1 and 4.23.

+ +
+ Improvements and new features + + + + +

[manager] Improved handling of unexpected return values from + snmpm_user + callback functions.

+

Violations of the documented API (crashes or invalid return + values) will now result in an error message.

+

Own Id: OTP-11307

+ + + + +
+ +
+ Fixed Bugs and Malfunctions +

-

+ + + +
+ +
+ Incompatibilities + + + + +

[manager] The + snmpm_user + callback functions are no longer allowed to "return" via + exit or throw.

+

Own Id: OTP-11307

+ + + +
+ +
+ +
SNMP Development Toolkit 4.24.1

Version 4.24.1 supports code replacement in runtime from/to diff --git a/lib/snmp/doc/src/snmpm_user.xml b/lib/snmp/doc/src/snmpm_user.xml index 1823e0c815..cb2deab976 100644 --- a/lib/snmp/doc/src/snmpm_user.xml +++ b/lib/snmp/doc/src/snmpm_user.xml @@ -1,10 +1,10 @@ - +

- 20042009 + 20042013 Ericsson AB. All Rights Reserved. @@ -56,40 +56,59 @@

handle_report/3

 + +

handle_invalid_result/2

+

The semantics of them and their exact signatures are explained - below.

-

Note that if an agent is registered using the old, no longer - documented, functions (using Addr and Port), the old variant of the - callback functions, handle_pdu, handle_trap, handle_inform and - handle_report, will be called.

+ below.

+

Some of the function has no defined return value (void()), + they can ofcourse return anythyng. But the functions that do have + specified return value(s) must adhere to this. None of the + functions can use exit of throw to return.

- + + +
+ DATA TYPES + + +
+ - handle_error(ReqId, Reason, UserData) -> Reply + handle_error(ReqId, Reason, UserData) -> void() Handle error ReqId = integer() Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info, SecInfo, SnmpInfo} | {empty_message, Addr, Port} | term() + SnmpInfo = snmp_gen_info() + SecInfo = term() Addr = ip_address() Port = integer() UserData = term() - Reply = ignore

This function is called when the manager needs to - communicate an "asynchronous" error, to the user: - e.g. failure to send an asynchronous message (i.e. encoding - error), a received message was discarded due to security - error, the manager failed to generate a response message to - a received inform-request, or when receiving an unexpected - PDU from an agent (could be an expired async request).

-

If ReqId is less then 0, it means that this - information was not available to the manager (that info was - never retrieved before the message was discarded). -

+ communicate an "asynchronous" error to the user: + e.g. failure to send an asynchronous message (i.e. encoding + error), a received message was discarded due to security + error, the manager failed to generate a response message to + a received inform-request, or when receiving an unexpected + PDU from an agent (could be an expired async request).

+

If ReqId is less then 0, it means that this + information was not available to the manager (that info was + never retrieved before the message was discarded).

For SnmpInfo see handle_agent below.

@@ -104,22 +123,22 @@ Port = integer() Type = pdu | trap | report | inform SnmpInfo = SnmpPduInfo | SnmpTrapInfo | SnmpReportInfo | SnmpInformInfo - ErrorStatus = atom() - ErrorIndex = integer() - Varbinds = [varbind()] - varbind() = #varbind + SnmpPduInfo = snmp_gen_info() + SnmpTrapInfo = snmp_v1_trap_info() + SnmpReportInfo = snmp_gen_info() + SnmpInformInfo = snmp_gen_info() UserData = term() - Reply = ignore | {register, UserId, TargetName, agent_info()} + Reply = ignore | {register, UserId, TargetName, AgentConfig} UserId = term() TargetName = target_name() - agent_info() = [{agent_info_item(), agent_info_value()}] + AgentConfig = [agent_config()] -

This function is called when a message is received from an - unknown agent.

+

This function is called when a message is received from an + unknown agent.

Note that this will always be the default user that is called.

-

For more info about the agent_info(), see - register_agent.

+

For more info about the agent_config(), see + register_agent.

The arguments Type and SnmpInfo relates in the following way:

@@ -148,7 +167,7 @@

The only user which would return - {register, UserId, TargetName, agent_info()} is the + {register, UserId, TargetName, AgentConfig} is the default user.

@@ -156,18 +175,13 @@ - handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> Reply + handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> void() Handle the reply to an asynchronous request TargetName = target_name() ReqId = term() - SnmpPduInfo = {ErrorStatus, ErrorIndex, Varbinds} - ErrorStatus = atom() - ErrorIndex = integer() - Varbinds = [varbind()] - varbind() = #varbind + SnmpPduInfo = snmp_gen_info() UserData = term() - Reply = ignore

Handle the reply to an asynchronous request, such as @@ -186,27 +200,19 @@ Handle a trap/notification message TargetName = TargetName2 = target_name() - SnmpTrapInfo = {Enteprise, Generic, Spec, Timestamp, Varbinds} | {ErrorStatus, ErrorIndex, Varbinds} - Enterprise = oid() - Generic = integer() - Spec = integer() - Timestamp = integer() - ErrorStatus = atom() - ErrorIndex = integer() - Varbinds = [varbind()] - varbind() = #varbind + SnmpTrapInfo = snmp_v1_trap_info() | snmp_gen_info() UserData = term() - Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()} + Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig} UserId = term() - agent_info() = [{agent_info_item(), agent_info_value()}] + AgentConfig = [agent_config()]

Handle a trap/notification message from an agent.

-

For more info about the agent_info(), see - register_agent

+

For more info about the agent_config(), see + register_agent

The only user which would return - {register, UserId, TargetName2, agent_info()} is the - default user.

+ {register, UserId, TargetName2, agent_info()} is the + default user.

 @@ -217,29 +223,25 @@ Handle a inform message TargetName = TargetName2 = target_name() - SnmpInformInfo = {ErrorStatus, ErrorIndex, Varbinds} - ErrorStatus = atom() - ErrorIndex = integer() - Varbinds = [varbind()] - varbind() = #varbind + SnmpInformInfo = snmp_gen_info() UserData = term() - Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()} + Reply = ignore | no_reply | unregister | {register, UserId, TargetName2, AgentConfig} UserId = term() - agent_info() = [{agent_info_item(), agent_info_value()}] + AgentConfig = [agent_config()]

Handle a inform message.

-

For more info about the agent_info(), see - register_agent

+

For more info about the agent_config(), see + register_agent

The only user which would return - {register, UserId, TargetName2, agent_info()} is the - default user.

-

If the - inform request behaviour - configuration option is set to user or - {user, integer()}, the response (acknowledgment) to this - inform-request will be sent when this function returns.

- + {register, UserId, TargetName2, AgentConfig} is the + default user.

+

If the + inform request behaviour + configuration option is set to user or + {user, integer()}, the response (acknowledgment) to this + inform-request will be sent when this function returns.

+ @@ -251,23 +253,46 @@ TargetName = TargetName2 = target_name() Addr = ip_address() Port = integer() - SnmpReportInfo = {ErrorStatus, ErrorIndex, Varbinds} - ErrorStatus = atom() - ErrorIndex = integer() - Varbinds = [varbind()] - varbind() = #varbind + SnmpReportInfo = snmp_gen_info() UserData = term() - Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()} + Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig} UserId = term() - agent_info() = [{agent_info_item(), agent_info_value()}] + AgentConfig = [agent_config()]

Handle a report message.

-

For more info about the agent_info(), see - register_agent

+

For more info about the agent_config(), see + register_agent

The only user which would return - {register, UserId, TargetName2, agent_info()} is the - default user.

+ {register, UserId, TargetName2, AgentConfig} is the + default user.

+ + + + + + + handle_invalid_result(IN, OUT) -> void() + Handle a report message + + IN = {Func, Args} + Func = atom() + Args = list() + OUT = {crash, CrashInfo} | {result, InvalidResult} + CrashInfo = {ErrorType, Error, Stacktrace} + ErrorType = atom() + Error = term() + Stacktrace = list() + InvalidResult = term() + + +

If any of the other callback functions crashes + (exit, throw or a plain crash) or return an invalid result (if a valid + return has been specified), this function is called. + The purpose is to allow the user handle this + error (for instance to issue an error report).

+

IN reprecents the function called (and its arguments). + OUT represents the unexpected/invalid result.

-- cgit v1.2.3