[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.

1 files changed, 106 insertions, 81 deletions

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 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
   <header>
     <copyright>
-      <year>2004</year><year>2009</year>
+      <year>2004</year><year>2013</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -56,40 +56,59 @@
       <item>
         <p>handle_report/3</p>
       </item>
+      <item>
+        <p>handle_invalid_result/2</p>
+      </item>
     </list>
     <p>The semantics of them and their exact signatures are explained
-      below. </p>
-    <p>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. </p>
+    below. </p>
+    <p>Some of the function has no defined return value (<c>void()</c>), 
+    they can ofcourse return anythyng. But the functions that do have 
+    specified return value(s) <em>must</em> adhere to this. None of the 
+    functions can use exit of throw to return. </p>
 
-    <marker id="handle_error"></marker>
+    <marker id="types"></marker>
   </description>
+
+  <section>
+    <title>DATA TYPES</title>
+    <code type="none"><![CDATA[
+snmp_gen_info() = {ErrorStatus :: atom(), 
+                   ErrorIndex  :: pos_integer(), 
+                   Varbinds    :: [snmp:varbind()]}
+snmp_v1_trap_info() :: {Enteprise :: snmp:oid(), 
+                        Generic   :: integer(), 
+                        Spec      :: integer(), 
+                        Timestamp :: integer(), 
+                        Varbinds  :: [snmp:varbind()]}
+    ]]></code>
+    <marker id="handle_error"></marker>
+  </section>
+
   <funcs>
     <func>
-      <name>handle_error(ReqId, Reason, UserData) -> Reply</name>
+      <name>handle_error(ReqId, Reason, UserData) -> void()</name>
       <fsummary>Handle error</fsummary>
       <type>
         <v>ReqId = integer()</v>
         <v>Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info, SecInfo, SnmpInfo} | {empty_message, Addr, Port} | term()</v>
+        <v>SnmpInfo = snmp_gen_info()</v>
+        <v>SecInfo = term()</v>
         <v>Addr = ip_address()</v>
         <v>Port = integer()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore</v>
       </type>
       <desc>
         <p>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). </p>
-        <p>If <c>ReqId</c> 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). 
-          </p>
+	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). </p>
+	<p>If <c>ReqId</c> 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). </p>
         <p>For <c>SnmpInfo</c> see handle_agent below.</p>
 
         <marker id="handle_agent"></marker>
@@ -104,22 +123,22 @@
         <v>Port = integer()</v>
         <v>Type = pdu | trap | report | inform</v>
         <v>SnmpInfo = SnmpPduInfo | SnmpTrapInfo | SnmpReportInfo | SnmpInformInfo</v>
-        <v>ErrorStatus = atom()</v>
-        <v>ErrorIndex = integer()</v>
-        <v>Varbinds = [varbind()]</v>
-        <v>varbind() = #varbind</v>
+        <v>SnmpPduInfo = snmp_gen_info()</v>
+        <v>SnmpTrapInfo = snmp_v1_trap_info()</v>
+        <v>SnmpReportInfo = snmp_gen_info()</v>
+        <v>SnmpInformInfo = snmp_gen_info()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore | {register, UserId, TargetName, agent_info()}</v>
+        <v>Reply = ignore | {register, UserId, TargetName, AgentConfig}</v>
         <v>UserId = term()</v>
         <v>TargetName = target_name()</v>
-        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v>
+        <v>AgentConfig = [agent_config()]</v>
       </type>
       <desc>
-        <p>This function is called when a message is received from an 
-          unknown agent.</p>
+	<p>This function is called when a message is received from an 
+	unknown agent.</p>
         <p>Note that this will always be the default user that is called.</p>
-        <p>For more info about the <c>agent_info()</c>, see 
-          <seealso marker="snmpm#register_agent">register_agent</seealso>.</p>
+        <p>For more info about the <c>agent_config()</c>, see 
+	<seealso marker="snmpm#register_agent">register_agent</seealso>.</p>
 
         <p>The arguments <c>Type</c> and <c>SnmpInfo</c> relates in the 
           following way: </p>
@@ -148,7 +167,7 @@
 	  </list>
 
         <p>The only user which would return 
-          <c>{register, UserId, TargetName, agent_info()}</c> is the 
+          <c>{register, UserId, TargetName, AgentConfig}</c> is the 
           <em>default user</em>.</p>
 
         <marker id="handle_pdu"></marker>
@@ -156,18 +175,13 @@
     </func>
 
     <func>
-      <name>handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> Reply</name>
+      <name>handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> void()</name>
       <fsummary>Handle the reply to an asynchronous request</fsummary>
       <type>
         <v>TargetName = target_name()</v>
         <v>ReqId = term()</v>
-        <v>SnmpPduInfo = {ErrorStatus, ErrorIndex, Varbinds}</v>
-        <v>ErrorStatus = atom()</v>
-        <v>ErrorIndex = integer()</v>
-        <v>Varbinds = [varbind()]</v>
-        <v>varbind() = #varbind</v>
+        <v>SnmpPduInfo = snmp_gen_info()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore</v>
       </type>
       <desc>
         <p>Handle the reply to an asynchronous request, such as 
@@ -186,27 +200,19 @@
       <fsummary>Handle a trap/notification message</fsummary>
       <type>
         <v>TargetName = TargetName2 = target_name()</v>
-        <v>SnmpTrapInfo = {Enteprise, Generic, Spec, Timestamp, Varbinds} | {ErrorStatus, ErrorIndex, Varbinds}</v>
-        <v>Enterprise = oid()</v>
-        <v>Generic = integer()</v>
-        <v>Spec = integer()</v>
-        <v>Timestamp = integer()</v>
-        <v>ErrorStatus = atom()</v>
-        <v>ErrorIndex = integer()</v>
-        <v>Varbinds = [varbind()]</v>
-        <v>varbind() = #varbind</v>
+        <v>SnmpTrapInfo = snmp_v1_trap_info() | snmp_gen_info()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}</v>
         <v>UserId = term()</v>
-        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v>
+        <v>AgentConfig = [agent_config()]</v>
       </type>
       <desc>
         <p>Handle a trap/notification message from an agent.</p>
-        <p>For more info about the <c>agent_info()</c>, see 
-          <seealso marker="snmpm#register_agent">register_agent</seealso></p>
+        <p>For more info about the <c>agent_config()</c>, see 
+	<seealso marker="snmpm#register_agent">register_agent</seealso></p>
         <p>The only user which would return 
-          <c>{register, UserId, TargetName2, agent_info()}</c> is the 
-          <em>default user</em>.</p>
+	<c>{register, UserId, TargetName2, agent_info()}</c> is the 
+	<em>default user</em>.</p>
 
         <marker id="handle_inform"></marker>
       </desc>
@@ -217,29 +223,25 @@
       <fsummary>Handle a inform message</fsummary>
       <type>
         <v>TargetName = TargetName2 = target_name()</v>
-        <v>SnmpInformInfo = {ErrorStatus, ErrorIndex, Varbinds}</v>
-        <v>ErrorStatus = atom()</v>
-        <v>ErrorIndex = integer()</v>
-        <v>Varbinds = [varbind()]</v>
-        <v>varbind() = #varbind</v>
+        <v>SnmpInformInfo = snmp_gen_info()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>Reply = ignore | no_reply | unregister | {register, UserId, TargetName2, AgentConfig}</v>
         <v>UserId = term()</v>
-        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v>
+        <v>AgentConfig = [agent_config()]</v>
       </type>
       <desc>
         <p>Handle a inform message.</p>
-        <p>For more info about the <c>agent_info()</c>, see 
-          <seealso marker="snmpm#register_agent">register_agent</seealso></p>
+        <p>For more info about the <c>agent_config()</c>, see 
+	<seealso marker="snmpm#register_agent">register_agent</seealso></p>
         <p>The only user which would return 
-          <c>{register, UserId, TargetName2, agent_info()}</c> is the 
-          <em>default user</em>.</p>
-        <p>If the 
-          <seealso marker="snmp_app">inform request behaviour</seealso> 
-          configuration option is set to <c>user</c> or 
-          <c>{user, integer()}</c>, the response (acknowledgment) to this 
-          inform-request will be sent when this function returns.</p>
-
+	<c>{register, UserId, TargetName2, AgentConfig}</c> is the 
+	<em>default user</em>.</p>
+	<p>If the 
+	<seealso marker="snmp_app">inform request behaviour</seealso> 
+	configuration option is set to <c>user</c> or 
+	<c>{user, integer()}</c>, the response (acknowledgment) to this 
+	inform-request will be sent when this function returns.</p>
+	
         <marker id="handle_report"></marker>
       </desc>
     </func>
@@ -251,23 +253,46 @@
         <v>TargetName = TargetName2 = target_name()</v>
         <v>Addr = ip_address()</v>
         <v>Port = integer()</v>
-        <v>SnmpReportInfo = {ErrorStatus, ErrorIndex, Varbinds}</v>
-        <v>ErrorStatus = atom()</v>
-        <v>ErrorIndex = integer()</v>
-        <v>Varbinds = [varbind()]</v>
-        <v>varbind() = #varbind</v>
+        <v>SnmpReportInfo = snmp_gen_info()</v>
         <v>UserData = term()</v>
-        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>Reply = ignore | unregister | {register, UserId, TargetName2, AgentConfig}</v>
         <v>UserId = term()</v>
-        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v>
+        <v>AgentConfig = [agent_config()]</v>
       </type>
       <desc>
         <p>Handle a report message.</p>
-        <p>For more info about the <c>agent_info()</c>, see 
-          <seealso marker="snmpm#register_agent">register_agent</seealso></p>
+        <p>For more info about the <c>agent_config()</c>, see 
+	<seealso marker="snmpm#register_agent">register_agent</seealso></p>
         <p>The only user which would return 
-          <c>{register, UserId, TargetName2, agent_info()}</c> is the 
-          <em>default user</em>.</p>
+	<c>{register, UserId, TargetName2, AgentConfig}</c> is the 
+	<em>default user</em>.</p>
+	
+        <marker id="handle_invalid_result"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_invalid_result(IN, OUT) -> void()</name>
+      <fsummary>Handle a report message</fsummary>
+      <type>
+        <v>IN = {Func, Args}</v>
+        <v>Func = atom()</v>
+        <v>Args = list()</v>
+        <v>OUT = {crash, CrashInfo} | {result, InvalidResult}</v>
+        <v>CrashInfo = {ErrorType, Error, Stacktrace}</v>
+        <v>ErrorType = atom()</v>
+        <v>Error = term()</v>
+        <v>Stacktrace = list()</v>
+        <v>InvalidResult = term()</v>
+      </type>
+      <desc>
+        <p>If <em>any</em> of the <em>other</em> 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).</p>
+	<p><c>IN</c> reprecents the function called (and its arguments). 
+	<c>OUT</c> represents the unexpected/invalid result. </p>
       </desc>
     </func>
   </funcs>