aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src/snmpm_user.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/snmp/doc/src/snmpm_user.xml')
-rw-r--r--lib/snmp/doc/src/snmpm_user.xml276
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>
+