Merge branch 'bmk/agent/extra_info_notification/OTP-9183' into bmk/snmp/snmp420_integration

Conflicts:
	lib/snmp/doc/src/notes.xml
	lib/snmp/src/app/snmp.appup.src

OTP-9119
OTP-9183

1 files changed, 157 insertions, 93 deletions

diff --git a/lib/snmp/doc/src/snmpa.xml b/lib/snmp/doc/src/snmpa.xml
index 1d680e80f5..27d89ea4e3 100644
--- a/lib/snmp/doc/src/snmpa.xml
+++ b/lib/snmp/doc/src/snmpa.xml
@@ -872,10 +872,138 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
           then that sub-agent will be unregistered from all trees in
           <c>Agent</c>. </p>
 
-          <marker id="send_notification"></marker>
+          <marker id="send_notification2"></marker>
       </desc>
     </func>
 
+
+    <func>
+      <name>send_notification2(Agent, Notification, SendOpts) -> void()</name>
+      <fsummary>Send notification</fsummary>
+      <type>
+        <v>Agent = pid() | atom()</v>
+        <v>Notification = atom()</v>
+        <v>SendOpts = [send_option()]</v>
+        <v>send_option() = {receiver, receiver()} | {name, notify_name()} | {context, context_name()} | {varbinds, varbinds()} | {local_engine_id, string()} | {extra, extra_info()}</v>
+        <v>receiver() = no_receiver | {tag(), tag_receiver()} | notification_delivery_info()</v>
+        <v>tag() = term(()</v>
+        <v>tag_receiver() = pid() | registered_name() | {Mod, Func, Args}</v>
+        <v>registered_name() = atom()</v>
+        <v>Mod = atom()</v>
+        <v>Func = atom()</v>
+        <v>Args = list()</v>
+        <v>notify_name() = string()</v>
+        <v>context_name() = string()</v>
+        <v>varbinds() = [varbind()]</v>
+        <v>varbind() = {variable(), value()} | {column(), row_index(), value()} | {oid(), value()}</v>
+        <v>variable() = atom()</v>
+        <v>value() = term()</v>
+        <v>column() = atom()</v>
+        <v>row_index() = [int()]</v>
+        <v>extra_info() = term()</v>
+      </type>
+      <desc>
+        <p>Send the notification <c>Notification</c> to the management 
+	targets defined for notify-name (<c>name</c>) in the 
+	<c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the 
+	specified <c>context</c>. </p>
+
+	<p>If no <c>name</c> is specified (or if it is <c>""</c>), the
+	notification is sent to all management targets. </p>
+
+	<p>If no <c>context</c> is specified, the default context, <c>""</c>, 
+	is used. </p>
+
+        <p>The send option <c>receiver</c> specifies where information
+	about delivery of Inform-Requests should be sent.  The agent
+	sends Inform-Requests and waits for acknowledgments from the
+	management targets. 
+	The <c>receiver</c> can have three values: </p>
+
+	<list type="bulleted">
+          <item>
+            <p><c>no_receiver</c> - No information is delivered. </p>
+	  </item>
+
+          <item>
+	    <p><c>notification_delivery_info()</c> - The information is 
+	    delivered via a function call according to this data. See the 
+	    <seealso marker="#data_types">DATA TYPES</seealso> section 
+	    above for details. </p>
+	  </item>
+
+          <item>
+            <p><c>{tag(), tag_receiver()}</c> - The information is delivered 
+	    either via messages or via a function call according to the value 
+	    of <c>tag_receiver()</c>. </p>
+	    <p>Delivery is done differently depending on the value
+	    of <c>tag_receiver()</c>: </p>
+
+	    <list>
+	      <item>
+		<p><c>pid() | registered_name()</c> - The info will be delivered in  
+		the following messages: </p>
+		<list>
+		  <item>
+		    <p><c>{snmp_targets, tag(), Addresses}</c></p>
+		    <p>This informs the user which target addresses the 
+		    notification was sent to. </p>
+		  </item>
+		  <item>
+		    <p><c>{snmp_notification, tag(), {got_response, Address}}</c></p>
+		    <p>This informs the user that this target address 
+		    acknowledged the notification. </p>
+		  </item>
+		  <item>
+		    <p><c>{snmp_notification, tag(), {no_response, Address}}</c></p>
+		    <p>This informs the user that this target address 
+		    did not acknowledge the notification. </p>
+		  </item>
+		</list>
+		<p>The notification is sent as an Inform-Request to each 
+		target address in <c>Addresses</c> and if there are no 
+		targets for which an Inform-Request is sent, <c>Addresses</c> 
+		is the empty list <c>[]</c>. </p>
+		<p>The <c>tag_receiver()</c> will first be sent the 
+		<c>snmp_targets</c> message, and then for each address in 
+		<c>Addresses</c> list, one of the two <c>snmp_notification</c> 
+		messages. </p>
+	      </item>
+
+	      <item>
+		<p><c>{Mod, Func, Args}</c> - The info will be delivered via
+		the function call: </p>
+		<p><c>Mod:Func([Msg | Args])</c></p>
+		<p>where <c>Msg</c> has the same content and purpose as the 
+		messages descrived above.</p>
+	      </item>
+
+	    </list>
+	  </item>
+        </list>
+
+	<note>
+	  <p>The <c>extra</c> info is not normally interpreted by the agent, 
+	  instead it is passed through to the 
+	  <seealso marker="snmp_agent_netif">net-if</seealso> process. It is 
+	  up to the implementor of that process to make use of this data. </p>
+	  <p>The version of net-if provided by this application makes no use
+	  of this data, with one exception: 
+	  Any tuple containing the atom 
+	  <c>snmpa_default_notification_extra_info</c> 
+	  may be used by the agent and is therefor <em>reserved</em>. </p>
+	  <p>See the net-if incomming messages for sending a 
+	  <seealso marker="snmp_agent_netif#im_send_pdu">
+	  trap</seealso> and 
+	  <seealso marker="snmp_agent_netif#im_send_pdu_req">
+	  notification</seealso> for more info. </p>
+	</note>
+
+	<marker id="send_notification"></marker>
+      </desc>
+    </func>
+
+
     <func>
       <name>send_notification(Agent, Notification, Receiver)</name>
       <name>send_notification(Agent, Notification, Receiver, Varbinds)</name>
@@ -907,18 +1035,19 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
       </type>
       <desc>
         <p>Sends the notification <c>Notification</c> to the
-          management targets defined for <c>NotifyName</c> in the
-          <c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the
-          specified context.  If no <c>NotifyName</c> is specified (or
-          if it is <c>""</c>), the notification is sent to all
-          management targets (<c>Addresses</c> below).  If no <c>ContextName</c> 
-          is specified, the default <c>""</c> context is used.
-          </p>
+	management targets defined for <c>NotifyName</c> in the
+	<c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the
+	specified context.  </p>
+	<p>If no <c>NotifyName</c> is specified (or if it is <c>""</c>), 
+	the notification is sent to all management targets 
+	(<c>Addresses</c> below).  </p>
+	<p>If no <c>ContextName</c> is specified, the default <c>""</c> 
+	context is used. </p>
 
         <p>The parameter <c>Receiver</c> specifies where information
-          about delivery of Inform-Requests should be sent.  The agent
-          sends Inform-Requests and waits for acknowledgments from the
-          managers. <c>Receiver</c> can have three values: </p>
+	about delivery of Inform-Requests should be sent.  The agent
+	sends Inform-Requests and waits for acknowledgments from the
+	managers. <c>Receiver</c> can have three values: </p>
 
 	<list type="bulleted">
           <item>
@@ -926,17 +1055,18 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
 	  </item>
 
           <item>
-            <p><c>{Tag, Recv}</c> - The information is delivered either via messages 
-              or via a function call according to the value of <c>Recv</c>. </p>
-	  </item>
-
-          <item>
             <p><c>notification_delivery_info()</c> - The information is 
               delivered via a function call according to this data. See the 
               <seealso marker="#data_types">DATA TYPES</seealso> section 
               above for details. </p>
 	  </item>
 
+          <item>
+            <p><c>{Tag, Recv}</c> - The information is delivered either via 
+	    messages or via a function call according to the value of 
+	    <c>Recv</c>. </p>
+	  </item>
+
         </list>
 
 
@@ -1064,86 +1194,20 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
             (see SNMP-FRAMEWORK-MIB). </p>
 	</note>
 
-<!--
-          <marker id="send_trap"></marker>
--->
-	  <marker id="discovery"></marker>
+        <p><c>ExtraInfo</c> is not normally used in any way by the agent. 
+	It is intended to be passed along to the net-if process, which is
+	a component that a user can implement themself. The users own net-if
+	may then make use of ExtraInfo. The net-if provided with this 
+	application does not process ExtraInfo. </p>
+	<p>There is one exception. <em>Any</em> tuple containing the atom
+	<c>snmpa_default_notification_extra_info</c> will, in this context,
+	be considered belonging to this application, and may be processed
+	by the agent. </p>
+
+	<marker id="discovery"></marker>
       </desc>
     </func>
 
-<!--
-    <func>
-      <name>send_trap(Agent,Trap,Community)</name>
-      <name>send_trap(Agent,Trap,Community,Varbinds) -> void()</name>
-      <fsummary>Send a trap</fsummary>
-      <type>
-        <v>Agent = pid() | atom()</v>
-        <v>Trap = atom()</v>
-        <v>Community = string()</v>
-        <v>Varbinds = [Varbind]</v>
-        <v>Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}</v>
-        <v>Variable = atom()</v>
-        <v>Column = atom()</v>
-        <v>OID = oid()</v>
-        <v>Value = term()</v>
-        <v>RowIndex = [int()]</v>
-      </type>
-      <desc>
-        <p>Note!  This function is only kept for backwards
-          compatibility reasons.  Use <c>send_notification</c> instead.
-          </p>
-        <p>Sends the trap <c>Trap</c> to the managers defined for
-          <c>Community</c> in the <c>intTrapDestTable</c> in
-          OTP-SNMPEA-MIB.  The optional argument <c>Varbinds</c> defines
-          values for the objects in the trap.  If no value is given for
-          an object, the <c>Agent</c> performs a get-operation to
-          retrieve the value.
-          </p>
-        <p><c>Varbinds</c> is a list of <c>Varbind</c>, where each
-          <c>Varbind</c> is one of:
-          </p>
-        <list type="bulleted">
-          <item><c>{Variable, Value}</c>, where <c>Variable</c> is the
-           symbolic name of a scalar variable referred to in the trap
-           specification.
-          </item>
-          <item><c>{Column, RowIndex, Value}</c>, where <c>Column</c>
-           is the symbolic name of a column variable.
-          <c>RowIndex</c> is a list of indices for the specified
-           element.  If this is the case, the OBJECT IDENTIFIER sent
-           in the trap is the <c>RowIndex</c> appended to the OBJECT
-           IDENTIFIER for the table column. This is the OBJECT
-           IDENTIFIER which specifies the element.
-          </item>
-          <item><c>{OID, Value}</c>, where <c>OID</c> is the OBJECT
-           IDENTIFIER for an instance of an object, scalar variable,
-           or column variable.
-          </item>
-        </list>
-        <p>For example, to specify that <c>sysLocation</c> should have the
-          value <c>"upstairs"</c> in the trap, we could use one of:
-          </p>
-        <list type="bulleted">
-          <item><c>{sysLocation, "upstairs"}</c> or</item>
-          <item><c>{[1,3,6,1,2,1,1,6,0], "upstairs"}</c> or</item>
-          <item><c>{?sysLocation_instance, "upstairs"}</c> (provided
-           that the generated <c>.hrl</c> file is included)</item>
-        </list>
-        <p>If a variable in the trap is a table element, the
-          <c>RowIndex</c> for the element must be given in the
-          <c>Varbinds</c> list. In this case, the OBJECT IDENTIFIER sent
-          in the trap is the OBJECT IDENTIFIER that identifies this
-          element.  This OBJECT IDENTIFIER could be used in a get
-          operation later.
-          </p>
-        <p>This function is asynchronous, and does not return any
-          information.  If an error occurs, <c>snmp_error:user_err/2</c>
-          is called and the trap is discarded. </p>
-
-        <marker id="discovery"></marker>
-      </desc>
-    </func>
--->
 
     <func>
       <name>discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}</name>