| | 1 | \chapter{Introduction} |
|---|
| | 2 | |
|---|
| | 3 | |
|---|
| | 4 | \section{XML-RPC Signatures} |
|---|
| | 5 | |
|---|
| | 6 | The XMLRPC signatures used in this part of the manual define a translation |
|---|
| | 7 | between the XMLRPC value and C-friendly data types that represent the same |
|---|
| | 8 | information. For example, it might say that a floating point number translates |
|---|
| | 9 | to or from a C double value, or that an array of 4 integers translates to or |
|---|
| | 10 | from 4 C int values. |
|---|
| | 11 | |
|---|
| | 12 | A format string usually describes the type of one XMLRPC value. But some types |
|---|
| | 13 | (array and structure) are compound types -- they are composed recursively of |
|---|
| | 14 | other XMLRPC values. So a single format string might involve multiple XMLRPC |
|---|
| | 15 | values. |
|---|
| | 16 | |
|---|
| | 17 | But first, lets look at the simple (not compound) format types. These are easy. |
|---|
| | 18 | The format string consists of one of the strings in the list below. The string |
|---|
| | 19 | is called a format specifier, and in particular a simple format specifier. |
|---|
| | 20 | |
|---|
| | 21 | The XMLRPC server uses only three native XMLRPC datatypes: |
|---|
| | 22 | |
|---|
| | 23 | \begin{labeling}{00.00.0000} |
|---|
| | 24 | \item [{\texttt{int}}] signed 32-bit integer (-2,147,483,648 to +2,147,483,647) |
|---|
| | 25 | \item [{\texttt{bool}}] boolean value (true/false) |
|---|
| | 26 | \item [{\texttt{string}}] character string of arbitrary length |
|---|
| | 27 | \end{labeling} |
|---|
| | 28 | |
|---|
| | 29 | Unfortunately the XMLRPC protocol does not define 64-bit integer values, |
|---|
| | 30 | therefore the XMLRPC server uses the native string datatype and converts all |
|---|
| | 31 | leading digit characters to 64-bit integer representation. |
|---|
| | 32 | |
|---|
| | 33 | This chapter uses the following convention to denote these integer datatypes: |
|---|
| | 34 | |
|---|
| | 35 | \begin{labeling}{00.00.0000} |
|---|
| | 36 | \item [{\texttt{int32}}] signed 32-bit integer |
|---|
| | 37 | (-2,147,483,648 to +2,147,483,647) |
|---|
| | 38 | \item [{\texttt{uint32}}] unsigned 32-bit integer |
|---|
| | 39 | (0 to +4,294,967,295) |
|---|
| | 40 | \item [{\texttt{int64}}] signed 64-bit integer |
|---|
| | 41 | (-9,223,372,036,854,775,808 to +9,223,372,036,854,775,807) |
|---|
| | 42 | \item [{\texttt{uint64}}] unsigned 64-bit integer |
|---|
| | 43 | (0 to +18,446,744,073,709,551,615) |
|---|
| | 44 | \end{labeling} |
|---|
| | 45 | |
|---|
| | 46 | The simple datatypes mentioned above are not sufficent to represent data in an |
|---|
| | 47 | efficient way. Therefore compound datatypes are defined in XMLRPC. There are two |
|---|
| | 48 | compound datatypes: array and struct. The signature denotes arrays using |
|---|
| | 49 | normal braces, structs use curly braces. |
|---|
| | 50 | |
|---|
| | 51 | \begin{labeling}{00.00.0000} |
|---|
| | 52 | \item [{\texttt{array}}] An array holds a series of data elements. Individual |
|---|
| | 53 | elements are accessed by their position array in the array. |
|---|
| | 54 | \item [{\texttt{struct}}] A structure is a collection of simple datatypes under |
|---|
| | 55 | a single compund. This collection can be of different types, and each has |
|---|
| | 56 | a name which is used to select it from the structure. A structure is a |
|---|
| | 57 | convenient way of grouping several pieces of related information together. |
|---|
| | 58 | \end{labeling} |
|---|
| | 59 | |
|---|
| | 60 | Here are some examples of XMLRPC signatures: |
|---|
| | 61 | |
|---|
| | 62 | \begin{itemize} |
|---|
| | 63 | \item A single \texttt{string} datatype named \emph{path}:\\ |
|---|
| | 64 | \texttt{string path} |
|---|
| | 65 | \item An \texttt{array} of three int datatypes:\\ |
|---|
| | 66 | \texttt{(int, int, int)} |
|---|
| | 67 | \item An \texttt{array} with one \texttt{bool}, one \texttt{string} and one |
|---|
| | 68 | \texttt{int} datatype:\\ |
|---|
| | 69 | \texttt{(bool, string, int)} |
|---|
| | 70 | \item A \texttt{struct} with one \texttt{string} and one \texttt{int} |
|---|
| | 71 | datatype:\\ |
|---|
| | 72 | \texttt{\{string name, int id\}} |
|---|
| | 73 | \end{itemize} |
|---|
| | 74 | |
|---|
| | 75 | Please note that the next chapters use the following convention to declare |
|---|
| | 76 | methods and their parameters, although they do not involve arrays. |
|---|
| | 77 | |
|---|
| | 78 | \begin{quote} |
|---|
| | 79 | \texttt{vx.create(string name, string template, int rebuild)} |
|---|
| | 80 | \end{quote} |
|---|
| | 81 | |
|---|
| | 82 | Instead this convention matches the function declaration in the C language. |
|---|
| | 83 | Translated to a XMLRPC signature format string the above would become a struct: |
|---|
| | 84 | |
|---|
| | 85 | \begin{quote} |
|---|
| | 86 | \texttt{\{string name, string template, int rebuild\}} |
|---|
| | 87 | \end{quote} |
|---|
| | 88 | |
|---|
| | 89 | Read on to the next section to learn how method requests are performed and how |
|---|
| | 90 | this struct is placed in the request. |
|---|
| | 91 | |
|---|
| | 92 | |
|---|
| | 93 | \section{Performing XML-RPC Requests} |
|---|
| | 94 | |
|---|
| | 95 | An XMLRPC method call is an HTTP-POST request. The body of the request is in |
|---|
| | 96 | XML. The specified method executes on the server and the value it returns is |
|---|
| | 97 | also formatted in XML. |
|---|
| | 98 | |
|---|
| | 99 | Here is an example of an XML-RPC request: |
|---|
| | 100 | |
|---|
| | 101 | \begin{verbatim} |
|---|
| | 102 | POST /RPC2 HTTP/1.0 |
|---|
| | 103 | User-Agent: VCC/1.0 |
|---|
| | 104 | Host: betty.userland.com |
|---|
| | 105 | Content-Type: text/xml |
|---|
| | 106 | Content-length: 181 |
|---|
| | 107 | |
|---|
| | 108 | <?xml version="1.0"?> |
|---|
| | 109 | <methodCall> |
|---|
| | 110 | <methodName>examples.getStateName</methodName> |
|---|
| | 111 | <params> |
|---|
| | 112 | <param> |
|---|
| | 113 | <value><i4>41</i4></value> |
|---|
| | 114 | </param> |
|---|
| | 115 | </params> |
|---|
| | 116 | </methodCall> |
|---|
| | 117 | \end{verbatim} |
|---|
| | 118 | |
|---|
| | 119 | |
|---|
| | 120 | \subsection{Header Requirements} |
|---|
| | 121 | |
|---|
| | 122 | The following requirements must be met when sending requests to the XMLRPC |
|---|
| | 123 | server: |
|---|
| | 124 | |
|---|
| | 125 | \begin{itemize} |
|---|
| | 126 | \item The \texttt{/RPC2} location handler to explicitly denote XMLRPC requests |
|---|
| | 127 | \item A User-Agent and Host must be specified |
|---|
| | 128 | \item The Content-Type is text/xml |
|---|
| | 129 | \item The Content-Length must be specified and must be correct |
|---|
| | 130 | \end{itemize} |
|---|
| | 131 | |
|---|
| | 132 | |
|---|
| | 133 | \subsection{Payload Format} |
|---|
| | 134 | |
|---|
| | 135 | The payload is in XML, a single \texttt{<methodCall>} structure. |
|---|
| | 136 | |
|---|
| | 137 | The \texttt{<methodCall>} must contain a \texttt{<methodName>} sub-item, a |
|---|
| | 138 | string, containing the name of the method to be called. The string may only |
|---|
| | 139 | contain identifier characters, upper and lower-case A-Z, the numeric |
|---|
| | 140 | characters, 0-9, underscore, dot, colon and slash. |
|---|
| | 141 | |
|---|
| | 142 | If the procedure call has parameters, the <methodCall> must contain a <params> |
|---|
| | 143 | sub-item. The <params> sub-item can contain any number of <param>s, each of |
|---|
| | 144 | which has a <value>. |
|---|
| | 145 | |
|---|
| | 146 | |
|---|
| | 147 | \subsubsection{Simple Datatypes} |
|---|
| | 148 | |
|---|
| | 149 | The XMLRPC server only uses three native datatypes as mentioned above: |
|---|
| | 150 | |
|---|
| | 151 | \begin{labeling}{00.00.0000} |
|---|
| | 152 | \item [{\texttt{<int>}}] signed 32-bit integer |
|---|
| | 153 | \item [{\texttt{<boolean>}}] 0 (false) or 1 (true) |
|---|
| | 154 | \item [{\texttt{<string>}}] character string of arbitrary length |
|---|
| | 155 | \end{labeling} |
|---|
| | 156 | |
|---|
| | 157 | If no type is indicated, the type is string. |
|---|
| | 158 | |
|---|
| | 159 | |
|---|
| | 160 | \subsubsection{Structures} |
|---|
| | 161 | |
|---|
| | 162 | \subsubsection{Arrays} |
|---|
| | 163 | |
|---|
| | 164 | \subsection{Method Initialization} |
|---|
| | 165 | |
|---|
| | 166 | \subsection{Authentication and Access Restrictions} |
|---|
| | 167 | |
|---|
| | 168 | \subsection{Response Format} |
|---|
| | 169 | |
|---|
| | 170 | |
|---|
| | 171 | |
|---|
| | 172 | \section{Method Error Codes} |
|---|