<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.20 $ -->
 <reference id="ref.wddx">
  <title>WDDX Functions</title>
  <titleabbrev>WDDX</titleabbrev>
  
  <partintro>
   <para>
    These functions are intended for work with <ulink
    url="&url.wddx;">WDDX</ulink>.
   </para>
   <para>
    In order to use WDDX, you will need to install the expat library
    (which comes with apache 1.3.7 or higher) and recompile PHP with
    <option role="configure">--with-xml</option> and <option
    role="configure">--enable-wddx</option>.
   </para>
   <note>
    <para>
      If you want to serialize non-ASCII characters you have to set
      the appropriate locale before doing so (see 
      <function>setlocale</function>).
    </para>
   </note>
   <para>
    All the functions that serialize variables use the first
    element of an array to determine whether the array is to be
    serialized into an array or structure.  If the first element has
    string key, then it is serialized into a structure, otherwise,
    into an array.
    <example>
     <title>Serializing a single value</title>
     <programlisting role="php">
<![CDATA[
<?php
print wddx_serialize_value("PHP to WDDX packet example", "PHP packet");
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    This example will produce:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<wddxPacket version='1.0'><header comment='PHP packet'/><data>
<string>PHP to WDDX packet example</string></data></wddxPacket>
]]>
     </programlisting>
    </informalexample>

    <example>
     <title>Using incremental packets</title>
     <programlisting role="php">
<![CDATA[
<?php
$pi = 3.1415926;
$packet_id = wddx_packet_start("PHP");
wddx_add_vars($packet_id, "pi");

/* Suppose $cities came from database */
$cities = array("Austin", "Novato", "Seattle");
wddx_add_vars($packet_id, "cities");

$packet = wddx_packet_end($packet_id);
print $packet;
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    This example will produce:
    <informalexample>
     <screen>
<![CDATA[
<wddxPacket version='1.0'><header comment='PHP'/><data><struct>
<var name='pi'><number>3.1415926</number></var><var name='cities'>
<array length='3'><string>Austin</string><string>Novato</string>
<string>Seattle</string></array></var></struct></data></wddxPacket>
]]>
     </screen>
    </informalexample>
   </para>
  </partintro>
  
  <refentry id="function.wddx-serialize-value">
   <refnamediv>
    <refname>wddx_serialize_value</refname>
    <refpurpose>Serialize a single value into a WDDX packet</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>wddx_serialize_value</methodname>
      <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>comment</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>wddx_serialize_value</function> is used to create a
     WDDX packet from a single given value.  It takes the value
     contained in <parameter>var</parameter>, and an optional
     <parameter>comment</parameter> string that appears in the packet
     header, and returns the WDDX packet.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.wddx-serialize-vars">
   <refnamediv>
    <refname>wddx_serialize_vars</refname>
    <refpurpose>Serialize variables into a WDDX packet</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>wddx_serialize_vars</methodname>
      <methodparam><type>mixed</type><parameter>var_name</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>wddx_serialize_vars</function> is used to create a WDDX
     packet with a structure that contains the serialized
     representation of the passed variables.
    </para>
    <para>
     <function>wddx_serialize_vars</function> takes a variable number
     of arguments, each of which can be either a string naming a
     variable or an array containing strings naming the variables or
     another array, etc.
    </para>
    <para>
     <example>
      <title><function>wddx_serialize_vars</function> example</title>
      <programlisting>
<![CDATA[
<?php
$a = 1;
$b = 5.5;
$c = array("blue", "orange", "violet");
$d = "colors";

$clvars = array("c", "d");
print wddx_serialize_vars("a", "b", $clvars);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The above example will produce:
     <screen>
<![CDATA[
<wddxPacket version='1.0'><header/><data><struct><var name='a'><number>1</number></var>
<var name='b'><number>5.5</number></var><var name='c'><array length='3'>
<string>blue</string><string>orange</string><string>violet</string></array></var>
<var name='d'><string>colors</string></var></struct></data></wddxPacket>
]]>
     </screen>
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.wddx-packet-start">
   <refnamediv>
    <refname>wddx_packet_start</refname>
    <refpurpose>
     Starts a new WDDX packet with structure inside it
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>wddx_packet_start</methodname>
      <methodparam choice="opt"><type>string</type><parameter>comment</parameter></methodparam>
     </methodsynopsis>
    <para>
     Use <function>wddx_packet_start</function> to start a new WDDX
     packet for incremental addition of variables.  It takes an
     optional <parameter>comment</parameter> string and returns a
     packet ID for use in later functions.  It automatically creates a
     structure definition inside the packet to contain the variables.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.wddx-packet-end">
   <refnamediv>
    <refname>wddx_packet_end</refname>
    <refpurpose>Ends a WDDX packet with the specified ID</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>wddx_packet_end</methodname>
      <methodparam><type>int</type><parameter>packet_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>wddx_packet_end</function> ends the WDDX packet
     specified by the <parameter>packet_id</parameter> and returns the
     string with the packet.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.wddx-add-vars">
   <refnamediv>
    <refname>wddx_add_vars</refname>
    <refpurpose>
     Add variables to a WDDX packet with the specified ID
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <methodname>wddx_add_vars</methodname>
      <methodparam><type>int</type><parameter>packet_id</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>name_var</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>wddx_add_vars</function> is used to serialize passed
     variables and add the result to the packet specified by the
     <parameter>packet_id</parameter>.  The variables to be serialized
     are specified in exactly the same way as
     <function>wddx_serialize_vars</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.wddx-deserialize">
   <refnamediv>
    <refname>wddx_deserialize</refname>
    <refpurpose>Deserializes a WDDX packet</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>wddx_deserialize</methodname>
      <methodparam><type>string</type><parameter>packet</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>wddx_deserialize</function> takes a
     <parameter>packet</parameter> string and deserializes it.  It
     returns the result which can be string, number, or array.  Note
     that structures are deserialized into associative arrays.
    </para>
   </refsect1>
  </refentry>
 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->