c-agent10.html

vxworks相关论文

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="83950">4.10.2  &nbsp;&nbsp;Input Parameters to Method Routines</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="83951"> </a>The following parameters are passed by the SNMP agent to the MIB method routines. It is important to understand the meanings of these parameters before writing any method routines. For source-code examples, look to the source code provided with this product in <b class="file">$WIND_BASE/target/src/snmpv1/agent</b>.</p>
</dl>

</dl>

<dl class="margin">

<dd><font face="Helvetica, sans-serif" size="-1" class="sans">
<h5 class="HU"><i><a name="83952"><i class="textVariable">last_match</i>, <i class="textVariable">compc</i>, and <i class="textVariable">compl</i></a></i></h5>
</font><dl class="margin">

<dd><p class="Body"><a name="83953"> </a>In SNMP, the name of a variable is composed of two parts.  The first part is the sequence of numbers which form the object identifier for the variable.  The second part is a sequence of one or more numbers which name the instance of the variable.  For scalar variables, SNMP defines the instance to be the single number zero.  For tabular variables, RFC 1157 defines how the instance is represented for each table found in RFC 1213.  Within the SNMP PDUs, these two parts are concatenated together to form a single object identifier. This is known as a <i class="emphasis">variable binding</i>.</p>
<dd><p class="Body"><a name="83954"> </a>During the processing of a <b class="command">GET</b>, <b class="command">GET NEXT</b>, <b class="command">GET BULK</b>, or <b class="command">SET </b>request PDU, the object identifier in the variable binding becomes a search target.  The search is a descent of the MIB tree.  As the search progresses, the components of the target object identifier are consumed, starting from the high-order, leftmost end.  Assuming that the target is valid, the search continues until it reaches a leaf of the MIB tree.  Once the leaf is reached, the access functions may be called depending on the type of PDU being processed.</p>
<dd><p class="Body"><a name="83955"> </a>The parameter named <i class="textVariable">last_match</i> is the value of the last component of the object identifier consumed during the tree search.  For example, if the target is the object identifier 1.2.3.4.5.6, and there exists a variable whose name is 1.2.3.4, then the value of <i class="textVariable">last_match</i> is 4. </p>
<dd><p class="Body"><a name="83956"> </a>The parameters named <i class="textVariable">compc</i> and <i class="textVariable">compl</i> describe the unused part of the target. The <i class="textVariable">compc</i> parameter is the count of components referenced by <i class="textVariable">compl</i>. The variable <i class="textVariable">compl</i> is a pointer to the list of unconsumed components. Again assuming that the target is 1.2.3.4.5.6 and a leaf is encountered at 1.2.3.4, <i class="textVariable">compc</i> would have the value of 2 and <i class="textVariable">compl</i> would point to an array containing the values 5 and 6.</p>
<dd><p class="Body"><a name="83957"> </a>For scalar variables, these three parameters are not particularly useful. </p>
<dd><p class="Body"><a name="83958"> </a>For tabular variables, <i class="textVariable">compc</i> and <i class="textVariable">compl</i> define the row of the table in which the variable is to be found.  The access function uses this information to look up the variable in its internal data structures.</p>
<dd><p class="Body"><a name="83959"> </a><i class="textVariable">last_match</i> is useful, but not strictly necessary, when dealing with tabular variables.  One can define the leaf nodes in the MIB so that for each attribute (column) in a table, there are a unique set of access functions, each set written to handle a particular attribute.  This is not an efficient use of code space.  The <i class="textVariable">last_match</i> parameter allows one to write a single set of access functions for each table.  The <i class="textVariable">last_match</i> parameter gives these access functions a way to determine which column in the table should be used. </p>
<dd><p class="Body"><a name="83960"> </a>By way of example, assume that there exists a table whose RFC 1213 identifier is 1.2.3.4.  Further assume that the table contains three variables in each row.  Assume that these variables are named <i class="textVariable">interfaceName</i>, <i class="textVariable">bytesIn</i>, and <i class="textVariable">bytesOut</i> with object IDs, respectively, 1.2.3.4.1, 1.2.3.4.2, and 1.2.3.4.3.  Without the <i class="textVariable">last_match</i> parameter, it would be necessary to provide a distinct set of access functions for <i class="textVariable">interfaceName</i>, <i class="textVariable">bytesIn</i>, and <i class="textVariable">bytesOut</i>.  With the <i class="textVariable">last_match</i> parameter, it would be possible to merge the access functions for all three. The <i class="textVariable">last_match</i> paramenter would have a value of 1 when accessing <i class="textVariable">interfaceName</i>, a value of 2 when accessing <i class="textVariable">bytesIn</i> and a value of 3 when accessing <i class="textVariable">bytesOut</i>.</p>
</dl>

<dd><font face="Helvetica, sans-serif" size="-1" class="sans">
<h5 class="HU"><i><a name="83961"><i class="textVariable">pktp</i> and <i class="textVariable">vbp</i></a></i></h5>
</font><dl class="margin">

<dd><p class="Body"><a name="83962"> </a>Each method routine has the ability to view the requested packet in its entirety.  This is accomplished via the <i class="textVariable">pktp</i> parameter. It is also given a pointer (<i class="textVariable">vbp</i>) to the <b class="symbol_UC">VB_T</b> structure that caused the access routine to be called.</p>
</dl>

<dd><font face="Helvetica, sans-serif" size="-1" class="sans">
<h5 class="HU"><i><a name="83963"><i class="textVariable">cookie</i> </a></i></h5>
</font><dl class="margin">

<dd><p class="Body"><a name="83964"> </a>The data structure for leaf nodes of the MIB tree contains a <i class="textVariable">cookie</i> field. The <i class="textVariable">cookie </i>parameter<i class="textVariable"> </i>is, by convention, the address of the target-management variable.  For tabular variables, you are free to place any value in the leaf structure.  </p>
<dd><p class="Body"><a name="83965"> </a><i class="textVariable">cookie</i> is stored and passed in the form of a pointer to a character.  The number of bits is, consequently, system-dependent. </p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="83966">4.10.3  &nbsp;&nbsp;Overall Validity Check and Set Aggregation</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="83967"> </a>The complex series of actions and user-defined hooks which are performed during the handling of a <b class="keyword">SET</b> request is designed to give you the means to perform overall consistency checking of the request and to collect related set actions into a single operation.</p>
<dd><p class="Body"><a name="83968"> </a>The <i class="textVariable">vb_link</i> field in the <b class="symbol_UC">VB_T</b> structure is available to the application as a means to link related VarBinds to one another. For example, during the PDU-validation hook (see <a href="c-agent8.html#83905"><i class="title">4.8&nbsp;Hooks</i></a>) or during the calls to the <b class="keyword">testproc</b> routines, the application could link a number of related VarBinds so that they could be processed together during the <b class="keyword">setproc</b> operations in a subsequent hook.</p>
<dd><p class="Body"><a name="83972"> </a>The locator field of the <b class="symbol_UC">MIBLEAF_T</b> structure is used to help the application find related VarBinds in a query.  The locator can be used to assign a unique, easily handled, numeric name to each item in the MIB. For tabular elements of the MIB it is necessary to examine instance information once a VarBind entry has been located in a query. </p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="83973">4.10.4  &nbsp;&nbsp;VarBind Private Field</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="83974"> </a>During <b class="keyword">SET</b> operations, it may become necessary to reserve resources that are used if the <b class="keyword">SET</b> completes but that may need to be released if the set fails.</p>
<dd><p class="Body"><a name="83975"> </a>The <i class="textVariable">vb_priv</i> and <i class="textVariable">vb_free_priv</i> fields are available to the application as a means to link reserved resources to a <b class="symbol_UC">VB_T</b> and release those resources when the SNMP agent is finished processing the packet.  <i class="textVariable">vb_priv</i> is of type <b class="symbol_UC">PTR_T</b>; an application may fill this field during the PDU-valudation hook (see <a href="c-agent8.html#83905"><i class="title">4.8&nbsp;Hooks</i></a>) or during the calls to the <b class="keyword">testproc</b> operations.  The <i class="textVariable">vb_free_priv</i> field is a pointer to a routine that is called when the packet is cleaned at the end of processing and provides a way to clean up user-allocated resources if a <b class="keyword">SET</b> operation fails.</p>
<dd><p class="Body"><a name="83979"> </a>For example, during the <b class="keyword">testproc</b> routine, the application could reserve a block of memory that it would need for the <b class="keyword">SET</b> to complete. The <b class="keyword">testproc</b> routine would then put a pointer to that memory block into the <i class="textVariable">vb_priv</i> field of the <b class="symbol_UC">VB_T</b> being tested.  It would also put a pointer to a routine to free the memory into the vb_free_priv field.  If the set completes normally, the <b class="keyword">setproc</b> operation would remove both pointers from the <b class="symbol_UC">VB_T</b>.  If the <b class="keyword">SET</b> fails for some reason (perhaps another variable is inconsistent or has an incorrect value), the pointers are not reset.  At the end of processing the packet, routines are called to release the packet resources.  One of these routines checks the <i class="textVariable">vb_free_priv</i> field and, if the field is not 0, calls the private-memory-deallocation hook (see <a href="c-agent8.html#83905"><i class="title">4.8&nbsp;Hooks</i></a>) with either the <b class="symbol_UC">PTR_T</b> from the <i class="textVariable">vb_priv</i> field or a pointer to the <b class="symbol_UC">VB_T</b> as the argument.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="83983">4.10.5  &nbsp;&nbsp;Undo Field</a></i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="83984"> </a>As described in the section on <b class="keyword">SET</b> PDU processing, if a <b class="keyword">setproc</b> operation indicates an error, it is necessary to undo any sets that have already been started.  The <i class="textVariable">undoproc</i> field in a <b class="symbol_UC">VB_T</b> is available to the application to hold a pointer to a routine to undo the effects of a <b class="keyword">setproc</b> operation.  You may place a value there during the <b class="keyword">testproc</b> or <b class="keyword">setproc</b> operation.  The SNMP agent runs the routine as soon as possible after an error is noticed, even if the <b class="keyword">SET</b> operation has not completed.  If this presents a problem you should install the routine at the end of the set task.  You may find the <i class="textVariable">vb_priv</i> field to be a convenient place to store old information that the undo routine may need to restore the previous state.  If you do use <i class="textVariable">vb_priv</i> you should also update <i class="textVariable">vb_free_priv</i> to free the information correctly.</p>
</dl>

</dl>


<a name="foot"><hr></a>


<p class="navbar" align="right"><a href="index.html"><img border="0" alt="[Contents]" src="icons/contents.gif"></a></a><a href="c-agent.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="c-agent9.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="c-agent11.html"><img border="0" alt="[Next]" src="icons/next.gif"></a></p>

</body>

</html>
<!---
by WRS Documentation (), Wind River Systems, Inc.
    conversion tool:  Quadralay WebWorks Publisher 4.0.11
    template:         CSS Template, Jan 1998 - Jefro --->