[snmp/agent] Updated documentation and release notes

1 files changed, 192 insertions, 40 deletions

diff --git a/lib/snmp/doc/src/snmpa_mib_data.xml b/lib/snmp/doc/src/snmpa_mib_data.xml
index eeeb124d9d..8e79bb1673 100644
--- a/lib/snmp/doc/src/snmpa_mib_data.xml
+++ b/lib/snmp/doc/src/snmpa_mib_data.xml
@@ -23,10 +23,7 @@
 
     <title>snmpa_mib_data</title>
     <prepared></prepared>
-    <responsible></responsible>
     <docno></docno>
-    <approved></approved>
-    <checked></checked>
     <date></date>
     <rev></rev>
     <file>snmpa_mib_data.xml</file>
@@ -41,76 +38,89 @@
     must export the following functions: </p>
     <list type="bulleted">
       <item>
-        <p>new/1</p>
+	<seealso marker="#new">new/1</seealso>
       </item>
       <item>
-        <p>close/1</p>
+	<seealso marker="#close">close/1</seealso>
       </item>
       <item>
-        <p>sync/1</p>
+	<seealso marker="#sync">sync/1</seealso>
       </item>
       <item>
-        <p>load_mib/4</p>
+	<seealso marker="#load_mib">load_mib/4</seealso>
       </item>
       <item>
-        <p>unload_mib/4</p>
+	<seealso marker="#unload_mib">unload_mib/4</seealso>
       </item>
       <item>
-        <p>lookup/2</p>
+	<seealso marker="#lookup">lookup/2</seealso>
       </item>
       <item>
-        <p>next/3</p>
+	<seealso marker="#next">next/3</seealso>
       </item>
       <item>
-        <p>register_subagent/3</p>
+	<seealso marker="#register_subagent">register_subagent/3</seealso>
       </item>
       <item>
-        <p>unregister_subagent/2</p>
+	<seealso marker="#unregister_subagent">unregister_subagent/2</seealso>
       </item>
       <item>
-        <p>which_mib/2</p>
+	<seealso marker="#which_mib">which_mib/2</seealso>
       </item>
       <item>
-        <p>which_mibs/1</p>
+	<seealso marker="#which_mibs">which_mibs/1</seealso>
       </item>
       <item>
-        <p>whereis_mib/2</p>
+	<seealso marker="#whereis_mib">whereis_mib/2</seealso>
       </item>
       <item>
-        <p>backup/2</p>
+	<seealso marker="#dump">dump/2</seealso>
       </item>
       <item>
-        <p>dump/2</p>
+	<seealso marker="#info">info/1</seealso>
       </item>
       <item>
-        <p>info/1,2</p>
+	<seealso marker="#backup">backup/2</seealso>
       </item>
       <item>
-        <p>code_change/2</p>
+	<seealso marker="#code_change">code_change/4</seealso>
       </item>
     </list>
-    <p>The semantics of them and their exact signatures are explained
-    below. </p>
 
-    <marker id="handle_error"></marker>
+    <p>The semantics of them and their exact signatures are 
+    explained below. </p>
+
+    <p>Note that some of the data need to be "passed on" to the 
+    symbolic-store for storage, see the default mib-server data 
+    module, <c>snmpa_mib_data_tttn</c> for details. </p>
+
   </description>
+
+  <section>
+    <title>CALLBACK FUNCTIONS</title>
+    <p>The following functions must be exported from a 
+    <c>mib-server</c> data callback module: </p>
+
+    <marker id="new"></marker>
+  </section>
+
   <funcs>
     <func>
-      <name>new(Storage) -> State</name>
-      <fsummary>Create new (mib-storage) instance</fsummary>
+      <name>Module:new(Storage) -> State</name>
+      <fsummary>Create new (mib-server) data instance</fsummary>
       <type>
         <v>Storage = mib_storage()</v>
         <v>State = term()</v>
       </type>
       <desc>
-        <p>Create a new mib-storage instance. </p>
+        <p>Create a new mib-server data instance. </p>
 
         <marker id="close"></marker>
       </desc>
     </func>
 
     <func>
-      <name>close(State) -> void()</name>
+      <name>Module:close(State) -> void()</name>
       <fsummary>Close the mib-storage</fsummary>
       <type>
         <v>State = term()</v>
@@ -123,13 +133,13 @@
     </func>
 
     <func>
-      <name>sync(State) -> void()</name>
+      <name>Module:sync(State) -> void()</name>
       <fsummary>Synchronize to disc</fsummary>
       <type>
         <v>State = term()</v>
       </type>
       <desc>
-        <p>Synchronize (write to disc, if possible) the data to disc. 
+        <p>Synchronize (write to disc, if possible) the mib-server data. 
 	This depends on the <c>mib_storage</c> option, and will only have 
 	an effect if the mib-storage option has an actual disc component 
 	(such as dets, or ets with a file). </p>
@@ -139,7 +149,7 @@
     </func>
 
     <func>
-      <name>load_mib(State, Filename, MeOverride, TeOverride) -> {ok, NewState} | {error, Reason}</name>
+      <name>Module:load_mib(State, Filename, MeOverride, TeOverride) -> {ok, NewState} | {error, Reason}</name>
       <fsummary>Load a mib into the mib-server</fsummary>
       <type>
         <v>State = NewState = term()</v>
@@ -160,7 +170,7 @@
     </func>
 
     <func>
-      <name>unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}</name>
+      <name>Module:unload_mib(State, Filename) -> {ok, NewState} | {error, Reason}</name>
       <fsummary>Unload mib from the mib-server</fsummary>
       <type>
         <v>State = NewState = term()</v>
@@ -176,7 +186,7 @@
     </func>
 
     <func>
-      <name>lookup(State, Oid) -> Reply</name>
+      <name>Module:lookup(State, Oid) -> Reply</name>
       <fsummary>Find the mib-entry corresponding to the Oid</fsummary>
       <type>
         <v>State = term()</v>
@@ -187,19 +197,18 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Find the mib-entry corresponding to the Oid. 
-	If it is a variable, the Oid must be 
-	<Oid for var>.0 
-	and if it is a table, Oid must be 
-	<table>.<entry>.<col>.<any>.</p>
-	<!-- FIX -->
+        <p>Find the mib-entry corresponding to the <c>Oid</c>. 
+	If it is a variable, the <c>Oid</c> must be 
+	&lt;Oid for var&gt;.0 
+	and if it is a table, <c>Oid</c> must be 
+	&lt;table&gt;.&lt;entry&gt;.&lt;col&gt;.&lt;any&gt;.</p>
 
         <marker id="next"></marker>
       </desc>
     </func>
 
     <func>
-      <name>next(State, Oid, MibView) -> Reply</name>
+      <name>Module:next(State, Oid, MibView) -> Reply</name>
       <fsummary>Finds the lexicographically next oid</fsummary>
       <type>
         <v>State = term()</v>
@@ -216,7 +225,7 @@
     </func>
 
     <func>
-      <name>register_subagent(State, Oid, Pid) -> Reply</name>
+      <name>Module:register_subagent(State, Oid, Pid) -> Reply</name>
       <fsummary>Register the subagent</fsummary>
       <type>
         <v>State = NewState = term()</v>
@@ -226,13 +235,156 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Register the the subagent, process, 
+        <p>Register the subagent, process, 
 	handling part of the mib-tree. </p>
 
         <marker id="unregister_subagent"></marker>
       </desc>
     </func>
 
+    <func>
+      <name>Module:unregister_subagent(State, PidOrOid) -> Reply</name>
+      <fsummary>Unregister the subagent</fsummary>
+      <type>
+        <v>State = NewState = term()</v>
+        <v>Reply = {ok, NewState} | {ok, NewState, Pid} | {error, Reason}</v>
+        <v>PidOrOid = pid() | oid()</v>
+        <v>Pid = pid()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Unregister the subagent, handling part of the mib-tree, 
+	as specified by the <c>oid()</c> or <c>pid()</c> 
+	(<c>PidOrOid</c>). </p>
+        <p>When unregister the subagent using an <c>oid()</c>, the <c>pid()</c> 
+	of the process handling the sub-tree is also returned. </p>
+
+        <marker id="dump"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:dump(State, Destination) -> Reply</name>
+      <fsummary>Unregister the subagent</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>Reply = ok | {error, Reason}</v>
+        <v>Destination = io | filename()</v>
+        <v>Pid = pid()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Dump the mib-server data to <c>stdio</c> (Destination = <c>io</c>) or
+	the specified file. </p>
+
+        <marker id="which_mib"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:which_mib(State, Oid) -> Reply</name>
+      <fsummary>Retrieve the mib file for an oid()</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>Reply = {ok, MibFile} | {error, Reason}</v>
+        <v>Oid = oid()</v>
+        <v>MibFile = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Retrieve the mib-file to which an given <c>oid()</c> belongs. </p>
+
+        <marker id="which_mibs"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:which_mibs(State) -> Reply</name>
+      <fsummary>Retrieve all loaded mib files</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>Reply = [{MibName, Filename}]</v>
+        <v>MibName = atom()</v>
+        <v>Filename = string()</v>
+      </type>
+      <desc>
+        <p>Retrieve all loaded mib-files. </p>
+
+        <marker id="whereis_mib"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:whereis_mib(State, MibName) -> Reply</name>
+      <fsummary>Retrieve the mib file for the mib</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>MibName = atom()</v>
+        <v>Reply = {ok, Filename} | {error, Reason}</v>
+        <v>Filename = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Retrieve the mib file for the mib. </p>
+
+        <marker id="info"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:info(State) -> Reply</name>
+      <fsummary>Retrieve misc info for the mib data</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>Reply = {ok, Filename} | {error, Reason}</v>
+        <v>Filename = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Retrieve misc info for the mib data. </p>
+        <p>This is a utility function used to inspect, for instance, 
+	memory usage, in a simple way. </p>
+
+        <marker id="backup"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:backup(State, BackupDir) -> Reply</name>
+      <fsummary>Perform a backup of the mib-server data</fsummary>
+      <type>
+        <v>State = term()</v>
+        <v>Reply = ok | {error, Reason}</v>
+        <v>BackupDir = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Perform a backup of the mib-server data. </p>
+        <p>Note that its implementation dependant (and also 
+	dependent on mib-storage is used) if a backup is possible. </p>
+
+        <marker id="code_change"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:code_change(Destination, Vsn, Extra, State) -> NewState</name>
+      <fsummary>Perform a code-change</fsummary>
+      <type>
+        <v>Destination = up | down</v>
+        <v>Vsn = term()</v>
+        <v>Extra = term()</v>
+        <v>State = NewState = term()</v>
+      </type>
+      <desc>
+        <p>Perform a code-change (upgrade or downgrade). </p>
+        <p>See 
+	<seealso marker="gen_server">gen_server</seealso>
+	for more info regarding the <c>Vsn</c> and <c>Extra</c> arguments. </p>
+
+      </desc>
+    </func>
+
   </funcs>
   
 </erlref>