david
28b02db2ea
git-svn-id: https://192.168.0.254/svn/Proyectos.Incam_SGD/tags/3.7.0.2_original@1 eb19766c-00d9-a042-a3a0-45cb8ec72764
48 lines
21 KiB
HTML
48 lines
21 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>1. xmlrpcval</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="XML-RPC for PHP"><link rel="up" href="ch07.html" title="Chapter 7. Class documentation"><link rel="prev" href="ch07.html" title="Chapter 7. Class documentation"><link rel="next" href="ch07s02.html" title="2. xmlrpcmsg"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1. xmlrpcval</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch07.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Class documentation</th><td width="20%" align="right"> <a accesskey="n" href="ch07s02.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="xmlrpcval"></a>1. xmlrpcval</h2></div></div></div><p>This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.</p><p>Ensure you've read the XML-RPC spec at <a href="http://www.xmlrpc.com/stories/storyReader$7" target="_top">http://www.xmlrpc.com/stories/storyReader$7</a> before reading on as it will make things clearer.</p><p>The <code class="classname">xmlrpcval</code> class can store arbitrarily complicated values using the following types: <code class="literal">i4 int boolean string double dateTime.iso8601 base64 array struct</code>. You should refer to the <a href="http://www.xmlrpc.com/spec" target="_top">spec</a> for more information on what each of these types mean.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e815"></a>1.1. Notes on types</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e818"></a>1.1.1. int</h4></div></div></div><p>The type <code class="classname">i4</code> is accepted as a synonym for <code class="classname">int</code> when creating xmlrpcval objects. The xml parsing code will always convert <code class="classname">i4</code> to <code class="classname">int</code>: <code class="classname">int</code> is regarded by this implementation as the canonical name for this type.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e838"></a>1.1.2. base64</h4></div></div></div><p>Base 64 encoding is performed transparently to the caller when using this type. Decoding is also transparent. Therefore you ought to consider it as a "binary" data type, for use when you want to pass data that is not 7-bit clean.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e843"></a>1.1.3. boolean</h4></div></div></div><p>The php values <code class="literal">true</code> and <code class="literal">1</code> map to <code class="literal">true</code>. All other values (including the empty string) are converted to <code class="literal">false</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e860"></a>1.1.4. string</h4></div></div></div><p>Characters <, >, ', ", &, are encoded using their entity reference as &lt; &gt; &apos; &quot; and &amp; All other characters outside of the ASCII range are encoded using their character reference representation (e.g. &#200 for é). The XML-RPC spec recommends only encoding <code class="literal">< &</code> but this implementation goes further, for reasons explained by <a href="http://www.w3.org/TR/REC-xml#syntax" target="_top">the XML 1.0 recommendation</a>. In particular, using character reference representation has the advantage of producing XML that is valid independently of the charset encoding assumed.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="xmlrpcval-creation"></a>1.2. Creation</h3></div></div></div><p>The constructor is the normal way to create an <code class="classname">xmlrpcval</code>. The constructor can take these forms:</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$myVal = new <b class="fsfunc">xmlrpcval</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$myVal = new <b class="fsfunc">xmlrpcval</b>(</code></td><td><var class="pdparam">$stringVal</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code>string</code> </td><td><code><var class="pdparam">$stringVal</var>;</code></td></tr></table><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$myVal = new <b class="fsfunc">xmlrpcval</b>(</code></td><td><var class="pdparam">$scalarVal</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">$scalartyp</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code>mixed</code> </td><td><code><var class="pdparam">$scalarVal</var>;</code></td></tr><tr><td><code>string</code> </td><td><code><var class="pdparam">$scalartyp</var>;</code></td></tr></table><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$myVal = new <b class="fsfunc">xmlrpcval</b>(</code></td><td><var class="pdparam">$arrayVal</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">$arraytyp</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>array</code> </td><td><code><var class="pdparam">$arrayVal</var>;</code></td></tr><tr><td><code>string</code> </td><td><code><var class="pdparam">$arraytyp</var>;</code></td></tr></table></div><p>The first constructor creates an empty value, which must be altered using the methods <code class="function">addScalar</code>, <code class="function">addArray</code> or <code class="function">addStruct</code> before it can be used.</p><p>The second constructor creates a simple string value.</p><p>The third constructor is used to create a scalar value. The second parameter must be a name of an XML-RPC type. Valid types are: "<code class="literal">int</code>", "<code class="literal">boolean</code>", "<code class="literal">string</code>", "<code class="literal">double</code>", "<code class="literal">dateTime.iso8601</code>", "<code class="literal">base64</code>".</p><p>Examples:</p><pre class="programlisting">
|
|
$myInt = new xmlrpcvalue(1267, "int");
|
|
$myString = new xmlrpcvalue("Hello, World!", "string");
|
|
$myBool = new xmlrpcvalue(1, "boolean");
|
|
$myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
|
|
|
|
</pre><p>The fourth constructor form can be used to compose complex XML-RPC values. The first argument is either a simple array in the case of an XML-RPC <code class="classname">array</code> or an associative array in the case of a <code class="classname">struct</code>. The elements of the array <span class="emphasis"><em>must be <code class="classname">xmlrpcval</code> objects themselves</em></span>.</p><p>The second parameter must be either "<code class="literal">array</code>" or "<code class="literal">struct</code>".</p><p>Examples:</p><pre class="programlisting">
|
|
$myArray = new xmlrpcval(
|
|
array(
|
|
new xmlrpcval("Tom"),
|
|
new xmlrpcval("Dick"),
|
|
new xmlrpcval("Harry")
|
|
),
|
|
"array");
|
|
|
|
// recursive struct
|
|
$myStruct = new xmlrpcval(
|
|
array(
|
|
"name" => new xmlrpcval("Tom", "string"),
|
|
"age" => new xmlrpcval(34, "int"),
|
|
"address" => new xmlrpcval(
|
|
array(
|
|
"street" => new xmlrpcval("Fifht Ave", "string"),
|
|
"city" => new xmlrpcval("NY", "string")
|
|
),
|
|
"struct")
|
|
),
|
|
"struct");
|
|
|
|
</pre><p>See the file <code class="literal">vardemo.php</code> in this distribution for more examples.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="xmlrpcval-methods"></a>1.3. Methods</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e997"></a>1.3.1. addScalar</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$ok = $val-><b class="fsfunc">addScalar</b>(</code></td><td><var class="pdparam">$stringVal</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code>string</code> </td><td><code><var class="pdparam">$stringVal</var>;</code></td></tr></table><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$ok = $val-><b class="fsfunc">addScalar</b>(</code></td><td><var class="pdparam">$scalarVal</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">$scalartyp</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>mixed</code> </td><td><code><var class="pdparam">$scalarVal</var>;</code></td></tr><tr><td><code>string</code> </td><td><code><var class="pdparam">$scalartyp</var>;</code></td></tr></table></div><p>If <em class="parameter"><code>$val</code></em> is an empty <code class="classname">xmlrpcval</code> this method makes it a scalar value, and sets that value.</p><p>If <em class="parameter"><code>$val</code></em> is already a scalar value, then no more scalars can be added and <code class="literal">0</code> is returned.</p><p>If <em class="parameter"><code>$val</code></em> is an xmlrpcval of type array, the php value <em class="parameter"><code>$scalarval</code></em> is added as its last element.</p><p>If all went OK, <code class="literal">1</code> is returned, otherwise <code class="literal">0</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1058"></a>1.3.2. addArray</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$ok = $val-><b class="fsfunc">addArray</b>(</code></td><td><var class="pdparam">$arrayVal</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>array</code> </td><td><code><var class="pdparam">$arrayVal</var>;</code></td></tr></table></div><p>The argument is a simple (numerically indexed) array. The elements of the array <span class="emphasis"><em>must be <code class="classname">xmlrpcval</code> objects themselves</em></span>.</p><p>Turns an empty <code class="classname">xmlrpcval</code> into an <code class="classname">array</code> with contents as specified by <em class="parameter"><code>$arrayVal</code></em>.</p><p>If <em class="parameter"><code>$val</code></em> is an xmlrpcval of type array, the elements of <em class="parameter"><code>$arrayVal</code></em> are appended to the existing ones.</p><p>See the fourth constructor form for more information.</p><p>If all went OK, <code class="literal">1</code> is returned, otherwise <code class="literal">0</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1109"></a>1.3.3. addStruct</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$ok = $val-><b class="fsfunc">addStruct</b>(</code></td><td><var class="pdparam">$assocArrayVal</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>array</code> </td><td><code><var class="pdparam">$assocArrayVal</var>;</code></td></tr></table></div><p>The argument is an associative array. The elements of the array <span class="emphasis"><em>must be <code class="classname">xmlrpcval</code> objects themselves</em></span>.</p><p>Turns an empty <code class="classname">xmlrpcval</code> into a <code class="classname">struct</code> with contents as specified by <em class="parameter"><code>$assocArrayVal</code></em>.</p><p>If <em class="parameter"><code>$val</code></em> is an xmlrpcval of type struct, the elements of <em class="parameter"><code>$arrayVal</code></em> are merged with the existing ones.</p><p>See the fourth constructor form for more information.</p><p>If all went OK, <code class="literal">1</code> is returned, otherwise <code class="literal">0</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1160"></a>1.3.4. kindOf</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$kind = $val-><b class="fsfunc">kindOf</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>Returns a string containing "struct", "array" or "scalar" describing the base type of the value. If it returns "undef" it means that the value hasn't been initialised.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1172"></a>1.3.5. serialize</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$outString = $val-><b class="fsfunc">serialize</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>Returns a string containing the XML-RPC representation of this value.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1184"></a>1.3.6. scalarVal</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$scalarVal = $val-><b class="fsfunc">scalarVal</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>If <code class="function">$val->kindOf() == "scalar"</code>, this method returns the actual PHP-language value of the scalar (base 64 decoding is automatically handled here).</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1199"></a>1.3.7. scalarTyp</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$typeName = $val-><b class="fsfunc">scalarTyp</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>If <code class="function">$val->kindOf() == "scalar"</code>, this method returns a string denoting the type of the scalar. As mentioned before, <code class="literal">i4</code> is always coerced to <code class="literal">int</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1220"></a>1.3.8. arrayMem</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$xmlrpcVal = $val-><b class="fsfunc">arrayMem</b>(</code></td><td><var class="pdparam">$n</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>int</code> </td><td><code><var class="pdparam">$n</var>;</code></td></tr></table></div><p>If <code class="function">$val->kindOf() == "array"</code>, returns the <em class="parameter"><code>$n</code></em>th element in the array represented by the value <em class="parameter"><code>$val</code></em>. The value returned is an <code class="classname">xmlrpcval</code> object.</p><pre class="programlisting">
|
|
// iterating over values of an array object
|
|
for ($i = 0; $i < $val->arraySize(); $i++)
|
|
{
|
|
$v = $val->arrayMem($i);
|
|
echo "Element $i of the array is of type ".$v->kindOf();
|
|
}
|
|
|
|
</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1251"></a>1.3.9. arraySize</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$len = $val-><b class="fsfunc">arraySize</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>If <em class="parameter"><code>$val</code></em> is an <code class="classname">array</code>, returns the number of elements in that array.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1269"></a>1.3.10. structMem</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$xmlrpcVal = $val-><b class="fsfunc">structMem</b>(</code></td><td><var class="pdparam">$memberName</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>string</code> </td><td><code><var class="pdparam">$memberName</var>;</code></td></tr></table></div><p>If <code class="function">$val->kindOf() == "struct"</code>, returns the element called <em class="parameter"><code>$memberName</code></em> from the struct represented by the value <em class="parameter"><code>$val</code></em>. The value returned is an <code class="classname">xmlrpcval</code> object.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e1297"></a>1.3.11. structEach</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">list($key, $value) = $val-><b class="fsfunc">structEach</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>Returns the next (key, value) pair from the struct, when <em class="parameter"><code>$val</code></em> is a struct. <em class="parameter"><code>$value</code></em> is an xmlrpcval itself. See also <a href="ch07s01.html#structreset">structreset()</a>.</p><pre class="programlisting">
|
|
// iterating over all values of a struct object
|
|
$val->structreset();
|
|
while (list($key, $v) = $val->structEach())
|
|
{
|
|
echo "Element $key of the struct is of type ".$v->kindOf();
|
|
}
|
|
|
|
</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="structreset"></a>1.3.12. structReset</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$val-><b class="fsfunc">structReset</b>(</code></td><td><code>)</code>;</td><td> </td></tr></table></div><p>Resets the internal pointer for <code class="function">structEach()</code> to the beginning of the struct, where <em class="parameter"><code>$val</code></em> is a struct.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="structmemexists"></a>1.3.13. structMemExists</h4></div></div></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">$exists = $val-><b class="fsfunc">structMemExsists</b>(</code></td><td><var class="pdparam">$memberName</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>string</code> </td><td><code><var class="pdparam">$memberName</var>;</code></td></tr></table></div><p>Returns <code class="constant">TRUE</code> or <code class="constant">FALSE</code> depending on whether a member of the given name exists in the struct.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch07s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Class documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2. xmlrpcmsg</td></tr></table></div></body></html> |