From 29ac3cf1c1e6620344192944ebeae7ee8f220bb7 Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Thu, 14 Apr 2011 12:24:51 +0200 Subject: Detailed usage of "Extra" usage in the request API functions, including the reserved value. --- lib/snmp/doc/src/snmpm.xml | 210 +++++++++++++++++++------------- lib/snmp/src/manager/snmpm.erl | 1 - lib/snmp/src/manager/snmpm_internal.hrl | 5 +- lib/snmp/src/manager/snmpm_net_if.erl | 18 ++- lib/snmp/src/manager/snmpm_server.erl | 2 - 5 files changed, 145 insertions(+), 91 deletions(-) (limited to 'lib') diff --git a/lib/snmp/doc/src/snmpm.xml b/lib/snmp/doc/src/snmpm.xml index b1c8e56721..72849b9c9e 100644 --- a/lib/snmp/doc/src/snmpm.xml +++ b/lib/snmp/doc/src/snmpm.xml @@ -525,9 +525,11 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option extra 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.

+ 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) @@ -569,16 +571,18 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Synchronous get-request.

Remaining is the remaining time of the given or - default timeout time.

+ default timeout time.

When Reason is {send_failed, ...} 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. R - is the actual reason in this case.

-

ExtraInfo 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.

+ the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. R + is the actual reason in this case.

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

For SnmpInfo, see the user callback function handle_report.

@@ -610,12 +614,14 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

-

The send option extra specifies an opaque data structure +

The send option extra 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.

- + 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, @@ -646,15 +652,17 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Asynchronous get-request.

The reply, if it arrives, will be delivered to the user - through a call to the snmpm_user callback function - handle_pdu.

-

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

-

ExtraInfo 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.

+ through a call to the snmpm_user callback function + handle_pdu.

+

The Expire time indicates for how long the request is + valid (after which the manager is free to delete it).

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

@@ -695,9 +703,11 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option extra 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.

+ 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) @@ -735,15 +745,17 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Synchronous get-next-request.

Remaining time of the given or default timeout time.

When Reason is {send_failed, ...} 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. R - is the actual reason in this case.

-

ExtraInfo 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.

- + the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. R + is the actual reason in this case.

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+ @@ -769,12 +781,14 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option timeout specifies for how long the request is valid (after which the manager is free to delete it).

-

The send option extra specifies an opaque data structure +

The send option extra 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.

- + 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, @@ -808,6 +822,13 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 to the snmpm_user callback function handle_pdu.

The Expire time indicates for how long the request is valid (after which the manager is free to delete it).

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

@@ -851,9 +872,11 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option extra 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.

+ 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) @@ -891,16 +914,18 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Synchronous set-request.

Remaining time of the given or default timeout time.

When Reason is {send_failed, ...} 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. R - is the actual reason in this case.

-

When var_and_val() is {oid(), value()}, the - manager makes an educated guess based on the loaded mibs.

-

ExtraInfo 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.

+ the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. R + is the actual reason in this case.

+

When var_and_val() is {oid(), value()}, the + manager makes an educated guess based on the loaded mibs.

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

@@ -934,10 +959,12 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option extra 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.

- + 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, @@ -967,17 +994,19 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Asynchronous set-request.

The reply will be delivered to the user through a call - to the snmpm_user callback function handle_pdu.

+ to the snmpm_user callback function handle_pdu.

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

-

When var_and_val() is {oid(), value()}, the - manager makes an educated guess based on the loaded mibs.

-

ExtraInfo 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.

- + valid (after which the manager is free to delete it).

+

When var_and_val() is {oid(), value()}, the + manager makes an educated guess based on the loaded mibs.

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+ @@ -1019,10 +1048,12 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

The send option extra 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.

- + 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

+

Some of the send options (community, sec_model, sec_name, sec_level and max_message_size) are override options. That is, @@ -1059,15 +1090,17 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Synchronous get-bulk-request (See RFC1905).

Remaining time of the given or default timeout time.

-

When Reason is {send_failed, ...} 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. R - is the actual reason in this case.

-

ExtraInfo 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.

+

When Reason is {send_failed, ...} 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. R + is the actual reason in this case.

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

@@ -1136,9 +1169,16 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Asynchronous get-bulk-request (See RFC1905).

The reply will be delivered to the user through a call - to the snmpm_user callback function handle_pdu.

+ to the snmpm_user callback function handle_pdu.

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

+ valid (after which the manager is free to delete it).

+

ExtraInfo 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: + Any tuple with snmpm_extra_info_tag as its first + element is reserved for internal use.

diff --git a/lib/snmp/src/manager/snmpm.erl b/lib/snmp/src/manager/snmpm.erl index dd85ec9f41..8a629eaf3b 100644 --- a/lib/snmp/src/manager/snmpm.erl +++ b/lib/snmp/src/manager/snmpm.erl @@ -164,7 +164,6 @@ -include("snmpm_internal.hrl"). -define(DEFAULT_AGENT_PORT, 161). -%% -define(DEFAULT_CONTEXT, ""). %% This function is called when the snmp application diff --git a/lib/snmp/src/manager/snmpm_internal.hrl b/lib/snmp/src/manager/snmpm_internal.hrl index 389aeaf197..53ad41c6b0 100644 --- a/lib/snmp/src/manager/snmpm_internal.hrl +++ b/lib/snmp/src/manager/snmpm_internal.hrl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2006-2009. All Rights Reserved. +%% Copyright Ericsson AB 2006-2011. All Rights Reserved. %% %% 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 @@ -21,6 +21,9 @@ -define(snmpm_internal, true). -define(DEFAULT_CONTEXT, ""). +-define(SNMPM_EXTRA_INFO_TAG, snmpm_extra_info_tag). +-define(DEFAULT_EXTRA_INFO, {?SNMPM_EXTRA_INFO_TAG}). + -include_lib("snmp/src/app/snmp_internal.hrl"). diff --git a/lib/snmp/src/manager/snmpm_net_if.erl b/lib/snmp/src/manager/snmpm_net_if.erl index 07156dacd9..3d248fff57 100644 --- a/lib/snmp/src/manager/snmpm_net_if.erl +++ b/lib/snmp/src/manager/snmpm_net_if.erl @@ -99,7 +99,7 @@ stop(Pid) -> call(Pid, stop). send_pdu(Pid, Pdu, Vsn, MsgData, Addr, Port) -> - send_pdu(Pid, Pdu, Vsn, MsgData, Addr, Port, undefined). + send_pdu(Pid, Pdu, Vsn, MsgData, Addr, Port, ?DEFAULT_EXTRA_INFO). send_pdu(Pid, Pdu, Vsn, MsgData, Addr, Port, ExtraInfo) when is_record(Pdu, pdu) -> @@ -380,13 +380,14 @@ handle_call(Req, From, State) -> %% {noreply, State, Timeout} | %% {stop, Reason, State} (terminate/2 is called) %%-------------------------------------------------------------------- -handle_cast({send_pdu, Pdu, Vsn, MsgData, Addr, Port, _ExtraInfo}, State) -> +handle_cast({send_pdu, Pdu, Vsn, MsgData, Addr, Port, ExtraInfo}, State) -> ?vlog("received send_pdu message with" "~n Pdu: ~p" "~n Vsn: ~p" "~n MsgData: ~p" "~n Addr: ~p" "~n Port: ~p", [Pdu, Vsn, MsgData, Addr, Port]), + maybe_process_extra_info(ExtraInfo), maybe_handle_send_pdu(Pdu, Vsn, MsgData, Addr, Port, State), {noreply, State}; @@ -997,6 +998,19 @@ pdu_type_of(TrapPdu) when is_record(TrapPdu, trappdu) -> trap. +%% ------------------------------------------------------------------- + +%% At this point this function is used during testing +maybe_process_extra_info(?DEFAULT_EXTRA_INFO) -> + ok; +maybe_process_extra_info({?SNMPM_EXTRA_INFO_TAG, Fun}) + when is_function(Fun, 0) -> + (catch Fun()), + ok; +maybe_process_extra_info(_ExtraInfo) -> + ok. + + %% ------------------------------------------------------------------- t() -> diff --git a/lib/snmp/src/manager/snmpm_server.erl b/lib/snmp/src/manager/snmpm_server.erl index 29f0c61b0e..b8d7cf6375 100644 --- a/lib/snmp/src/manager/snmpm_server.erl +++ b/lib/snmp/src/manager/snmpm_server.erl @@ -101,8 +101,6 @@ -define(DEFAULT_ASYNC_GET_BULK_TIMEOUT, ?DEFAULT_ASYNC_TIMEOUT). -define(DEFAULT_ASYNC_SET_TIMEOUT, ?DEFAULT_ASYNC_TIMEOUT). --define(DEFAULT_EXTRA_INFO, undefined). - -define(SNMP_AGENT_PORT, 161). -define(SYNC_GET_TIMEOUT(SendOpts), -- cgit v1.2.3