svn: /phpdoc/en/trunk/reference/snmp/functions/ snmp3-set.xml
| From: | Christian Hammers | Date: | Sat, 19 Feb 2011 18:44:08 +0000 |
| Subject: | svn: /phpdoc/en/trunk/reference/snmp/functions/ snmp3-set.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-7786@lists.php.net to get a copy of this message | ||
ch Sat, 19 Feb 2011 18:44:08 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=308488
Log:
Added documentation for snmp3_set()
Changed paths:
U phpdoc/en/trunk/reference/snmp/functions/snmp3-set.xml
Modified: phpdoc/en/trunk/reference/snmp/functions/snmp3-set.xml
===================================================================
--- phpdoc/en/trunk/reference/snmp/functions/snmp3-set.xml 2011-02-19 17:45:24 UTC (rev 308487)
+++ phpdoc/en/trunk/reference/snmp/functions/snmp3-set.xml 2011-02-19 18:44:08 UTC (rev 308488)
@@ -6,7 +6,7 @@
<refname>snmp3_set</refname>
<refpurpose>Description</refpurpose>
</refnamediv>
-
+
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
@@ -25,13 +25,15 @@
<methodparam
choice="opt"><type>string</type><parameter>retries</parameter></methodparam>
</methodsynopsis>
<para>
-
+ <function>snmp3_set</function> is used to set the value of an
<acronym>SNMP</acronym> object
+ specified by the <parameter>object_id</parameter>.
</para>
-
- &warn.undocumented.func;
-
+ <para>
+ Even if the security level does not use an auth or priv protocol/password valid values have to
be specified.
+ </para>
+
</refsect1>
-
+
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
@@ -39,7 +41,7 @@
<term><parameter>host</parameter></term>
<listitem>
<para>
-
+ The hostname of the SNMP agent (server).
</para>
</listitem>
</varlistentry>
@@ -47,7 +49,7 @@
<term><parameter>sec_name</parameter></term>
<listitem>
<para>
-
+ the security name, usually some kind of username
</para>
</listitem>
</varlistentry>
@@ -55,7 +57,7 @@
<term><parameter>sec_level</parameter></term>
<listitem>
<para>
-
+ the security level (noAuthNoPriv|authNoPriv|authPriv)
</para>
</listitem>
</varlistentry>
@@ -63,7 +65,7 @@
<term><parameter>auth_protocol</parameter></term>
<listitem>
<para>
-
+ the authentication protocol (MD5 or SHA)
</para>
</listitem>
</varlistentry>
@@ -71,7 +73,7 @@
<term><parameter>auth_passphrase</parameter></term>
<listitem>
<para>
-
+ the authentication pass phrase
</para>
</listitem>
</varlistentry>
@@ -79,7 +81,7 @@
<term><parameter>priv_protocol</parameter></term>
<listitem>
<para>
-
+ the privacy protocol (DES or AES)
</para>
</listitem>
</varlistentry>
@@ -87,7 +89,7 @@
<term><parameter>priv_passphrase</parameter></term>
<listitem>
<para>
-
+ the privacy pass phrase
</para>
</listitem>
</varlistentry>
@@ -95,7 +97,7 @@
<term><parameter>object_id</parameter></term>
<listitem>
<para>
-
+ The <acronym>SNMP</acronym> object id.
</para>
</listitem>
</varlistentry>
@@ -103,15 +105,70 @@
<term><parameter>type</parameter></term>
<listitem>
<para>
-
+ The <acronym>MIB</acronym> defines the type of each object id. It has to be
specified as a single character from the below list.
</para>
+ <table>
+ <title>types</title>
+ <tgroup cols="2">
+ <tbody>
+ <row><entry>=</entry><entry>The type is taken from the
MIB</entry></row>
+ <row><entry>i</entry><entry>INTEGER</entry> </row>
+ <row><entry>u</entry><entry>INTEGER</entry></row>
+ <row><entry>s</entry><entry>STRING</entry></row>
+ <row><entry>x</entry><entry>HEX STRING</entry></row>
+ <row><entry>d</entry><entry>DECIMAL
STRING</entry></row>
+ <row><entry>n</entry><entry>NULLOBJ</entry></row>
+ <row><entry>o</entry><entry>OBJID</entry></row>
+ <row><entry>t</entry><entry>TIMETICKS</entry></row>
+ <row><entry>a</entry><entry>IPADDRESS</entry></row>
+ <row><entry>b</entry><entry>BITS</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ If OPAQUE_SPECIAL_TYPES was defined while compiling the SNMP library, the following are also
valid:
+ </para>
+ <table>
+ <title>types</title>
+ <tgroup cols="2">
+ <tbody>
+ <row><entry>U</entry><entry>unsigned
int64</entry></row>
+ <row><entry>I</entry><entry>signed int64</entry></row>
+ <row><entry>F</entry><entry>float</entry></row>
+ <row><entry>D</entry><entry>double</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Most of these will use the obvious corresponding ASN.1 type. 's', 'x',
'd' and 'b' are all different ways of specifying an OCTET STRING value, and
+ the 'u' unsigned type is also used for handling Gauge32 values.
+ </para>
+ <para>
+ If the MIB-Files are loaded by into the MIB Tree with "snmp_read_mib" or by
specifying it in the libsnmp config, '=' may be used as the
<parameter>type</parameter> parameter
+ for all object ids as the type can then be automatically read from the MIB.
+ </para>
+ <para>
+ Note that there are two ways to set a variable of the type BITS like e.g. "SYNTAX
BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}"
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Using type "b" and a list of bit numbers like: <programlisting
role="php">snmpset('FOO-MIB::bar.42', 'b', '0 1 2 3
4');</programlisting> with the disadvantage that the success is not easily verifyable as
an snmpget() for the same OID would return e.g. 0xF8.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using type "x" and a hex number but without(!) the usual "0x" prefix:
<programlisting role="php">snmpset('FOO-MIB::bar.42', 'x',
'F0');</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
-
+ The new value
</para>
</listitem>
</varlistentry>
@@ -119,7 +176,7 @@
<term><parameter>timeout</parameter></term>
<listitem>
<para>
-
+ The number of microseconds until the first timeout.
</para>
</listitem>
</varlistentry>
@@ -127,21 +184,41 @@
<term><parameter>retries</parameter></term>
<listitem>
<para>
-
+ The number of retries in case of timeouts.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
-
+
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
-
+ &return.success;
</para>
+ <para>
+ If the SNMP host rejects the data type, an E_WARNING message like "Warning: Error in
packet. Reason: (badValue) The value given has the wrong type or length." is shown.
+ If an unknown or invalid OID is specified the warning probably reads "Could not add
variable".
+ </para>
</refsect1>
-
-
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Using <function>snmpgetnext</function></title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ snmp3_set('localhost', 'james', 'authPriv', 'SHA',
'secret007', 'AES', 'secret007', 'IF-MIB::ifAlias.3',
's', "foo");
+?>
+ ]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
+
</refentry>
<!-- Keep this comment at the end of the file