From 41648101cfe91b1e43e4436eb658ceb889897989 Mon Sep 17 00:00:00 2001
From: Christian Hammers <ch@php.net>
Date: Mon, 21 Feb 2011 22:39:56 +0000
Subject: [PATCH] Documented snmp_set_valueretrieval() and
 snmp_get_valueretrieval().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@308549 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../functions/snmp-get-valueretrieval.xml     | 46 ++++++++--
 .../functions/snmp-set-valueretrieval.xml     | 88 +++++++++++++++++--
 2 files changed, 121 insertions(+), 13 deletions(-)

diff --git a/reference/snmp/functions/snmp-get-valueretrieval.xml b/reference/snmp/functions/snmp-get-valueretrieval.xml
index d67f6450f0..dc8c54788a 100644
--- a/reference/snmp/functions/snmp-get-valueretrieval.xml
+++ b/reference/snmp/functions/snmp-get-valueretrieval.xml
@@ -1,32 +1,61 @@
 <?xml version='1.0' encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.snmp-get-valueretrieval" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.snmp-get-valueretrieval" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>snmp_get_valueretrieval</refname>
   <refpurpose>
    Return the method how the SNMP values will be returned
   </refpurpose>
  </refnamediv>
+ 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>int</type><methodname>snmp_get_valueretrieval</methodname>
+   <type>int</type>
+   <methodname>snmp_get_valueretrieval</methodname>
    <void/>
   </methodsynopsis>
-
-   &warn.undocumented.func;
-
  </refsect1>
-
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   On of the SNMP_VALUE_LIBRARY, SNMP_VALUE_PLAIN, SNMP_VALUE_OBJECT constants.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using snmp_get_valueretrieval</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+ $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
+ if (snmp_get_valueretrieval() == SNMP_VALUE_OBJECT) {
+   echo $ret->value;
+ } else {
+   echo $ret;
+ }
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>snmp_set_valueretrieval</function></member>
+    <member>
+     <function>snmp_set_valueretrieval</function>
+    </member>
+    <member><xref linkend="snmp.constants" /></member>
    </simplelist>
   </para>
  </refsect1>
-
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file
@@ -49,3 +78,4 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
+
diff --git a/reference/snmp/functions/snmp-set-valueretrieval.xml b/reference/snmp/functions/snmp-set-valueretrieval.xml
index 86084428b5..af89fd1d9c 100644
--- a/reference/snmp/functions/snmp-set-valueretrieval.xml
+++ b/reference/snmp/functions/snmp-set-valueretrieval.xml
@@ -7,26 +7,103 @@
    Specify the method how the SNMP values will be returned
   </refpurpose>
  </refnamediv>
+ 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>bool</type><methodname>snmp_set_valueretrieval</methodname>
-   <methodparam><type>int</type><parameter>method</parameter></methodparam>
+   <type>bool</type>
+   <methodname>snmp_set_valueretrieval</methodname>
+   <methodparam>
+    <type>int</type>
+    <parameter>method</parameter>
+    <initializer>SNMP_VALUE_LIBRARY</initializer>
+   </methodparam>
   </methodsynopsis>
+ </refsect1>
+ 
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term>
+      <parameter>method</parameter>
+     </term>
+     <listitem>
+      <table>
+       <title>types</title>
+       <tgroup cols="2">
+        <tbody>
+         <row>
+          <entry>SNMP_VALUE_LIBRARY</entry>
+          <entry>The return values will be as returned by the Net-SNMP library.</entry>
+         </row>
+         <row>
+          <entry>SNMP_VALUE_PLAIN</entry>
+          <entry>The return values will be the plain value without the SNMP type hint.</entry>
+         </row>
+         <row>
+          <entry>SNMP_VALUE_OBJECT</entry>
+          <entry>
+           The return values will be objects with the properties "value" and "type", where the latter
+           is one of the SNMP_OCTET_STR, SNMP_COUNTER etc. constants.           
+          </entry>
+         </row>
+        </tbody>
+       </tgroup>
+      </table>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+ 
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using
+     <function>snmp_set_valueretrieval</function>
+    </title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+ snmp_set_valueretrieval(SNMP_VALUE_LIBRARY);
+ $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
+ // $ret = "STRING: lo"
 
-   &warn.undocumented.func;
+ snmp_set_valueretrieval(SNMP_VALUE_PLAIN);
+ $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
+ // $ret = "lo";
 
+ snmp_set_valueretrieval(SNMP_VALUE_OBJECT);
+ $ret = snmpget('localhost', 'public', 'IF-MIB::ifName.1');
+ // stdClass Object
+ // (
+ //   [type] => 4        <-- SNMP_OCTET_STR, see constants
+ //   [value] => lo
+ // )
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
  </refsect1>
  
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>snmp_get_valueretrieval</function></member>
+    <member>
+     <function>snmp_get_valueretrieval</function>
+    </member>
+    <member><xref linkend="snmp.constants" /></member>
    </simplelist>
   </para>
  </refsect1>
-
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file
@@ -49,3 +126,4 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
+