svn: /phpdoc/en/trunk/reference/snmp/functions/ snmp3-set.xml

From: 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

« previous php.doc.cvs (#7786) next »