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

2 files changed, 191 insertions, 81 deletions

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
@@ -34,6 +34,91 @@
 
 
   <section>
+    <title>SNMP Development Toolkit 4.25</title>
+    <p>Version 4.25 supports code replacement in runtime from/to
+    version 4.24.1, 4.24, 4.23.1 and 4.23. </p>
+
+    <section>
+      <title>Improvements and new features</title>
+<!--
+      <p>-</p>
+-->
+
+      <list type="bulleted">
+        <item>
+          <p>[manager] Improved handling of unexpected return values from
+	  <seealso marker="snmpm_user">snmpm_user</seealso>
+	  callback functions. </p>
+	  <p>Violations of the documented API (crashes or invalid return 
+	  values) will now result in an error message. </p>
+          <p>Own Id: OTP-11307</p>
+        </item>
+
+      </list>
+
+    </section>
+
+    <section>
+      <title>Fixed Bugs and Malfunctions</title>
+      <p>-</p>
+
+<!--
+      <list type="bulleted">
+        <item>
+          <p>[agent] Reading the value of the vacmViewTreeFamilyMask returns 
+	  it in the wrong (internal bitlist) format. </p>
+	  <p>The vacmViewTreeFamilyMask is defined as a bit string in the MIB
+	  (OCTET STRING). Internally a bitlist (list of 1's and 0's, 
+	  see <seealso marker="snmp_agent_config_files#vacm">vacm config file</seealso>
+	  for more info) is used. 
+	  However, the MIB implementation assumed the latter, effectively
+	  rendering all attempts to read/set masks via SNMP unsuccessful. </p>
+	  <p>Since the mask is used in hot paths (e.g. access permission checks 
+	  for each SNMP operation, the bitlist representation of the mask has 
+	  benefits (e.g. faster processing). Reading/writing the view mask 
+	  objects is less time-critical. Therefore, to fix the issue, convert 
+	  between the bitlist (internal) representation and bitstring 
+	  (external) when the vacmViewTreeFamilyMask objects are accessed. </p>
+	  <p>Also, the check of the vacm config file was invalid with 
+	  regard to the mask value. It was assumed to be a proper oid, which 
+	  is not strictly the case (see bitlist above). </p>
+          <p>Own Id: OTP-11177</p>
+	  <p>Stefan Zegenhagen</p>
+        </item>
+
+        <item>
+          <p>[agent] The counter increment function in the local-db was  
+	  incorrect. It did not handle counter wrap correctly. </p>
+          <p>Own Id: OTP-11192</p>
+        </item>
+
+      </list>
+-->
+
+    </section>
+
+    <section>
+      <title>Incompatibilities</title>
+<!--
+      <p>-</p>
+-->
+
+      <list type="bulleted">
+        <item>
+          <p>[manager] The 
+	  <seealso marker="snmpm_user">snmpm_user</seealso> 
+	  callback functions are no longer allowed to "return" via
+	  exit or throw. </p>
+          <p>Own Id: OTP-11307</p>
+        </item>
+
+      </list>
+    </section>
+
+  </section> <!-- 4.25 -->
+
+
+  <section>
     <title>SNMP Development Toolkit 4.24.1</title>
     <p>Version 4.24.1 supports code replacement in runtime from/to
     version 4.24, 4.23.1 and 4.23. </p>
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>