Blame - user_guide/libraries/xmlrpc.html - code-igniter-v3-giggi

2010-10-04 16:33:58 +0200

[diff] [blame]

195

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

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>

Robin Sowell

66a3fc0

2010-03-18 09:44:55 -0400

[diff] [blame]

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.

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

205

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

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

Greg Aker

2010-11-09 13:53:07 -0600

[diff] [blame]

214

<code>class <kbd>My_blog</kbd> extends CI_Controller {<br />

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

215

<br />

216

    function <kbd>new_post</kbd>(<var>$request</var>)<br />

    {<br />

<br />

    }<br />

}

</code>

<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

Greg Aker

2010-11-09 13:53:07 -0600

[diff] [blame]

233

<code>class <kbd>My_blog</kbd> extends CI_Controller {<br />

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

234

<br />

235

    function <kbd>getUserInfo</kbd>(<var>$request</var>)<br />

236

    {<br />

237

238

        $username = 'smitty';<br />

239

        $password = 'secretsmittypass';<br /><br />

240

241

        $this->load->library('xmlrpc');<br />

242

    <br />

243

        $parameters = $request->output_parameters();<br />

244

    <br />

245

        if ($parameters['1'] != $username AND $parameters['2'] != $password)<br />

246

        {<br />

247

            return $this->xmlrpc->send_error_message('100', 'Invalid Access');<br />

248

        }<br />

249

    <br />

250

        $response = array(array('nickname'  => array('Smitty','string'),<br />

251

                                'userid'    => array('99','string'),<br />

252

                                'url'       => array('http://yoursite.com','string'),<br />

253

                                'email'     => array('jsmith@yoursite.com','string'),<br />

254

                                'lastname'  => array('Smith','string'),<br />

255

                                'firstname' => array('John','string')<br />

256

                                ),<br />

257

                         'struct');<br />

258

<br />

259

        return $this->xmlrpc->send_response($response);<br />

    }<br />

}

</code>

<h3>Notes:</h3>

<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

                   array(<br />

287

                         'first_name' => array('John', 'string'),<br />

288

                         'last_name' => array('Doe', 'string'),<br />

289

                         'member_id' => array(123435, 'int'),<br />

290

                         'todo_list' => array(array('clean house', 'call mom', 'water plants'), 'array'),<br />

291

                        ),<br />

292

                 'struct'<br />

                 );

</code>

<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>

<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>

<h3>The Client</h3>

<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

Derek Allard

4b6d493

2008-12-07 17:04:56 +0000

[diff] [blame]

324

<textarea class="textarea" style="width:100%" cols="50" rows="32"><?php

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

325

Greg Aker

2010-11-09 13:53:07 -0600

[diff] [blame]

326

class Xmlrpc_client extends CI_Controller {

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

327

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

328

function index()

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

329

{

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

330

$this->load->helper('url');

331

$server_url = site_url('xmlrpc_server');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

332

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

333

$this->load->library('xmlrpc');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

334

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

335

$this->xmlrpc->server($server_url, 80);

336

$this->xmlrpc->method('Greetings');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

337

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

338

$request = array('How is it going?');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

339

$this->xmlrpc->request($request);

340

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

341

if ( ! $this->xmlrpc->send_request())

342

{

343

echo $this->xmlrpc->display_error();

}

else

{

echo '<pre>';

print_r($this->xmlrpc->display_response());

echo '</pre>';

}

}

}

?></textarea>

<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>

<h3>The Server</h3>

<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

Derek Allard

4b6d493

2008-12-07 17:04:56 +0000

[diff] [blame]

362

<textarea class="textarea" style="width:100%" cols="50" rows="30"><?php

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

363

Greg Aker

2010-11-09 13:53:07 -0600

[diff] [blame]

364

class Xmlrpc_server extends CI_Controller {

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

function index()

{

$this->load->library('xmlrpc');

369

$this->load->library('xmlrpcs');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

370

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

371

$config['functions']['Greetings'] = array('function' => 'Xmlrpc_server.process');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

372

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

373

$this->xmlrpcs->initialize($config);

374

$this->xmlrpcs->serve();

375

}

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

376

377

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

378

function process($request)

379

{

380

$parameters = $request->output_parameters();

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

381

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

382

$response = array(

383

array(

384

'you_said' => $parameters['0'],

385

'i_respond' => 'Not bad at all.'),

386

'struct');

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

387

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

388

return $this->xmlrpc->send_response($response);

}

}

?></textarea>

<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

                 array(<br />

409

                       // Param 0<br />

410

                       array(<br />

411

                             'name'=>'John'<br />

412

                             ),<br />

413

                             'struct'<br />

414

                       ),<br />

415

                       array(<br />

416

                             // Param 1<br />

417

                             array(<br />

418

                                   'size'=>'large',<br />

419

                                   'shape'=>'round'<br />

420

                                   ),<br />

421

                             'struct'<br />

422

                       )<br />

423

                 );<br />

424

$this->xmlrpc->request($request);</code>

Barry Mieny

2010-10-04 16:33:58 +0200

[diff] [blame]

425

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

426

<p>You can retrieve the associative array when processing the request in the Server.</p>

427

428

<code>$parameters = $request->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

                 array(<br />

478

                        'flerror' => array(FALSE, 'boolean'),<br />

Derek Jones

b705475

2010-03-30 08:49:37 -0500

[diff] [blame]

479

                        'message' => "Thanks for the ping!"<br />

Derek Allard

2008-11-13 22:59:24 +0000

[diff] [blame]

480

                     )<br />

481

                 'struct');<br />

482

return $this->xmlrpc->send_response($response);</code>

<h2>Data Types</h2>

<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>

<ul>

<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

498

<li><em>struct</em> (contains array of values)</li>

499

<li><em>array</em> (contains array of values)</li>

</ul>

</div>

<p>

Previous Topic:  <a href="user_agent.html">User Agent Class</a>

510

   ·  

511

<a href="#top">Top of Page</a>   ·  

512

<a href="../index.html">User Guide Home</a>   ·  

513

Next Topic:  <a href="zip.html">Zip Encoding Class</a>

514

</p>

Derek Jones

898949f

2011-01-28 07:42:16 -0600

[diff] [blame]

515

Derek Allard