aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMicael Karlberg <bmk@erlang.org>2011-04-13 12:05:20 +0200
committerMicael Karlberg <bmk@erlang.org>2011-04-13 12:05:20 +0200
commit6f7913a20db1f59a67cc22ae3b6ce6d4d013deee (patch)
tree115a549bfb88a558f917eeb133e6fb7e161eef12
parent21244028b693c6a1d4726b6a7d10bc947d9fb0f4 (diff)
downloadotp-6f7913a20db1f59a67cc22ae3b6ce6d4d013deee.tar.gz
otp-6f7913a20db1f59a67cc22ae3b6ce6d4d013deee.tar.bz2
otp-6f7913a20db1f59a67cc22ae3b6ce6d4d013deee.zip
Proper interface documentation for new API. Also release notes
with links into API.
-rw-r--r--lib/snmp/doc/src/notes.xml23
-rw-r--r--lib/snmp/doc/src/snmpm.xml354
2 files changed, 247 insertions, 130 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index f5fa7065fb..11d2a513df 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -54,8 +54,29 @@
</item>
<item>
+ <p>[manager] The API for snmp requests has been changed to
+ allow the caller to override some configuration. </p>
+ <p>See
+ <seealso marker="snmpm#sync_get">sync_get/3,4</seealso>,
+ <seealso marker="snmpm#async_get">async_get/3,4</seealso>,
+ <seealso marker="snmpm#sync_get_next">sync_get_next/3,4</seealso>,
+ <seealso marker="snmpm#async_get_next">async_get_next/3,4</seealso>,
+ <seealso marker="snmpm#sync_get_bulk">sync_get_bulk/5,6</seealso>,
+ <seealso marker="snmpm#async_get_bulk">async_get_bulk/5,6</seealso>,
+ <seealso marker="snmpm#sync_set">sync_set/3,4</seealso> and
+ <seealso marker="snmpm#async_set">async_set/3,4</seealso>
+ for more info. </p>
+ <p>Own Id: OTP-9162</p>
+ </item>
+
+ <item>
<p>[manager] The old API functions (for get and set
- requests) are now officially deprecated.
+ requests:
+ snmpm:g/3,4,5,6,7, snmpm:ag/3,4,5,6,7,
+ snmpm:gn/3,4,5,6,7, snmpm:agn/3,4,5,6,7,
+ snmpm:s/3,4,5,6,7, snmpm:s/3,4,5,6,7,
+ snmpm:gb/5,6,7,8,9 and snmpm:agb/5,6,7,8,9)
+ are now officially deprecated.
They will be removed as of R16B. </p>
<p>Own Id: OTP-9174</p>
</item>
diff --git a/lib/snmp/doc/src/snmpm.xml b/lib/snmp/doc/src/snmpm.xml
index 1ee391d9ba..db7abd6867 100644
--- a/lib/snmp/doc/src/snmpm.xml
+++ b/lib/snmp/doc/src/snmpm.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -63,6 +63,10 @@ value_type() = o ('OBJECT IDENTIFIER') |
c64 ('Counter64') |
tt ('TimeTicks')
value() = term()
+community() = string()
+sec_model() = any | v1 | v2c | usm
+sec_name() = string()
+sec_level() = noAuthNoPriv | authNoPriv | authPriv
]]></code>
<marker id="monitor"></marker>
@@ -488,22 +492,20 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>sync_get(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get(UserId, TargetName, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get(UserId, TargetName, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
+ <name>sync_get(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
<fsummary>Synchronous <c>get-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Timeout = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>SnmpReply = snmp_reply()</v>
<v>Remaining = integer()</v>
- <v>Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
- <v>R = term()</v>
+ <v>Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
+ <v>ReqId = term()</v>
+ <v>ActualReason = term()</v>
<v>SecInfo = [sec_info()]</v>
<v>sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}</v>
<v>sec_tag() = atom()</v>
@@ -512,19 +514,29 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
</type>
<desc>
<p>Synchronous <c>get-request</c>. </p>
- <p><c>Remaining</c> is the remaining time of the given or
- default timeout time.</p>
+
+ <p><c>Remaining</c> is the remaining time of the given (or default)
+ timeout time.</p>
+
<p>When <em>Reason</em> is <em>{send_failed, ...}</em> it means that
- the net_if process failed to send the message. This could happen
- because of any number of reasons, i.e. encoding error. <em>R</em>
- is the actual reason in this case. </p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
- <p>For <c>SnmpInfo</c>, see the user callback function
- <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p>
+ the net_if process failed to send the message. This could happen
+ because of any number of reasons, i.e. encoding error.
+ <em>ActualReason</em> is the actual reason in this case. </p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a option (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
+
+ <p>For <c>SnmpInfo</c>, see the user callback function
+ <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p>
<marker id="async_get"></marker>
</desc>
@@ -532,33 +544,39 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>async_get(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get(UserId, TargetName, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason}</name>
+ <name>async_get(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}</name>
<fsummary>Asynchronous <c>get-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Expire = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>ReqId = term()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Asynchronous <c>get-request</c>.</p>
+
<p>The reply, if it arrives, will be delivered to the user
- through a call to the snmpm_user callback function
- <c>handle_pdu</c>.</p>
- <p>The <c>Expire</c> time indicates for how long the request is
- valid (after which the manager is free to delete it).</p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
+ through a call to the snmpm_user callback function
+ <c>handle_pdu</c>.</p>
+
+ <p>The send option <c>timeout</c> specifies for how long the request is
+ valid (after which the manager is free to delete it).</p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
<marker id="sync_get_next"></marker>
</desc>
@@ -566,35 +584,51 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>sync_get_next(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_next(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_next(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_next(UserId, TargetName, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_next(UserId, TargetName, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
+ <name>sync_get_next(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
<fsummary>Synchronous <c>get-next-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Timeout = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>SnmpReply = snmp_reply()</v>
<v>Remaining = integer()</v>
- <v>Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
- <v>R = term()</v>
+ <v>Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
+ <v>ReqId = term()</v>
+ <v>ActualReason = term()</v>
+ <v>SecInfo = [sec_info()]</v>
+ <v>sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}</v>
+ <v>sec_tag() = atom()</v>
+ <v>ExpectedValue = ReceivedValue = term()</v>
+ <v>SnmpInfo = term()</v>
</type>
<desc>
<p>Synchronous <c>get-next-request</c>. </p>
- <p><c>Remaining</c> time of the given or default timeout time.</p>
+
+ <p><c>Remaining</c> is the remaining time of the given (or default)
+ timeout time.</p>
+
<p>When <em>Reason</em> is <em>{send_failed, ...}</em> it means that
- the net_if process failed to send the message. This could happen
- because of any number of reasons, i.e. encoding error. <em>R</em>
- is the actual reason in this case. </p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
+ the net_if process failed to send the message. This could happen
+ because of any number of reasons, i.e. encoding error.
+ <em>ActualReason</em> is the actual reason in this case. </p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
+
+ <p>For <c>SnmpInfo</c>, see the user callback function
+ <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p>
<marker id="async_get_next"></marker>
</desc>
@@ -602,27 +636,36 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>async_get_next(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_next(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_next(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_next(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_next(UserId, TargetName, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason}</name>
+ <name>async_get_next(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}</name>
<fsummary>Asynchronous <c>get-next-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Expire = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>ReqId = integer()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Asynchronous <c>get-next-request</c>. </p>
+
<p>The reply will be delivered to the user through a call
- to the snmpm_user callback function <c>handle_pdu</c>.</p>
- <p>The <c>Expire</c> time indicates for how long the request is
- valid (after which the manager is free to delete it).</p>
+ to the snmpm_user callback function <c>handle_pdu</c>.</p>
+
+ <p>The send option <c>timeout</c> specifies for how long the request is
+ valid (after which the manager is free to delete it).</p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
<marker id="sync_set"></marker>
</desc>
@@ -630,37 +673,54 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>sync_set(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_set(UserId, TargetName, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
+ <name>sync_set(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
<fsummary>Synchronous <c>set-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
- <v>ContextName = string()</v>
<v>VarsAndVals = vars_and_vals()</v>
- <v>Timeout = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>SnmpReply = snmp_reply()</v>
<v>Remaining = integer()</v>
<v>Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
+ <v>ReqId = term()</v>
<v>ActualReason = term()</v>
+ <v>SecInfo = [sec_info()]</v>
+ <v>sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}</v>
+ <v>sec_tag() = atom()</v>
+ <v>ExpectedValue = ReceivedValue = term()</v>
+ <v>SnmpInfo = term()</v>
</type>
<desc>
<p>Synchronous <c>set-request</c>. </p>
- <p><c>Remaining</c> time of the given or default timeout time.</p>
- <p>When <em>Reason</em> is <em>{send_failed, ...}</em> it means that
- the net_if process failed to send the message. This could happen
- because of any number of reasons, i.e. encoding error. <em>R</em>
- is the actual reason in this case. </p>
- <p>When <em>var_and_val()</em> is <em>{oid(), value()}</em>, the
- manager makes an educated guess based on the loaded mibs. </p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
+
+ <p><c>Remaining</c> is the remaining time of the given (or default)
+ timeout time.</p>
+
+ <p>When <em>Reason</em> is <em>{send_failed, ...}</em> it means that
+ the net_if process failed to send the message. This could happen
+ because of any number of reasons, i.e. encoding error.
+ <em>ActualReason</em> is the actual reason in this case. </p>
+
+ <p>When <em>var_and_val()</em> is <em>{oid(), value()}</em>, the
+ manager makes an educated guess based on the loaded mibs. </p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing. </p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
+
+ <p>For <c>SnmpInfo</c>, see the user callback function
+ <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p>
<marker id="async_set"></marker>
</desc>
@@ -668,33 +728,41 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>async_set(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_set(UserId, TargetName, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_set(UserId, TargetName, ContextName, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_set(UserId, TargetName, ContextName, VarsAndVals, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason}</name>
+ <name>async_set(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} | {error, Reason}</name>
<fsummary>Asynchronous <c>set-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
<v>VarsAndVals = vars_and_vals()</v>
- <v>Expire = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>ReqId = term()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Asynchronous <c>set-request</c>. </p>
- <p>The reply will be delivered to the user through a call
- to the snmpm_user callback function <c>handle_pdu</c>.</p>
- <p>The <c>Expire</c> time indicates for how long the request is
- valid (after which the manager is free to delete it).</p>
- <p>When <em>var_and_val()</em> is <em>{oid(), value()}</em>, the
- manager makes an educated guess based on the loaded mibs. </p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
+
+ <p>The reply will be delivered to the user through a call
+ to the snmpm_user callback function <c>handle_pdu</c>.</p>
+
+ <p>The send option <c>timeout</c> specifies for how long the request is
+ valid (after which the manager is free to delete it).</p>
+
+ <p>When <em>var_and_val()</em> is <em>{oid(), value()}</em>, the
+ manager makes an educated guess based on the loaded mibs. </p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
<marker id="sync_get_bulk"></marker>
</desc>
@@ -702,36 +770,53 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
- <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
+ <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason}</name>
<fsummary>Synchronous <c>get-bulk-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
<v>NonRep = integer()</v>
<v>MaxRep = integer()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Timeout = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>SnmpReply = snmp_reply()</v>
<v>Remaining = integer()</v>
- <v>Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
+ <v>Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term()</v>
+ <v>ReqId = term()</v>
+ <v>ActualReason = term()</v>
+ <v>SecInfo = [sec_info()]</v>
+ <v>sec_info() = {sec_tag(), ExpectedValue, ReceivedValue}</v>
+ <v>sec_tag() = atom()</v>
+ <v>ExpectedValue = ReceivedValue = term()</v>
+ <v>SnmpInfo = term()</v>
</type>
<desc>
<p>Synchronous <c>get-bulk-request</c> (See RFC1905).</p>
- <p><c>Remaining</c> time of the given or default timeout time.</p>
+
+ <p><c>Remaining</c> is the remaining time of the given (or default)
+ timeout time.</p>
+
<p>When <em>Reason</em> is <em>{send_failed, ...}</em> it means that
- the net_if process failed to send the message. This could happen
- because of any number of reasons, i.e. encoding error. <em>R</em>
- is the actual reason in this case. </p>
- <p><c>ExtraInfo</c> is an opaque data structure passed on to
- the net-if process. The net-if process included in this
- application makes no use of this info, so the only use for it
- in such a configuration (when using the built in net-if) would
- be tracing.</p>
+ the net_if process failed to send the message. This could happen
+ because of any number of reasons, i.e. encoding error.
+ <em>ActualReason</em> is the actual reason in this case. </p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
+
+ <p>For <c>SnmpInfo</c>, see the user callback function
+ <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p>
<marker id="async_get_bulk"></marker>
</desc>
@@ -739,29 +824,40 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
<func>
<name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name>
- <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason}</name>
+ <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) -> {ok, ReqId} | {error, Reason}</name>
<fsummary>Asynchronous <c>get-bulk-request</c></fsummary>
<type>
<v>UserId = term()</v>
<v>TargetName = target_name()</v>
<v>NonRep = integer()</v>
<v>MaxRep = integer()</v>
- <v>ContextName = string()</v>
<v>Oids = [oid()]</v>
- <v>Expire = integer()</v>
- <v>ExtraInfo = term()</v>
+ <v>SendOpts = send_opts()</v>
+ <v>send_opts() = [send_opt()]</v>
+ <v>send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()}</v>
<v>ReqId = integer()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Asynchronous <c>get-bulk-request</c> (See RFC1905).</p>
+
<p>The reply will be delivered to the user through a call
- to the snmpm_user callback function <c>handle_pdu</c>.</p>
- <p>The <c>Expire</c> time indicates for how long the request is
- valid (after which the manager is free to delete it).</p>
+ to the snmpm_user callback function <c>handle_pdu</c>.</p>
+
+ <p>The send option <c>timeout</c> specifies for how long the request is
+ valid (after which the manager is free to delete it).</p>
+
+ <p>The send option <c>extra</c> specifies an opaque data structure
+ passed on to the net-if process. The net-if process included in this
+ application makes no use of this info, so the only use for it
+ in such a configuration (when using the built in net-if) would
+ be tracing.</p>
+
+ <p>Some of the send options (<c>community</c>, <c>sec_model</c>,
+ <c>sec_name</c>, <c>sec_level</c> and <c>max_message_size</c>)
+ are <c>override options</c>. That is,
+ for <em>this</em> request, they override any configuration done
+ when the agent was registered. </p>
<marker id="cancel_async_request"></marker>
</desc>