diff options
Diffstat (limited to 'modules/xmlrpc/doc/xmlrpcval.html')
| -rw-r--r-- | modules/xmlrpc/doc/xmlrpcval.html | 933 |
1 files changed, 933 insertions, 0 deletions
diff --git a/modules/xmlrpc/doc/xmlrpcval.html b/modules/xmlrpc/doc/xmlrpcval.html new file mode 100644 index 00000000..68489699 --- /dev/null +++ b/modules/xmlrpc/doc/xmlrpcval.html @@ -0,0 +1,933 @@ +<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" +>< > "</TT +> and + <TT +CLASS="LITERAL" +>&</TT +> are converted to their entity + equivalents <TT +CLASS="LITERAL" +>&lt; &gt; + &quot;</TT +> and <TT +CLASS="LITERAL" +>&amp;</TT +> + for transport through XML-RPC. The current XML-RPC spec + recommends only encoding <TT +CLASS="LITERAL" +>< &</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" +> &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" => new xmlrpcval("Tom"), + "age" => new xmlrpcval(34, "int"), + "geek" => 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->addScalar</CODE +>($stringVal);</CODE +></P +><P +><CODE +><CODE +CLASS="FUNCDEF" +>$ok=$val->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->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->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->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->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->scalarval</CODE +>();</CODE +></P +><P +></P +></DIV +><P +> If <TT +CLASS="FUNCTION" +>$val->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->scalartyp</CODE +>();</CODE +></P +><P +></P +></DIV +><P +> If <TT +CLASS="FUNCTION" +>$val->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->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->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->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->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->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 +>
\ No newline at end of file |