diff options
Diffstat (limited to 'lib/snmp/doc/src/snmpm_user.xml')
| -rw-r--r-- | lib/snmp/doc/src/snmpm_user.xml | 276 |
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> + |