diff options
Diffstat (limited to 'lib/snmp/doc/src/snmpm.xml')
| -rw-r--r-- | lib/snmp/doc/src/snmpm.xml | 632 |
1 files changed, 505 insertions, 127 deletions
diff --git a/lib/snmp/doc/src/snmpm.xml b/lib/snmp/doc/src/snmpm.xml index 8f631363dc..c36a1b2a24 100644 --- a/lib/snmp/doc/src/snmpm.xml +++ b/lib/snmp/doc/src/snmpm.xml @@ -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> @@ -279,27 +283,27 @@ sec_level = noAuthNoPriv | authNoPriv | authPriv <v>TargetName = target_name()</v> <v>Config = [agent_config()]</v> <v>agent_config() = {Item, Val}</v> - <v>Item = engine_id | address | port | community | timeout | max_message_size | version | sec_model | sec_name | sec_level</v> + <v>Item = engine_id | address | port | community | timeout | max_message_size | version | sec_model | sec_name | sec_level | tdomain</v> <v>Val = term()</v> <v>Reason = term()</v> </type> <desc> <p>Explicitly instruct the manager to handle this agent, with - <c>UserId</c> as the responsible user. </p> - <p>Called to instruct the manager that this agent - shall be handled. This function is used when - the user knows in advance which agents the - manager shall handle. - Note that there is an alternate way to do the same thing: - Add the agent to the manager config files (see - <seealso marker="snmp_manager_config_files#agents">agents.conf</seealso>).</p> + <c>UserId</c> as the responsible user. </p> + <p>Called to instruct the manager that this agent shall be handled. + This function is used when the user knows in advance which agents + the manager shall handle. + Note that there is an alternate way to do the same thing: + Add the agent to the manager config files (see + <seealso marker="snmp_manager_config_files#agents">agents.conf</seealso>).</p> <p><c>TargetName</c> is a non-empty string, - uniquely identifying the agent. </p> - <p>The type of <c>Val</c> depends on <c>Item</c>: </p> + uniquely identifying the agent. </p> + <p>The type of <c>Val</c> depends on <c>Item</c>: </p> <code type="none"><![CDATA[ [mandatory] engine_id = string() [mandatory] address = ip_address() [optional] port = integer() +[optional] tdomain = transportDomainUdpIpv4 | transportDomainUdpIpv6 [optional] community = string() [optional] timeout = integer() | snmp_timer() [optional] max_message_size = integer() @@ -308,7 +312,9 @@ sec_level = noAuthNoPriv | authNoPriv | authPriv [optional] sec_name = string() [optional] sec_level = noAuthNoPriv | authNoPriv | authPriv ]]></code> - <p>Note that if no <c>Port</c> is given, the default value is used.</p> + <p>Note that if no <c>tdomain</c> is given, the default value, + <c>transportDomainUdpIpv4</c>, is used.</p> + <p>Note that if no <c>port</c> is given, the default value is used.</p> <marker id="unregister_agent"></marker> </desc> @@ -344,17 +350,25 @@ sec_level = noAuthNoPriv | authNoPriv | authPriv </func> <func> + <name>update_agent_info(UserId, TargetName, Info) -> ok | {error, Reason}</name> <name>update_agent_info(UserId, TargetName, Item, Val) -> ok | {error, Reason}</name> <fsummary>Update agent config</fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>Item = atom()</v> - <v>Val = term()</v> + <v>Info = [{item(), item_value()}]</v> + <v>Item = item()</v> + <v>item() = atom()</v> + <v>Val = item_value()</v> + <v>item_value() = term()</v> <v>Reason = term()</v> </type> <desc> - <p>Update agent config.</p> + <p>Update agent config. The function <c>update_agent_info/3</c> + should be used when several values needs to be updated atomically. </p> + <p>See function + <seealso marker="#register_agent">register_agent</seealso>) + for more info about what kind of items are allowed. </p> <marker id="which_agents"></marker> </desc> @@ -482,23 +496,75 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <p>Get a list of all registered usm users with engine-id <c>EngineID</c>.</p> - <marker id="sync_get"></marker> + <marker id="sync_get2"></marker> </desc> </func> <func> + <name>sync_get2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> + <name>sync_get2(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>Oids = [oid()]</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>get-request</c>. </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>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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="sync_get"></marker> + </desc> + </func> + + <func> <name>sync_get(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get(UserId, TargetName, CC, 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, CC, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get(UserId, TargetName, CC, Oids, Timeout, ExtraInfo) -> {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> <fsummary>Synchronous <c>get-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Timeout = integer()</v> <v>ExtraInfo = term()</v> @@ -514,10 +580,6 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 </type> <desc> <p>Synchronous <c>get-request</c>. </p> - <p>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</c>). </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 @@ -526,11 +588,55 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 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> + application makes, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + <p>For <c>SnmpInfo</c>, see the user callback function + <seealso marker="snmpm_user#handle_report">handle_report</seealso>.</p> + + <marker id="async_get2"></marker> + </desc> + </func> + + <func> + <name>async_get2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}</name> + <name>async_get2(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>Oids = [oid()]</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 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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="async_get"></marker> </desc> @@ -538,17 +644,15 @@ 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, CC, 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, CC, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name> - <name>async_get(UserId, TargetName, CC, Oids, Expire, ExtraInfo) -> {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> <fsummary>Asynchronous <c>get-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Expire = integer()</v> <v>ExtraInfo = term()</v> @@ -560,35 +664,85 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <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>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</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> - - <marker id="sync_get_next"></marker> + application makes, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + + <marker id="sync_get_next2"></marker> + </desc> + </func> + + <func> + <name>sync_get_next2(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> + <name>sync_get_next2(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>Oids = [oid()]</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>get-next-request</c>. </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>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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="sync_get_next"></marker> </desc> </func> <func> <name>sync_get_next(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get_next(UserId, TargetName, CC, 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, CC, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get_next(UserId, TargetName, CC, Oids, Timeout, ExtraInfo) -> {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> <fsummary>Synchronous <c>get-next-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Timeout = integer()</v> <v>ExtraInfo = term()</v> @@ -599,38 +753,73 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 </type> <desc> <p>Synchronous <c>get-next-request</c>. </p> - <p>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</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 + <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><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> + application makes, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + + <marker id="async_get_next2"></marker> + </desc> + </func> - <marker id="async_get_next"></marker> + <func> + <name>async_get_next2(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}</name> + <name>async_get_next2(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>Oids = [oid()]</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 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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="async_get_next"></marker> </desc> </func> <func> <name>async_get_next(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason}</name> - <name>async_get_next(UserId, TargetName, CC, 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, CC, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name> - <name>async_get_next(UserId, TargetName, CC, Oids, Expire, ExtraInfo) -> {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> <fsummary>Asynchronous <c>get-next-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Expire = integer()</v> <v>ExtraInfo = term()</v> @@ -641,30 +830,88 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <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>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</c>). </p> - <p>The <c>Expire</c> time indicates for how long the request is + <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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + + <marker id="sync_set2"></marker> + </desc> + </func> + + <func> + <name>sync_set2(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> + <name>sync_set2(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>VarsAndVals = vars_and_vals()</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> 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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> - <marker id="sync_set"></marker> + <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="sync_set"></marker> </desc> </func> <func> <name>sync_set(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_set(UserId, TargetName, CC, 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, CC, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_set(UserId, TargetName, CC, VarsAndVals, Timeout, ExtraInfo) -> {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> <fsummary>Synchronous <c>set-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>VarsAndVals = vars_and_vals()</v> <v>Timeout = integer()</v> <v>ExtraInfo = term()</v> @@ -675,12 +922,8 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 </type> <desc> <p>Synchronous <c>set-request</c>. </p> - <p>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</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 + <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> @@ -688,29 +931,72 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 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> + application makes, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> - <marker id="async_set"></marker> + <marker id="async_set2"></marker> + </desc> + </func> + + <func> + <name>async_set2(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}</name> + <name>async_set2(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>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 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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="async_set"></marker> </desc> </func> <func> <name>async_set(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason}</name> - <name>async_set(UserId, TargetName, CC, 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, CC, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason}</name> - <name>async_set(UserId, TargetName, CC, VarsAndVals, Expire, ExtraInfo) -> {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> <fsummary>Asynchronous <c>set-request</c></fsummary> <type> <v>UserId = term()</v> <v>TargetName = target_name()</v> <v>VarsAndVals = vars_and_vals()</v> - <v>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> - <v>Expire = integer()</v> + <v>Expire = integer()</v> <v>ExtraInfo = term()</v> <v>ReqId = term()</v> <v>Reason = term()</v> @@ -719,39 +1005,91 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <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>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</c>). </p> - <p>The <c>Expire</c> time indicates for how long the request is + <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> + application makes, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + + <marker id="sync_get_bulk2"></marker> + </desc> + </func> + + <func> + <name>sync_get_bulk2(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> + <name>sync_get_bulk2(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>Oids = [oid()]</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>get-bulk-request</c> (See RFC1905).</p> - <marker id="sync_get_bulk"></marker> + <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>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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </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="sync_get_bulk"></marker> </desc> </func> <func> <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, CC, 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, CC, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason}</name> - <name>sync_get_bulk(UserId, TragetName, NonRep, MaxRep, CC, Oids, Timeout, ExtraInfo) -> {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> <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>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Timeout = integer()</v> <v>ExtraInfo = term()</v> @@ -761,10 +1099,6 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 </type> <desc> <p>Synchronous <c>get-bulk-request</c> (See RFC1905).</p> - <p>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</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 @@ -772,29 +1106,70 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> + + <marker id="async_get_bulk2"></marker> + </desc> + </func> + + <func> + <name>async_get_bulk2(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}</name> + <name>async_get_bulk2(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>Oids = [oid()]</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 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> - <marker id="async_get_bulk"></marker> + <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="async_get_bulk"></marker> </desc> </func> <func> <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason}</name> - <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, CC, 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, CC, Oids, Expire) -> {ok, ReqId} | {error, Reason}</name> - <name>async_get_bulk(UserId, TargetName, NonRep, MaxRep, CC, Oids, Expire, ExtraInfo) -> {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> <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>CC = context_name() | {community, community()} | {context_name(), community()}</v> - <v>context_name() = string()</v> - <v>community() = string()</v> + <v>ContextName = string()</v> <v>Oids = [oid()]</v> <v>Expire = integer()</v> <v>ExtraInfo = term()</v> @@ -805,12 +1180,15 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 <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>When the <c>CC</c> argument is the tuple - <c>{_, Community}</c>, the <c>Community</c> part will - override the previously configured community for this agent - (represented by <c>TargetName</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, with one exception, 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. The one usage exception is: + <em>Any</em> tuple with <c>snmpm_extra_info_tag</c> as its first + element is reserved for internal use. </p> <marker id="cancel_async_request"></marker> </desc> |