Detailed usage of "Extra" usage in the request API functions,

including the reserved value.

5 files changed, 145 insertions, 91 deletions

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
 
 	<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>
+	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>) 
@@ -569,16 +571,18 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
       <desc>
         <p>Synchronous <c>get-request</c>. </p>
         <p><c>Remaining</c> is the remaining time of the given or 
-          default timeout time.</p>
+	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>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, 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>
 
@@ -610,12 +614,14 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
         <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 
+	<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>
-	
+	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,
@@ -646,15 +652,17 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
       <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 <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_get_next2"></marker>
       </desc>
@@ -695,9 +703,11 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 
 	<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>
+	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>) 
@@ -735,15 +745,17 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
         <p>Synchronous <c>get-next-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><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>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, 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>
@@ -769,12 +781,14 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 	<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 
+	<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>
-	
+	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,
@@ -808,6 +822,13 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 	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, 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>
@@ -851,9 +872,11 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 
 	<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>
+	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>) 
@@ -891,16 +914,18 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
         <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>
+	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, 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_set2"></marker>
       </desc>
@@ -934,10 +959,12 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 
 	<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>
-	
+	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,
@@ -967,17 +994,19 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
       <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>
+	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>
-
+	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, 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>
@@ -1019,10 +1048,12 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
 
 	<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>
-	
+	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,
@@ -1059,15 +1090,17 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
       <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>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>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, 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>
@@ -1136,9 +1169,16 @@ priv_key = [integer()]   (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1
       <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>
+	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>
+	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>
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};
 
@@ -999,6 +1000,19 @@ pdu_type_of(TrapPdu) when is_record(TrapPdu, trappdu) ->
 
 %% -------------------------------------------------------------------
 
+%% 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() ->
     {A,B,C} = erlang:now(),
     A*1000000000+B*1000+(C div 1000).
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),