1
0
Fork 0
mirror of https://github.com/Yetangitu/ampache synced 2025-10-04 18:29:40 +02:00
ampache/modules/xmlrpc/doc/xmlrpcval.html
Karl 'vollmerk' Vollmer bcad40a05a New Import
2005-06-09 16:34:40 +00:00

933 lines
No EOL
13 KiB
HTML

<HTML
><HEAD
><TITLE
>xmlrpcval</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.77+"><LINK
REV="MADE"
HREF="edd@usefulinc.com"><LINK
REL="HOME"
TITLE="XML-RPC for PHP"
HREF="index.html"><LINK
REL="UP"
TITLE="Class documentation"
HREF="apidocs.html"><LINK
REL="PREVIOUS"
TITLE="xmlrpcresp"
HREF="xmlrpcresp.html"><LINK
REL="NEXT"
TITLE="xmlrpc_server"
HREF="xmlrpc-server.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>XML-RPC for PHP: version 1.1</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="xmlrpcresp.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 5. Class documentation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="xmlrpc-server.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="XMLRPCVAL"
></A
>xmlrpcval</H1
><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 <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> class can store
arbitrarily complicated values using the following types:
<TT
CLASS="LITERAL"
>i4 int boolean string double dateTime.iso8601 base64
array struct</TT
>. You should refer to the <A
HREF="http://www.xmlrpc.com/stories/storyReader$7"
TARGET="_top"
>spec</A
>
for more information on what each of these types mean.
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN452"
></A
>Notes on types</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN454"
></A
>int</H3
><P
>The type <TT
CLASS="CLASSNAME"
>i4</TT
> is accepted as a
synonym for <TT
CLASS="CLASSNAME"
>int</TT
>. The value parsing
code will always convert <TT
CLASS="CLASSNAME"
>i4</TT
> to
<TT
CLASS="CLASSNAME"
>int</TT
>: <TT
CLASS="CLASSNAME"
>int</TT
>
is regarded by this implementation as the canonical name for
this type.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN462"
></A
>base64</H3
><P
>Base 64 encoding is performed transparently to the
caller when using this type. Therefore you ought to
consider it as a "binary" data type, for use when you want
to pass none 7-bit clean data. Decoding is also
transparent.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN465"
></A
>boolean</H3
><P
>The values <TT
CLASS="LITERAL"
>true</TT
> and
<TT
CLASS="LITERAL"
>1</TT
> map to <TT
CLASS="LITERAL"
>true</TT
>. All
other values (including the empty string)
are converted to <TT
CLASS="LITERAL"
>false</TT
>.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN472"
></A
>string</H3
><P
> The characters <TT
CLASS="LITERAL"
>&lt; &gt; &quot;</TT
> and
<TT
CLASS="LITERAL"
>&amp;</TT
> are converted to their entity
equivalents <TT
CLASS="LITERAL"
>&amp;lt; &amp;gt;
&amp;quot;</TT
> and <TT
CLASS="LITERAL"
>&amp;amp;</TT
>
for transport through XML-RPC. The current XML-RPC spec
recommends only encoding <TT
CLASS="LITERAL"
>&lt; &amp;</TT
> 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
>.
</P
><P
>TODO: <TT
CLASS="LITERAL"
> &amp;apos;</TT
> entity not
yet supported</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="XMLRPCVAL-CREATION"
></A
>Creation</H2
><P
>The constructor is the normal way to create an
<TT
CLASS="CLASSNAME"
>xmlrpcval</TT
>. The constructor can take
these forms:
</P
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN487"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$myVal=new xmlrpcval</CODE
>();</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$myVal=new xmlrpcval</CODE
>($stringVal);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$myVal=new xmlrpcval</CODE
>($scalarVal, "int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64");</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$myVal=new xmlrpcval</CODE
>($arrayVal, "array" | "struct");</CODE
></P
><P
></P
></DIV
><P
>The first constructor creates an empty value, which must
be altered using the methods <TT
CLASS="FUNCTION"
>addScalar</TT
>,
<TT
CLASS="FUNCTION"
>addArray</TT
> or
<TT
CLASS="FUNCTION"
>addStruct</TT
> 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. Examples:
</P
><PRE
CLASS="PROGRAMLISTING"
> $myInt=new xmlrpcvalue(1267, "int");
$myString=new xmlrpcvalue("Hello, World!", "string");
$myBool=new xmlrpcvalue(1, "boolean");
</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 <TT
CLASS="CLASSNAME"
>array</TT
> or
an associative array in the case of a
<TT
CLASS="CLASSNAME"
>struct</TT
>. The elements of the array
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must be <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> objects
themselves</I
></SPAN
>.
Examples:</P
><PRE
CLASS="PROGRAMLISTING"
> $myArray=new xmlrpcval(array(
new xmlrpcval("Tom"), new xmlrpcval("Dick"),
new xmlrpcval("Harry")), "array");
$myStruct=new xmlrpcval(array(
"name" =&#62; new xmlrpcval("Tom"),
"age" =&#62; new xmlrpcval(34, "int"),
"geek" =&#62; new xmlrpcval(1, "boolean")), "struct");
</PRE
><P
>See the file <TT
CLASS="LITERAL"
>vardemo.php</TT
> in this
distribution for more examples.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="XMLRPCVAL-METHODS"
></A
>Methods</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN524"
></A
>addScalar</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN526"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$ok=$val-&#62;addScalar</CODE
>($stringVal);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$ok=$val-&#62;addScalar</CODE
>($scalarVal, "int" | "boolean" | "string" | "double" | "dateTime.iso8601" | "base64");</CODE
></P
><P
></P
></DIV
><P
> If <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
> is an empty
<TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> this method makes it a
scalar value, and sets that value. If
<TT
CLASS="PARAMETER"
><I
>$val</I
></TT
> is already a scalar value, then
no more scalars can be added and <TT
CLASS="LITERAL"
>0</TT
> is
returned. If all went OK, <TT
CLASS="LITERAL"
>1</TT
> is returned.
</P
><P
>There is a special case if <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
>
is an <TT
CLASS="CLASSNAME"
>array</TT
>: the scalar value passed
is appended to the array.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN546"
></A
>addArray</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN548"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$ok=$val-&#62;addArray</CODE
>($arrayVal);</CODE
></P
><P
></P
></DIV
><P
>Turns an empty <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> into an
<TT
CLASS="CLASSNAME"
>array</TT
> with contents as specified by
<TT
CLASS="PARAMETER"
><I
>$arrayVal</I
></TT
>. See the fourth
constructor form for more information.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN557"
></A
>addStruct</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN559"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$ok=$val-&#62;addArray</CODE
>($assocArrayVal);</CODE
></P
><P
></P
></DIV
><P
>Turns an empty <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> into a
<TT
CLASS="CLASSNAME"
>struct</TT
> with contents as specified by
<TT
CLASS="PARAMETER"
><I
>$assocArrayVal</I
></TT
>. See the fourth
constructor form for more information.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN568"
></A
>kindOf</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN570"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$kind=$val-&#62;kindOf</CODE
>();</CODE
></P
><P
></P
></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"
><H3
CLASS="SECT3"
><A
NAME="AEN575"
></A
>serialize</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN577"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$outString=$val-&#62;serialize</CODE
>();</CODE
></P
><P
></P
></DIV
><P
> Returns a string containing the XML-RPC representation of
this value.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN582"
></A
>scalarval</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN584"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$scalarVal=$val-&#62;scalarval</CODE
>();</CODE
></P
><P
></P
></DIV
><P
> If <TT
CLASS="FUNCTION"
>$val-&#62;kindOf()=="scalar"</TT
>, this
method returns the actual PHP-language value of the scalar
(base 64 decoding is automatically handled here).
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN590"
></A
>scalartyp</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN592"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$typeName=$val-&#62;scalartyp</CODE
>();</CODE
></P
><P
></P
></DIV
><P
> If <TT
CLASS="FUNCTION"
>$val-&#62;kindOf()=="scalar"</TT
>, this
method returns a string denoting the type of the scalar.
As mentioned before,
<TT
CLASS="LITERAL"
>i4</TT
> is always coerced to <TT
CLASS="LITERAL"
>int</TT
>.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN600"
></A
>arraymem</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN602"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$xmlrpcVal=$val-&#62;arraymem</CODE
>($n);</CODE
></P
><P
></P
></DIV
><P
> Returns the <TT
CLASS="PARAMETER"
><I
>$n</I
></TT
>th element in the array
represented by the value <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
>. The
value returned is an <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> object.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN611"
></A
>arraysize</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN613"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$len=$val-&#62;arraysize</CODE
>();</CODE
></P
><P
></P
></DIV
><P
>If <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
> is an
<TT
CLASS="CLASSNAME"
>array</TT
>, returns the number of elements
in that array.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN620"
></A
>structmem</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN622"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$xmlrpcVal=$val-&#62;structmem</CODE
>($memberName);</CODE
></P
><P
></P
></DIV
><P
> Returns the element called
<TT
CLASS="PARAMETER"
><I
>$memberName</I
></TT
> from the struct
represented by the value <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
>. The
value returned is an <TT
CLASS="CLASSNAME"
>xmlrpcval</TT
> object.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN631"
></A
>structeach</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN633"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>list($key,$value)=$val-&#62;structeach</CODE
>();</CODE
></P
><P
></P
></DIV
><P
> Returns the next (key,value) pair from the struct, when
<TT
CLASS="PARAMETER"
><I
>$val</I
></TT
> is a struct. See also
<A
HREF="xmlrpcval.html#STRUCTRESET"
>structreset()</A
>.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="STRUCTRESET"
></A
>structreset</H3
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN642"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>$val-&#62;structreset</CODE
>();</CODE
></P
><P
></P
></DIV
><P
> Resets the internal pointer for
<TT
CLASS="FUNCTION"
>structeach()</TT
> to the beginning of the
struct, where <TT
CLASS="PARAMETER"
><I
>$val</I
></TT
> is a struct.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="xmlrpcresp.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="xmlrpc-server.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>xmlrpcresp</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="apidocs.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>xmlrpc_server</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>