diff options
Diffstat (limited to 'lib/snmp/doc/src/snmp_index.xml')
| -rw-r--r-- | lib/snmp/doc/src/snmp_index.xml | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/lib/snmp/doc/src/snmp_index.xml b/lib/snmp/doc/src/snmp_index.xml new file mode 100644 index 0000000000..cd241820e8 --- /dev/null +++ b/lib/snmp/doc/src/snmp_index.xml @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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 + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>snmp_index</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date></date> + <rev></rev> + <file>snmp_index.xml</file> + </header> + <module>snmp_index</module> + <modulesummary>Abstract Data Type for SNMP Indexing</modulesummary> + <description> + <p>The module <c>snmp_index</c> implements an Abstract + Data Type (ADT) for an SNMP + index structure for SNMP tables. It is implemented as an ets + table of the ordered_set data-type, which means that all operations are + O(log n). In the table, the key is an ASN.1 OBJECT + IDENTIFIER. + </p> + <p>This index is used to separate the implementation of the SNMP + ordering from the actual implementation of the table. The SNMP + ordering, that is implementation of GET NEXT, is implemented in this + module. + </p> + <p>For example, suppose there is an SNMP table, which is best + implemented in Erlang as one process per SNMP table row. Suppose + further that the INDEX in the SNMP table is an OCTET STRING. The + index structure would be created as follows: + </p> + <code type="none"> +snmp_index:new(string) + </code> + <p>For each new process we create, we insert an item in an + <c>snmp_index</c> structure: + </p> + <code type="none"><![CDATA[ +new_process(Name, SnmpIndex) -> + Pid = start_process(), + NewSnmpIndex = + snmp_index:insert(SnmpIndex, Name, Pid), + <...> + ]]></code> + <p>With this structure, we can now map an OBJECT IDENTIFIER in + e.g. a GET NEXT request, to the correct process: + </p> + <code type="none"> +get_next_pid(Oid, SnmpIndex) -> + {ok, {_, Pid}} = snmp_index:get_next(SnmpIndex, Oid), + Pid. + </code> + </description> + + <section> + <title>Common data types</title> + <p>The following data types are used in the functions below: + </p> + <list type="bulleted"> + <item> + <p><c>index()</c></p> + </item> + <item> + <p><c>oid() = [byte()]</c></p> + </item> + <item> + <p><c>key_types = type_spec() | {type_spec(), type_spec(), ...}</c></p> + </item> + <item> + <p><c>type_spec() = fix_string | string | integer</c></p> + </item> + <item> + <p><c>key() = key_spec() | {key_spec(), key_spec(), ...}</c></p> + </item> + <item> + <p><c>key_spec() = string() | integer()</c></p> + </item> + </list> + <p>The <c>index()</c> type denotes an snmp index structure. + </p> + <p>The <c>oid()</c> type is used to represent an ASN.1 OBJECT + IDENTIFIER. + </p> + <p>The <c>key_types()</c> type is used when creating the + index structure, and the <c>key()</c> type is used when inserting + and deleting items from the structure. + </p> + <p>The <c>key_types()</c> type defines the types of the SNMP INDEX + columns for the table. If the table has one single INDEX column, + this type should be a single atom, but if the table has multiple + INDEX columns, it should be a tuple with atoms. + </p> + <p>If the INDEX column is of type INTEGER, or derived from + INTEGER, the corresponding type should be <c>integer</c>. If it + is a variable length type (e.g. OBJECT IDENTIFIER, OCTET STRING), + the corresponding type should be <c>string</c>. Finally, if the + type is of variable length, but with a fixed size restriction + (e.g. IpAddress), the corresponding type should be + <c>fix_string</c>. + </p> + <p>For example, if the SNMP table has two INDEX columns, the first + one an OCTET STRING with size 2, and the second one an OBJECT + IDENTIFER, the corresponding <c>key_types</c> parameter would be + <c>{fix_string, string}</c>. + </p> + <p>The <c>key()</c> type correlates to the <c>key_types()</c> + type. If the <c>key_types()</c> is a single atom, the + corresponding <c>key()</c> is a single type as well, but if the + <c>key_types()</c> is a tuple, <c>key</c> must be a tuple of the + same size. + </p> + <p>In the example above, valid <c>keys</c> could be <c>{"hi", "mom"}</c> and <c>{"no", "thanks"}</c>, whereas <c>"hi"</c>, + <c>{"hi", 42}</c> and <c>{"hello", "there"}</c> would be invalid.</p> + <warning> + <marker id="1"></marker> + <p>All API functions that update the index return a <c>NewIndex</c> + term. This is for backward compatibility with a previous + implementation that used a B+ tree written purely in Erlang for + the index. The <c>NewIndex</c> return value can now be ignored. + The return value is now the unchanged table identifier for the + ets table.</p> + <p>The implementation using ets tables introduces a semantic + incompatibility with older implementations. In those older + implementations, using pure Erlang terms, the index was garbage + collected like any other Erlang term and did not have to be + deleted when discarded. An ets table is deleted only when the + process creating it explicitly deletes it or when the creating + process terminates.</p> + <p>A new interface <c>delete/1</c> is now added to + handle the case when a process wants to discard an index table + (i.e. to build a completely new). Any application using + transient snmp indexes has to be modified to handle this.</p> + <p>As an snmp adaption usually keeps the index for the whole of the + systems lifetime, this is rarely a problem.</p> + </warning> + </section> + <funcs> + <func> + <name>delete(Index) -> true</name> + <fsummary>Delete an index table</fsummary> + <type> + <v>Index = NewIndex = index()</v> + <v>Key = key()</v> + </type> + <desc> + <p>Deletes a complete index structure (i.e. the ets table + holding the index). The index can no longer be referenced + after this call. See the <seealso marker="#1">warning note</seealso> + above.</p> + </desc> + </func> + <func> + <name>delete(Index, Key) -> NewIndex</name> + <fsummary>Delete an item from the index</fsummary> + <type> + <v>Index = NewIndex = index()</v> + <v>Key = key()</v> + </type> + <desc> + <p>Deletes a key and its value from the index structure. + Returns a new structure.</p> + </desc> + </func> + <func> + <name>get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined</name> + <fsummary>Get the item with <c>KeyOid</c></fsummary> + <type> + <v>Index = index()</v> + <v>KeyOid = oid()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Gets the item with key <c>KeyOid</c>. Could be used from + within an SNMP instrumentation function.</p> + </desc> + </func> + <func> + <name>get_last(Index) -> {ok, {KeyOid, Value}} | undefined</name> + <fsummary>Get the last item in the index structure</fsummary> + <type> + <v>Index = index()</v> + <v>KeyOid = oid()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Gets the last item in the index structure.</p> + </desc> + </func> + <func> + <name>get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined</name> + <fsummary>Get the next item</fsummary> + <type> + <v>Index = index()</v> + <v>KeyOid = NextKeyOid = oid()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Gets the next item in the SNMP lexicographic ordering, + after <c>KeyOid</c> in the index structure. <c>KeyOid</c> + does not have to refer to an existing item in the index.</p> + </desc> + </func> + <func> + <name>insert(Index, Key, Value) -> NewIndex</name> + <fsummary>Insert an item into the index</fsummary> + <type> + <v>Index = NewIndex = index()</v> + <v>Key = key()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Inserts a new key value tuple into the index structure. If + an item with the same key already exists, the new <c>Value</c> + overwrites the old value.</p> + </desc> + </func> + <func> + <name>key_to_oid(Index, Key) -> KeyOid</name> + <fsummary>Convert a key to an OBJECT IDENTIFIER</fsummary> + <type> + <v>Index = index()</v> + <v>Key = key()</v> + <v>KeyOid = NextKeyOid = oid()</v> + </type> + <desc> + <p>Converts <c>Key</c> to an OBJECT IDENTIFIER.</p> + </desc> + </func> + <func> + <name>new(KeyTypes) -> Index</name> + <fsummary>Create a new snmp index structure</fsummary> + <type> + <v>KeyTypes = key_types()</v> + <v>Index = index()</v> + </type> + <desc> + <p>Creates a new snmp index structure. The <c>key_types()</c> + type is described above.</p> + </desc> + </func> + </funcs> + +</erlref> + |