The R13B03 release.OTP_R13B03

1 files changed, 276 insertions, 0 deletions

diff --git a/lib/snmp/doc/src/snmpm_user.xml b/lib/snmp/doc/src/snmpm_user.xml
new file mode 100644
index 0000000000..1823e0c815
--- /dev/null
+++ b/lib/snmp/doc/src/snmpm_user.xml
@@ -0,0 +1,276 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2004</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>snmpm_user</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>snmpm_user.xml</file>
+  </header>
+  <module>snmpm_user</module>
+  <modulesummary>Behaviour module for the SNMP manager user.</modulesummary>
+  <description>
+    <p>This module defines the behaviour of the manager user. 
+      A <c>snmpm_user</c> compliant module 
+      must export the following functions: </p>
+    <list type="bulleted">
+      <item>
+        <p>handle_error/3</p>
+      </item>
+      <item>
+        <p>handle_agent/4</p>
+      </item>
+      <item>
+        <p>handle_pdu/4</p>
+      </item>
+      <item>
+        <p>handle_trap/3</p>
+      </item>
+      <item>
+        <p>handle_inform/3</p>
+      </item>
+      <item>
+        <p>handle_report/3</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>
+
+    <marker id="handle_error"></marker>
+  </description>
+  <funcs>
+    <func>
+      <name>handle_error(ReqId, Reason, UserData) -> Reply</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>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>
+        <p>For <c>SnmpInfo</c> see handle_agent below.</p>
+
+        <marker id="handle_agent"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_agent(Addr, Port, Type, SnmpInfo, UserData) -> Reply</name>
+      <fsummary>Handle agent</fsummary>
+      <type>
+        <v>Addr = ip_address()</v>
+        <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>UserData = term()</v>
+        <v>Reply = ignore | {register, UserId, TargetName, agent_info()}</v>
+        <v>UserId = term()</v>
+        <v>TargetName = target_name()</v>
+        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</v>
+      </type>
+      <desc>
+        <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>The arguments <c>Type</c> and <c>SnmpInfo</c> relates in the 
+          following way: </p>
+
+	  <list type="bulleted">
+	    <item>
+	      <p><c>pdu</c> - <c>SnmpPduInfo</c> 
+                (see <seealso marker="#handle_pdu">handle_pdu</seealso>
+                for more info).</p>
+	    </item>
+	    <item>
+	      <p><c>trap</c> - <c>SnmpTrapInfo</c> 
+                (see <seealso marker="#handle_trap">handle_trap</seealso>
+                for more info).</p>
+	    </item>
+	    <item>
+	      <p><c>report</c> - <c>SnmpReportInfo</c> 
+                (see <seealso marker="#handle_report">handle_report</seealso>
+                for more info).</p>
+	    </item>
+	    <item>
+	      <p><c>inform</c> - <c>SnmpInformInfo</c> 
+                (see <seealso marker="#handle_inform">handle_inform</seealso>
+                for more info).</p>
+	    </item>
+	  </list>
+
+        <p>The only user which would return 
+          <c>{register, UserId, TargetName, agent_info()}</c> is the 
+          <em>default user</em>.</p>
+
+        <marker id="handle_pdu"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_pdu(TargetName, ReqId, SnmpPduInfo, UserData) -> Reply</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>UserData = term()</v>
+        <v>Reply = ignore</v>
+      </type>
+      <desc>
+        <p>Handle the reply to an asynchronous request, such as 
+          <seealso marker="snmpm#async_get">async_get</seealso>, 
+          <seealso marker="snmpm#async_get_next">async_get_next</seealso> or 
+          <seealso marker="snmpm#async_set">async_set</seealso>.</p>
+        <p>It could also be a late reply to a synchronous request.</p>
+        <p><c>ReqId</c> is returned by the asynchronous request function.</p>
+
+        <marker id="handle_trap"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_trap(TargetName, SnmpTrapInfo, UserData) -> Reply</name>
+      <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>UserData = term()</v>
+        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>UserId = term()</v>
+        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</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>The only user which would return 
+          <c>{register, UserId, TargetName2, agent_info()}</c> is the 
+          <em>default user</em>.</p>
+
+        <marker id="handle_inform"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_inform(TargetName, SnmpInformInfo, UserData) -> Reply</name>
+      <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>UserData = term()</v>
+        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>UserId = term()</v>
+        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</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>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>
+
+        <marker id="handle_report"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>handle_report(TargetName, SnmpReportInfo, UserData) -> Reply</name>
+      <fsummary>Handle a report message</fsummary>
+      <type>
+        <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>UserData = term()</v>
+        <v>Reply = ignore | unregister | {register, UserId, TargetName2, agent_info()}</v>
+        <v>UserId = term()</v>
+        <v>agent_info() = [{agent_info_item(), agent_info_value()}]</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>The only user which would return 
+          <c>{register, UserId, TargetName2, agent_info()}</c> is the 
+          <em>default user</em>.</p>
+      </desc>
+    </func>
+  </funcs>
+  
+</erlref>
+