git.maemo.org Git - xmlrpc-c/blob - tools/xmlrpc/xmlrpc.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <title>Xmlrpc User Manual</title>
   3 <body>
   4
   5 <p><b>xmlrpc</b> makes an XML-RPC remote procedure call (RPC) and displays
   6 the response.  <b>xmlrpc</b> runs an XML-RPC client.
   7
   8 <p>This program is mainly useful for debugging and learning about
   9 XML-RPC servers.  XML-RPC is such that the RPCs normally need to be made
  10 by a program rather than a person to be of use.
  11
  12 <p>A similar tool done as a web form is at <a
  13 href="http://gggeek.damacom.it/debugger/">
  14 http://gggeek.damacom.it/debugger/</a>
  15
  16 <h2>Examples</h2>
  17
  18 <pre>
  19 <tt>
  20      $ xmlrpc http://localhost:8080/RPC2 sample.add i/3 i/5
  21        Result:
  22          Integer: 8
  23 </tt>
  24 </pre>
  25
  26 <pre>
  27 <tt>
  28      $ xmlrpc localhost:8080 sample.add i/3 i/5
  29        Result:
  30          Integer: 8
  31
  32 </tt>
  33 </pre>
  34
  35 <pre>
  36 <tt>
  37      $ xmlrpc http://xmlrpc.server.net/~bryanh echostring \
  38          &quot;s/This is a string&quot;
  39      Result:
  40        String: This is a string
  41
  42 </tt>
  43 </pre>
  44
  45 <pre>
  46 <tt>
  47      $ xmlrpc http://xmlrpc.server.net/~bryanh echostring \
  48          &quot;This is a string in shortcut syntax&quot;
  49      Result:
  50        String: This is a string in shortcut syntax
  51
  52 </tt>
  53 </pre>
  54 <pre>
  55 <tt>
  56      $ xmlrpc http://xmlrpc.server.net sample.add i/3 i/5 \
  57          transport=curl -curlinterface=eth1 -username=bryanh -password=passw0rd
  58        Result:
  59          Integer: 8
  60
  61 </tt>
  62 </pre>
  63
  64 <h2>Overview</h2>
  65 <p>
  66 <b>xmlrpc</b>
  67 <i>url</i>
  68 <i>methodName</i>
  69 <i>parameter</i> ...
  70 [<b>-transport=</b><i>transportname</i>]
  71 [<b>-username=</b><i>username</i> <b>-password=</b><i>password</i>]
  72 [<b>-curlinterface</b>={<i>interface</i>|<i>host</i>}]
  73 [<b>-curlnoverifypeer</b>]
  74 [<b>-curlnoverifyhost</b>]
  75
  76 <p><i>parameter</i>:
  77
  78 <p>
  79 <b>i/</b><i>integer</i> |
  80 <b>s/</b><i>string</i> |
  81 <b>b/</b>{<b>true</b>|<b>false</b>|<b>t</b>|<b>f</b>} |
  82 <b>d/</b><i>realnum</i> |
  83 <b>n/</b> |
  84 <b><i>string</i></b>
  85
  86
  87 <P>Minimum unique abbreviation of option is acceptable.  You may use double
  88 hyphens instead of single hyphen to denote options.  You may use white
  89 space in place of the equals sign to separate an option name from its value.
  90
  91
  92 <h2>Arguments</h2>
  93
  94 <dl>
  95 <dt><i>url</i>
  96
  97 <dd>This is the URL of the XML-RPC server.  As XML-RPC uses HTTP, this
  98 must be an HTTP url.  However, if you don't specify a type (&quot;http:&quot;)
  99 in the URL, <b>xmlrpc</b> assumes an &quot;http://&quot; prefix and a
 100 &quot;/RPC2&quot; suffix.  <b>RPC2</b> is the conventional file name for
 101 an XML-RPC responder.
 102
 103 <dt><i>methodName</i>
 104
 105 <dd>The name of the XML-RPC method you want to invoke.
 106
 107 <dt><i>parameter</i> ...
 108
 109 <dd>The list of parameters for the RPC.  <b>xmlrpc</b> turns each of these
 110 arguments into an XML-RPC parameter, in the order given.  You may specify
 111 no parameters if you like.
 112
 113 <p>You specify the data type of the parameter with a prefix ending in
 114 a slash.  Example: <b>i/5</b>.  Here, the &quot;i&quot; signifies an
 115 integer data type.  &quot;5&quot; is the value.
 116
 117 <p><b>xmlrpc</b> is capable of only a subset of the
 118 possible XML-RPC types, as follows by prefix:
 119
 120 <dl>
 121 <dt>i/
 122 <dd>integer (&lt;int4&gt;)
 123
 124 <dt>s/
 125 <dd>string (&lt;string&gt;)
 126
 127 <dt>b/
 128 <dd>boolean (&lt;boolean&gt;)
 129
 130 <dt>d/
 131 <dd>double (&lt;double&gt;)  (i.e. real number)
 132
 133 <dt>n/
 134 <dd>nil (&lt;nil&gt;)
 135
 136 </dl>
 137
 138 <p>As a shortcut, if you don't specify a prefix (i.e. your argument does
 139 not contain a slash), <b>xmlrpc</b> assumes string data type.
 140
 141 </dl>
 142
 143
 144 <h2>Options</h2>
 145
 146 <dl>
 147 <dt><b>-transport=</b><i>transportname</i>
 148
 149 <dd>This selects the XML transport facility (e.g. libwww) that
 150 <b>xmlrpc</b> uses to perform the RPC.
 151
 152 <p>The name <i>transportname</i> is one that the Xmlrpc-c programming
 153 library recognizes.  This is typically <b>libwww</b>, <b>curl</b>, and
 154 <b>wininet</b>.
 155
 156 <p>By default, <b>xmlrpc</b> lets the Xmlrpc-c library choose.
 157
 158 <dt><b>-username=</b><i>username</i>
 159 <dt><b>-password=</b><i>password</i>
 160
 161 <dd>These options, which must be used together, cause the client to
 162 authenticate itself to the server, if the server requires it, using
 163 HTTP Basic Authentication and the specified username and password.
 164
 165 <dt><b>-curlinterface</b>={<i>interface</i>|<i>host</i>}
 166
 167 <dd>
 168 This option gives the &quot;interface&quot; option for a Curl XML transport.
 169
 170 <p>The exact meaning of this option is up to the Curl library, and the
 171 best documentation for it is the manual for the 'curl' program that comes
 172 with the Curl library.
 173
 174 <p>But essentially, it chooses the local network interface through which
 175 to send the RPC.  It causes the Curl library to perform a
 176 &quot;bind&quot; operation on the socket it uses for the
 177 communication.  It can be the name of a network interface (e.g. on
 178 Linux, &quot;eth1&quot;) or an IP address of the interface or a host
 179 name that resolves to the IP address of the interface.  Unfortunately,
 180 you can't explicitly state which form you're specifying, so there's
 181 some ambiguity.
 182
 183 <p>Examples:
 184
 185 <ul>
 186
 187 <li>
 188 <kbd>
 189 -interface=eth1
 190 </kbd>
 191
 192 <li>
 193 <kbd>
 194 -interface=64.171.19.66
 195 </kbd>
 196
 197 <li>
 198 <kbd>
 199 -interface=giraffe.giraffe-data.com
 200 </kbd>
 201
 202 </ul>
 203
 204 <p>This option causes <b>xmlrpc</b> to default to using the Curl
 205 XML transport.  You may not specify any other transport.
 206
 207 <dt><b>-curlnoverifypeer</b>
 208
 209 <dd>
 210 This option gives the &quot;no_ssl_verifypeer&quot; option for the Curl
 211 XML transport, which is essentially the CURLOPT_SSL_VERIFYPEER option
 212 of the Curl library.
 213
 214 <p>See the <b>curl_easy_setopt()</b> man page for details on this, but
 215 essentially it means that the client does not authenticate the server's
 216 certificate of identity -- it just believes whatever the server says.
 217
 218 <p>You may want to use <b>-curlnoverifyhost</b> as well.  Since you're
 219 not authenticating the server's identity, there's not much sense in
 220 checking it.
 221
 222 <p>This option causes <b>xmlrpc</b> to default to using the Curl
 223 XML transport.  You may not specify any other transport.
 224
 225
 226 <dt><b>-curlnoverifyhost</b>
 227
 228 <dd>
 229 This option gives the &quot;no_ssl_verifyhost&quot; option for the Curl
 230 XML transport, which is essentially the CURLOPT_SSL_VERIFYHOST option
 231 of the Curl library.
 232
 233 <p>See the <b>curl_easy_setopt()</b> man page for details on this, but
 234 essentially it means that the client does not verify the server's
 235 identity.  It just assumes that if the server answers the IP address
 236 of the server as indicated by the URL (probably via host name), then
 237 it's the intended server.
 238
 239 <p>You may want to use <b>-curlnoverifypeer</b> as well.  As long as
 240 you don't care who the server says it is, there's no point in
 241 authenticating its identity.
 242
 243 <p>This option causes <b>xmlrpc</b> to default to using the Curl
 244 XML transport.  You may not specify any other transport.
 245
 246
 247 </dl>
 248
 249 </body>