user_guide/libraries/xmlrpc.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3 <head>
   4
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <title>XML-RPC and XML-RPC Server Classes : CodeIgniter User Guide</title>
   7
   8 <style type='text/css' media='all'>@import url('../userguide.css');</style>
   9 <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
  10
  11 <script type="text/javascript" src="../nav/nav.js"></script>
  12 <script type="text/javascript" src="../nav/prototype.lite.js"></script>
  13 <script type="text/javascript" src="../nav/moo.fx.js"></script>
  14 <script type="text/javascript" src="../nav/user_guide_menu.js"></script>
  15
  16 <meta http-equiv='expires' content='-1' />
  17 <meta http-equiv= 'pragma' content='no-cache' />
  18 <meta name='robots' content='all' />
  19 <meta name='author' content='ExpressionEngine Dev Team' />
  20 <meta name='description' content='CodeIgniter User Guide' />
  21
  22 </head>
  23 <body>
  24
  25 <!-- START NAVIGATION -->
  26 <div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
  27 <div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
  28 <div id="masthead">
  29 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  30 <tr>
  31 <td><h1>CodeIgniter User Guide Version 2.0.2</h1></td>
  32 <td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
  33 </tr>
  34 </table>
  35 </div>
  36 <!-- END NAVIGATION -->
  37
  38
  39 <!-- START BREADCRUMB -->
  40 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  41 <tr>
  42 <td id="breadcrumb">
  43 <a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
  44 <a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
  45 XML-RPC and XML-RPC Server Classes
  46 </td>
  47 <td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
  48 </tr>
  49 </table>
  50 <!-- END BREADCRUMB -->
  51
  52 <br clear="all" />
  53
  54
  55 <!-- START CONTENT -->
  56 <div id="content">
  57
  58
  59 <h1>XML-RPC and XML-RPC Server Classes</h1>
  60
  61
  62 <p>CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up
  63 your own XML-RPC server to receive requests.</p>
  64
  65
  66 <h2>What is XML-RPC?</h2>
  67
  68 <p>Quite simply it is a way for two computers to communicate over the internet using XML.
  69 One computer, which we will call the <dfn>client</dfn>, sends an XML-RPC <strong>request</strong> to
  70 another computer, which we will call the <dfn>server</dfn>.  Once the server receives and processes the request it
  71 will send back a <strong>response</strong> to the client.</p>
  72
  73 <p>For example, using the MetaWeblog API, an XML-RPC Client (usually a desktop publishing tool) will
  74 send a request to an XML-RPC Server running on your site.  This request might be a new weblog entry
  75 being sent for publication, or it could be a request for an existing entry for editing.
  76
  77 When the XML-RPC Server receives this request it will examine it to determine which class/method should be called to process the request.
  78 Once processed, the server will then send back a response message.</p>
  79
  80 <p>For detailed specifications, you can visit the <a href="http://www.xmlrpc.com/">XML-RPC</a> site.</p>
  81
  82 <h2>Initializing the Class</h2>
  83
  84 <p>Like most other classes in CodeIgniter, the XML-RPC and XML-RPCS classes are initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
  85
  86 <p>To load the XML-RPC class you will use:</p>
  87 <code>$this->load->library('xmlrpc');</code>
  88 <p>Once loaded, the xml-rpc library object will be available using: <dfn>$this->xmlrpc</dfn></p>
  89
  90 <p>To load the XML-RPC Server class you will use:</p>
  91 <code>
  92 $this->load->library('xmlrpc');<br />
  93 $this->load->library('xmlrpcs');
  94 </code>
  95 <p>Once loaded, the xml-rpcs library object will be available using: <dfn>$this->xmlrpcs</dfn></p>
  96
  97 <p class="important"><strong>Note:</strong>&nbsp; When using the XML-RPC Server class you must load BOTH the XML-RPC class and the XML-RPC Server class.</p>
  98
  99
 100
 101 <h2>Sending XML-RPC Requests</h2>
 102
 103 <p>To send a request to an XML-RPC server you must specify the following information:</p>
 104
 105 <ul>
 106 <li>The URL of the server</li>
 107 <li>The method on the server you wish to call</li>
 108 <li>The <em>request</em> data (explained below).</li>
 109 </ul>
 110
 111 <p>Here is a basic example that sends a simple Weblogs.com ping to the <a href="http://pingomatic.com/">Ping-o-Matic</a></p>
 112
 113
 114 <code>$this->load->library('xmlrpc');<br />
 115 <br />
 116 $this->xmlrpc->server('http://rpc.pingomatic.com/', 80);<br />
 117 $this->xmlrpc->method('weblogUpdates.ping');<br />
 118
 119 <br />
 120 $request = array('My Photoblog', 'http://www.my-site.com/photoblog/');<br />
 121 $this->xmlrpc->request($request);<br />
 122 <br />
 123 if ( ! $this->xmlrpc->send_request())<br />
 124 {<br />
 125 &nbsp;&nbsp;&nbsp;&nbsp;echo $this-&gt;xmlrpc->display_error();<br />
 126 }</code>
 127
 128 <h3>Explanation</h3>
 129
 130 <p>The above code initializes the XML-RPC class, sets the server URL and method to be called (weblogUpdates.ping).  The
 131 request (in this case, the title and URL of your site) is placed into an array for transportation, and
 132 compiled using the request() function.
 133 Lastly, the full request is sent.  If the <dfn>send_request()</dfn> method returns false we will display the error message
 134 sent back from the XML-RPC Server.</p>
 135
 136 <h2>Anatomy of a Request</h2>
 137
 138 <p>An XML-RPC <dfn>request</dfn> is simply the data you are sending to the XML-RPC server.  Each piece of data in a request
 139 is referred to as a <dfn>request parameter</dfn>.  The above example has two parameters:
 140 The URL and title of your site. When the XML-RPC server receives your request, it will look for parameters it requires.</p>
 141
 142 <p>Request parameters must be placed into an array for transportation, and each parameter can be one
 143 of seven data types (strings, numbers, dates, etc.). If your parameters are something other than strings
 144 you will have to include the data type in the request array.</p>
 145
 146 <p>Here is an example of a simple array with three parameters:</p>
 147
 148 <code>$request = array('John', 'Doe', 'www.some-site.com');<br />
 149 $this->xmlrpc->request($request);</code>
 150
 151 <p>If you use data types other than strings, or if you have several different data types, you will place
 152 each parameter into its own array, with the data type in the second position:</p>
 153
 154 <code>
 155 $request = array (<br />
 156 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array('John', 'string'),<br />
 157 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array('Doe', 'string'),<br />
 158 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(FALSE, 'boolean'),<br />
 159 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(12345, 'int')<br />
 160 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);
 161 <br />
 162 $this->xmlrpc->request($request);</code>
 163
 164 The  <a href="#datatypes">Data Types</a>  section below has a full list of data types.
 165
 166
 167
 168 <h2>Creating an XML-RPC Server</h2>
 169
 170 <p>An XML-RPC Server acts as a traffic cop of sorts, waiting for incoming requests and redirecting them to the
 171 appropriate functions for processing.</p>
 172
 173 <p>To create your own XML-RPC server involves initializing the XML-RPC Server class in your controller where you expect the incoming
 174 request to appear, then setting up an array with mapping instructions so that incoming requests can be sent to the appropriate
 175 class and method for processing.</p>
 176
 177 <p>Here is an example to illustrate:</p>
 178
 179 <code>
 180 $this->load->library('xmlrpc');<br />
 181 $this->load->library('xmlrpcs');<br />
 182 <br />
 183 $config['functions']['<var>new_post</var>'] = array('function' => '<dfn>My_blog.new_entry</dfn>'),<br />
 184 $config['functions']['<var>update_post</var>'] = array('function' => '<dfn>My_blog.update_entry</dfn>');<br />
 185 $config['object'] = $this;<br />
 186 <br />
 187 $this->xmlrpcs->initialize($config);<br />
 188 $this->xmlrpcs->serve();</code>
 189
 190 <p>The above example contains an array specifying two method requests that the Server allows.
 191 The allowed methods are on the left side of the array. When either of those are received, they will be mapped to the class and method on the right.</p>
 192
 193 <p>The '<var>object</var>' key is a special key that you pass an instantiated class object with, which is necessary when the method you are mapping to is not
 194         part of the CodeIgniter super object.</p>
 195
 196 <p>In other words, if an XML-RPC Client sends a request for the <var>new_post</var> method, your
 197 server will load the <dfn>My_blog</dfn> class and call the <dfn>new_entry</dfn> function.
 198 If the request is for the <var>update_post</var> method, your
 199 server will load the <dfn>My_blog</dfn> class and call the <dfn>update_entry</dfn> function.</p>
 200
 201 <p>The function names in the above example are arbitrary.  You'll decide what they should be called on your server,
 202 or if you are using standardized APIs, like the Blogger or MetaWeblog API, you'll use their function names.</p>
 203
 204 <p>There are two additional configuration keys you may make use of when initializing the server class: <var>debug</var> can be set to TRUE in order to enable debugging, and <var>xss_clean</var> may be set to FALSE to prevent sending data through the Security library's xss_clean function.
 205
 206 <h2>Processing Server Requests</h2>
 207
 208 <p>When the XML-RPC Server receives a request and loads the class/method for processing, it will pass
 209 an object to that method containing the data sent by the client.</p>
 210
 211 <p>Using the above example, if the <var>new_post</var> method is requested, the server will expect a class
 212 to exist with this prototype:</p>
 213
 214 <code>class <kbd>My_blog</kbd> extends CI_Controller {<br />
 215 <br />
 216 &nbsp;&nbsp;&nbsp;&nbsp;function <kbd>new_post</kbd>(<var>$request</var>)<br />
 217 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
 218         <br />
 219 &nbsp;&nbsp;&nbsp;&nbsp;}<br />
 220 }
 221 </code>
 222
 223 <p>The <var>$request</var> variable is an object compiled by the Server, which contains the data sent by the XML-RPC Client.
 224 Using this object you will have access to the <em>request parameters</em> enabling you to process the request.  When
 225 you are done you will send a <dfn>Response</dfn> back to the Client.</p>
 226
 227 <p>Below is a real-world example, using the Blogger API.  One of the methods in the Blogger API is <dfn>getUserInfo()</dfn>.
 228 Using this method, an XML-RPC Client can send the Server a username and password, in return the Server sends
 229 back information about that particular user (nickname, user ID, email address, etc.).  Here is how the processing
 230 function might look:</p>
 231
 232
 233 <code>class <kbd>My_blog</kbd> extends CI_Controller {<br />
 234 <br />
 235 &nbsp;&nbsp;&nbsp;&nbsp;function <kbd>getUserInfo</kbd>(<var>$request</var>)<br />
 236 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
 237
 238 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$username = 'smitty';<br />
 239 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$password = 'secretsmittypass';<br /><br />
 240
 241 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->load->library('xmlrpc');<br />
 242 &nbsp;&nbsp;&nbsp;&nbsp;<br />
 243 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$parameters&nbsp;=&nbsp;$request->output_parameters();<br />
 244 &nbsp;&nbsp;&nbsp;&nbsp;<br />
 245 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;($parameters['1'] != $username AND $parameters['2'] != $password)<br />
 246 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<br />
 247 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;$this->xmlrpc->send_error_message('100',&nbsp;'Invalid&nbsp;Access');<br />
 248 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br />
 249 &nbsp;&nbsp;&nbsp;&nbsp;<br />
 250 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$response&nbsp;=&nbsp;array(array('nickname'&nbsp;&nbsp;=>&nbsp;array('Smitty','string'),<br />
 251 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'userid'&nbsp;&nbsp;&nbsp;&nbsp;=>&nbsp;array('99','string'),<br />
 252 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'url'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=>&nbsp;array('http://yoursite.com','string'),<br />
 253 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'email'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=>&nbsp;array('jsmith@yoursite.com','string'),<br />
 254 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'lastname'&nbsp;&nbsp;=>&nbsp;array('Smith','string'),<br />
 255 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'firstname'&nbsp;=>&nbsp;array('John','string')<br />
 256 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),<br />
 257 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'struct');<br />
 258 <br />
 259 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return $this->xmlrpc->send_response($response);<br />
 260 &nbsp;&nbsp;&nbsp;&nbsp;}<br />
 261 }
 262 </code>
 263
 264 <h3>Notes:</h3>
 265 <p>The <dfn>output_parameters()</dfn> function retrieves an indexed array corresponding to the request parameters sent by the client.
 266 In the above example, the output parameters will be the username and password.</p>
 267
 268 <p>If the username and password sent by the client were not valid, and error message is returned using <dfn>send_error_message()</dfn>.</p>
 269
 270 <p>If the operation was successful, the client will be sent back a response array containing the user's info.</p>
 271
 272
 273 <h2>Formatting a Response</h2>
 274
 275 <p>Similar to <em>Requests</em>, <em>Responses</em> must be formatted as an array.  However, unlike requests, a response is an array
 276 <strong>that contains a single item</strong>.  This item can be an array with several additional arrays, but there
 277 can be only one primary array index.  In other words, the basic prototype is this:</p>
 278
 279 <code>$response = array('Response data',  'array');</code>
 280
 281 <p>Responses, however, usually contain multiple pieces of information. In order to accomplish this we must put the response into its own
 282 array so that the primary array continues to contain a single piece of data.  Here's an example showing how this might be accomplished:</p>
 283
 284 <code>
 285 $response = array (<br />
 286 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 287 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'first_name' => array('John', 'string'),<br />
 288 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_name' => array('Doe', 'string'),<br />
 289 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'member_id' => array(123435, 'int'),<br />
 290 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'todo_list' => array(array('clean house', 'call mom', 'water plants'), 'array'),<br />
 291 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),<br />
 292 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'struct'<br />
 293 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);
 294 </code>
 295
 296 <p class="important">Notice that the above array is formatted as a <dfn>struct</dfn>.  This is the most common data type for responses.</p>
 297
 298 <p>As with Requests, a response can be one of the seven data types listed in the  <a href="#datatypes">Data Types</a>  section.</p>
 299
 300
 301 <h2>Sending an Error Response</h2>
 302
 303 <p>If you need to send the client an error response you will use the following:</p>
 304
 305 <code>return $this->xmlrpc->send_error_message('123', 'Requested data not available');</code>
 306
 307 <p>The first parameter is the error number while the second parameter is the error message.</p>
 308
 309
 310
 311
 312
 313
 314 <h2>Creating Your Own Client and Server</h2>
 315
 316 <p>To help you understand everything we've covered thus far, let's create a couple controllers that act as
 317 XML-RPC Client and Server.  You'll use the Client to send a request to the Server and receive a response.</p>
 318
 319 <h3>The Client</h3>
 320
 321 <p>Using a text editor, create a controller called <dfn>xmlrpc_client.php</dfn>.
 322 In it, place this code and save it to your <samp>applications/controllers/</samp> folder:</p>
 323
 324 <textarea class="textarea" style="width:100%" cols="50" rows="32">&lt;?php
 325
 326 class Xmlrpc_client extends CI_Controller {
 327
 328         function index()
 329         {
 330                 $this->load->helper('url');
 331                 $server_url = site_url('xmlrpc_server');
 332
 333                 $this->load->library('xmlrpc');
 334
 335                 $this->xmlrpc->server($server_url, 80);
 336                 $this->xmlrpc->method('Greetings');
 337
 338                 $request = array('How is it going?');
 339                 $this->xmlrpc->request($request);
 340
 341                 if ( ! $this->xmlrpc->send_request())
 342                 {
 343                         echo $this->xmlrpc->display_error();
 344                 }
 345                 else
 346                 {
 347                         echo '<pre>';
 348                         print_r($this->xmlrpc->display_response());
 349                         echo '</pre>';
 350                 }
 351         }
 352 }
 353 ?></textarea>
 354
 355 <p>Note: In the above code we are using a "url helper".  You can find more information in the <a href="../general/helpers.html">Helpers Functions</a> page.</p>
 356
 357 <h3>The Server</h3>
 358
 359 <p>Using a text editor, create a controller called <dfn>xmlrpc_server.php</dfn>.
 360 In it, place this code and save it to your <samp>applications/controllers/</samp> folder:</p>
 361
 362 <textarea class="textarea" style="width:100%" cols="50" rows="30">&lt;?php
 363
 364 class Xmlrpc_server extends CI_Controller {
 365
 366         function index()
 367         {
 368                 $this->load->library('xmlrpc');
 369                 $this->load->library('xmlrpcs');
 370
 371                 $config['functions']['Greetings'] = array('function' => 'Xmlrpc_server.process');
 372
 373                 $this->xmlrpcs->initialize($config);
 374                 $this->xmlrpcs->serve();
 375         }
 376
 377
 378         function process($request)
 379         {
 380                 $parameters = $request->output_parameters();
 381
 382                 $response = array(
 383                                                         array(
 384                                                                         'you_said'  => $parameters['0'],
 385                                                                         'i_respond' => 'Not bad at all.'),
 386                                                         'struct');
 387
 388                 return $this->xmlrpc->send_response($response);
 389         }
 390 }
 391 ?></textarea>
 392
 393 <h3>Try it!</h3>
 394
 395 <p>Now visit the your site using a URL similar to this:</p>
 396 <code>example.com/index.php/<var>xmlrpc_client</var>/</code>
 397
 398 <p>You should now see the message you sent to the server, and its response back to you.</p>
 399
 400 <p>The client you created sends a message ("How's is going?") to the server, along with a request for the "Greetings" method.
 401 The Server receives the request and maps it to the "process" function, where a response is sent back.</p>
 402
 403 <h2>Using Associative Arrays In a Request Parameter</h2>
 404
 405 <p>If you wish to use an associative array in your method parameters you will need to use a struct datatype:</p>
 406
 407 <code>$request = array(<br />
 408         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 409         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Param 0<br />
 410         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 411         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'name'=&gt;'John'<br />
 412         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        ),<br />
 413         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'struct'<br />
 414         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;),<br />
 415         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 416         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Param 1<br />
 417         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 418         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;    'size'=&gt;'large',<br />
 419         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'shape'=&gt;'round'<br />
 420         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;    ),<br />
 421         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'struct'<br />
 422         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)<br />
 423         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
 424         $this-&gt;xmlrpc-&gt;request($request);</code>
 425
 426 <p>You can retrieve the associative array when processing the request in the Server.</p>
 427
 428 <code>$parameters = $request-&gt;output_parameters();<br />
 429         $name = $parameters['0']['name'];<br />
 430         $size = $parameters['1']['size'];<br />
 431         $size = $parameters['1']['shape']; </code>
 432
 433 <h1>XML-RPC Function Reference</h1>
 434
 435 <h2>$this->xmlrpc->server()</h2>
 436 <p>Sets the URL and port number of the server to which a request is to be sent:</p>
 437 <code>$this->xmlrpc->server('http://www.sometimes.com/pings.php', 80);</code>
 438
 439 <h2>$this->xmlrpc->timeout()</h2>
 440 <p>Set a time out period (in seconds) after which the request will be canceled:</p>
 441 <code>$this->xmlrpc->timeout(6);</code>
 442
 443 <h2>$this->xmlrpc->method()</h2>
 444 <p>Sets the method that will be requested from the XML-RPC server:</p>
 445 <code>$this->xmlrpc->method('<var>method</var>');</code>
 446
 447 <p>Where <var>method</var> is the name of the method.</p>
 448
 449 <h2>$this->xmlrpc->request()</h2>
 450 <p>Takes an array of data and builds request to be sent to XML-RPC server:</p>
 451 <code>$request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/');<br />
 452 $this->xmlrpc->request($request);</code>
 453
 454 <h2>$this->xmlrpc->send_request()</h2>
 455 <p>The request sending function.  Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally.</p>
 456
 457 <h2>$this->xmlrpc->set_debug(TRUE);</h2>
 458 <p>Enables debugging, which will display a variety of information and error data helpful during development.</p>
 459
 460
 461 <h2>$this->xmlrpc->display_error()</h2>
 462 <p>Returns an error message as a string if your request failed for some reason.</p>
 463 <code>echo $this->xmlrpc->display_error();</code>
 464
 465 <h2>$this->xmlrpc->display_response()</h2>
 466 <p>Returns the response from the remote server once request is received.  The response will typically be an associative array.</p>
 467 <code>$this->xmlrpc->display_response();</code>
 468
 469 <h2>$this->xmlrpc->send_error_message()</h2>
 470 <p>This function lets you send an error message from your server to the client. First parameter is the error number while the second parameter
 471 is the error message.</p>
 472 <code>return $this->xmlrpc->send_error_message('123', 'Requested data not available');</code>
 473
 474 <h2>$this->xmlrpc->send_response()</h2>
 475 <p>Lets you send the response from your server to the client. An array of valid data values must be sent with this method.</p>
 476 <code>$response = array(<br />
 477 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;array(<br />
 478 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'flerror' => array(FALSE, 'boolean'),<br />
 479 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'message' => "Thanks for the ping!"<br />
 480 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)<br />
 481 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'struct');<br />
 482 return $this->xmlrpc->send_response($response);</code>
 483
 484
 485 <a name="datatypes"></a>
 486 <h2>Data Types</h2>
 487
 488 <p>According to the <a href="http://www.xmlrpc.com/spec">XML-RPC spec</a> there are seven types
 489 of values that you can send via XML-RPC:</p>
 490
 491 <ul>
 492 <li><em>int</em> or <em>i4</em></li>
 493 <li><em>boolean</em></li>
 494 <li><em>string</em></li>
 495 <li><em>double</em></li>
 496 <li><em>dateTime.iso8601</em></li>
 497 <li><em>base64</em></li>
 498 <li><em>struct</em> (contains array of values)</li>
 499 <li><em>array</em> (contains array of values)</li>
 500 </ul>
 501
 502
 503 </div>
 504 <!-- END CONTENT -->
 505
 506
 507 <div id="footer">
 508 <p>
 509 Previous Topic:&nbsp;&nbsp;<a href="user_agent.html">User Agent Class</a>
 510 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 511 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 512 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 513 Next Topic:&nbsp;&nbsp;<a href="zip.html">Zip Encoding Class</a>
 514 </p>
 515 <p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
 516 </div>
 517
 518 </body>
 519 </html>