aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'lib/snmp/doc/src')
-rw-r--r--lib/snmp/doc/src/notes.xml13
-rw-r--r--lib/snmp/doc/src/snmpm_user.xml187
2 files changed, 117 insertions, 83 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index 2b0daf897b..68743e60aa 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -46,7 +46,7 @@
<list type="bulleted">
<item>
- <p>Enable SNMP to create missing database directories. </p>
+ <p>[agent] Enable SNMP to create missing database directories. </p>
<p>Add
<seealso marker="snmp_app#db_init_error">
{db_init_error, create_db_and_dir}</seealso> option to SNMP
@@ -62,6 +62,15 @@
<p>Own Id: OTP-11352</p>
</item>
+ <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>
@@ -167,7 +176,7 @@
</list>
-->
</section>
-
+
</section> <!-- 4.24.2 -->
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>