From b0dd10f8171945e0c1f3527dd1e9d18b043e01a7 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 25 Aug 2006 17:25:49 +0000 Subject: Initial Import --- user_guide/libraries/xmlrpc.html | 485 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 485 insertions(+) create mode 100644 user_guide/libraries/xmlrpc.html (limited to 'user_guide/libraries/xmlrpc.html') diff --git a/user_guide/libraries/xmlrpc.html b/user_guide/libraries/xmlrpc.html new file mode 100644 index 000000000..f8ef59951 --- /dev/null +++ b/user_guide/libraries/xmlrpc.html @@ -0,0 +1,485 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +

Code Igniter User Guide Version 1.4.0

+
+ + + + + + + + + +
+ + +
+ + + +
+ + +

XML-RPC and XML-RPC Server Classes

+ + +

Code Igniter's XML-RPC classes permit you to send requests to another server, or set up +your own XML-RPC server to receive requests.

+ + +

What is XML-RPC?

+ +

Quite simply it is a way for two computers to communicate over the internet using XML. +One computer, which we will call the client, sends an XML-RPC request to +another computer, which we will call the server. Once the server receives and processes the request it +will send back a response to the client.

+ +

For example, using the MetaWeblog API, an XML-RPC Client (usually a desktop publishing tool) will +send a request to an XML-RPC Server running on your site. This request might be a new weblog entry +being sent for publication, or it could be a request for an existing entry for editing. + +When the XML-RPC Server receives this request it will examine it to determine which class/method should be called to process the request. +Once processed, the server will then send back a response message.

+ +

For detailed spcifications, you can visit the XML-RPC site.

+ +

Initializing the Class

+ +

Like most other classes in Code Igniter, the XML-RPC and XML-RPCS classes are initialized in your controller using the $this->load->library function:

+ +

To load the XML-RPC class you will use: +$this->load->library('xmlrpc'); +

Once loaded, the xml-rpc library object will be available using: $this->xmlrpc

+ +

To load the XML-RPC Server class you will use: +$this->load->library('xmlrpcs'); +

Once loaded, the xml-rpcs library object will be available using: $this->xmlrpcs

+ + + +

Sending XML-RPC Requests

+ +

To send a request to an XML-RPC server you must specify the following information:

+ + + +

Here is a basic example that sends a simple Weblogs.com ping to the Ping-o-Matic

+ + +$this->load->library('xmlrpc');
+
+$this->xmlrpc->server('http://rpc.pingomatic.com/', 80);
+$this->xmlrpc->method('weblogUpdates.ping');
+ +
+$request = array('My Photoblog', 'http://www.my-site.com/photoblog/');
+$this->xmlrpc->request($request);
+
+if ( ! $this->xmlrpc->send_request())
+{
+    echo $xmlrpc->display_error();
+} + + +

Explanation

+ +

The above code initializes the XML-RPC class, sets the server URL and method to be called (weblogUpdates.ping). The +request (in this case, the title and URL of your site) is placed into an array for transportation, and +compiled using the request() function. +Lastly, the full request is sent. If the send_request() method returns false we will display the error message +sent back from the XML-RPC Server.

+ +

Anatomy of a Request

+ +

An XML-RPC request is simply the data you are sending to the XML-RPC server. Each piece of data in a request +is referred to as a request parameter. The above example has two parameters: +The URL and title of your site. When the XML-RPC server receives your request, it will look for parameters it requires.

+ +

Request parameters must be placed into an array for transportation, and each parameter can can be one +of seven data types (strings, numbers, dates, etc.). If your parameters are something other than strings +you will have to include the data type in the request array.

+ +

Here is an example of a simple array with three parameters:

+ +$request = array('John', 'Doe', 'www.some-site.com');
+$this->xmlrpc->request($request); + +

If you use data types other than strings, or if you have several different data types, you will place +each parameter into its own array, with the data type in the second position:

+ + +$request = array (
+                   array('John', 'string'),
+                   array('Doe', 'string'),
+                   array(FALSE, 'boolean'),
+                   array(12345, 'int')
+                 ); +
+$this->xmlrpc->request($request); + +The Data Types section below has a full list of data types.

+ + + +

Creating an XML-RPC Server

+ +

An XML-RPC Server acts as a traffic cop of sorts, waiting for incoming requests and redirecting them to the +appropriate functions for processing.

+ +

To create your own XML-RPC server involves initializing the XML-RPC Server class in your controller where you expect the incoming +request to appear, then setting up an array with mapping instructions so that incoming requests can be sent to the appropriate +class and method for processing.

+ +

Here is an example to illustrate:

+ +$this->load->library('xmlrpcs');
+
+$config['functions']['new_post'];  = array('function' => 'My_blog.new_entry');
+$config['functions']['update_post'] = array('function' => 'My_blog.update_entry');
+
+$this->xmlrpcs->initialize($config);
+$this->xmlrpcs->serve(); + +

The above example contains an array specifying two method requests that the Server allows. +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. + +

In other words, if an XML-RPC Client sends a request for the new_post method, your +server will load the My_blog class and call the new_entry function. +If the request is for the update_post method, your +server will load the My_blog class and call the update_entry function.

+ +

The function names in the above example are arbitrary. You'll decide what they should be called on your server, +or if you are using standardized APIs, like the Blogger or MetaWeblog API, you'll use their function names.

+ + +

Processing Server Requests

+ +

When the XML-RPC Server receives a request and loads the class/method for processing, it will pass +an object to that method containing the data sent by the client.

+ +

Using the above example, if the new_post method is requested, the server will expect a class +to exist with this prototype:

+ +class My_blog extends Controller {
+
+    function new_post($request)
+    {
+
+    }
+} + + +

The $request variable is an object compiled by the Server, which contains the data sent by the XML-RPC Client. +Using this object you will have access to the request parameters enabling you to process the request. When +you are done you will send a Response back to the Client.

+ +

Below is a real-world example, using the Blogger API. One of the methods in the Blogger API is getUserInfo(). +Using this method, an XML-RPC Client can send the Server a username and password, in return the Server sends +back information about that particular user (nickname, user ID, email address, etc.). Here is how the processing +function might look:

+ + +class My_blog extends Controller {
+
+    function getUserInfo($request)
+    {
+ +        $username = 'smitty';
+        $password = 'secretsmittypass';

+ +        $this->load->library('xmlrpc');
+    
+        $parameters = $request->output_parameters();
+    
+        if ($parameters['1'] != $username AND $parameters['2'] != $password)
+        {
+            return $this->xmlrpc->send_error_message('100', 'Invalid Access');
+        }
+    
+        $response = array(array('nickname'  => array('Smitty','string'),
+                                'userid'    => array('99','string'),
+                                'url'       => array('http://yoursite.com','string'),
+                                'email'     => array('jsmith@yoursite.com','string'),
+                                'lastname'  => array('Smith','string'),
+                                'firstname' => array('John','string')
+                                ),
+                         'struct');
+
+        $this->xmlrpc->send_response($response);
+    }
+} + + +

Notes:

+

The output_parameters() function retrieves an indexed array corresponding to the request parameters sent by the client. +In the above example, the output parameters will be the username and password.

+ +

If the username and password sent by the client were not valid, and error message is returned using send_error_message().

+ +

If the operation was successful, the client will be sent back a response array containing the user's info.

+ + +

Formatting a Response

+ +

Similar to Requests, Responses must be formatted as an array. However, unlike requests, a response is an array +that contains a single item. This item can be an array with several additional arrays, but there +can be only one primary array index. In other words, the basic prototype is this:

+ +$request = array('Response data', 'array'); + +

Responses, however, usually contain multiple pieces of information. In order to accomplish this we must put the response into its own +array so that the primary array continues to contain a single piece of data. Here's an example showing how this might be accomplished:

+ + +$request = array (
+                   array(
+                         'first_name' => array('John', 'string'),
+                         'last_name' => array('Doe', 'string'),
+                         'member_id' => array(123435, 'int'),
+                         'todo_list' => array(array('clean house', 'call mom', 'water plants'), 'array'),
+                        ),
+                 'struct'
+                 ); + + +

Notice that the above array is formatted as a struct. This is the most common data type for responses.

+ +

As with Requests, a response can be on of the seven data types listed in the Data Types section.

+ + +

Sending an Error Response

+ +

If you need to send the client an error response you will use the following:

+ +return $this->xmlrpc->send_error_message('123', 'Requested data not available'); + +

The first parameter is the error number while the second parameter is the error message.

+ + + + + + +

Creating Your Own Client and Server

+ +

To help you understand everything we've covered thus far, let's create a couple controllers that act as +XML-RPC Client and Server. You'll use the Client to send a request to the Server and receive a response.

+ +

The Client

+ +

Using a text editor, create a controller called xmlrpc_client.php. +In it, place this code and save it to your applications/controllers/ folder:

+ + + +

Note: In the above code we are using a "url helper". You can find more information in the Helpers Functions page.

+ +

The Server

+ +

Using a text editor, create a controller called xmlrpc_server.php. +In it, place this code and save it to your applications/controllers/ folder:

+ + + +

Try it!

+ +

Now visit the your site using a URL similar to this:

+www.your-site.com/index.php/xmlrpc_client/ + +

You should now see the message you sent to the server, and its response back to you.

+ +

The client you created sends a message ("How's is going?") to the server, along with a reqest for the "Greetings" method. +The Server receives the request and maps it to the "process" function, where a response is sent back.

+ + + +

 

+

XML-RPC Function Reference

+ +

$this->xmlrpc->server()

+

Sets the URL and port number of the server to which a request is to be sent:

+$this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); + +

$this->xmlrpc->timeout()

+

Set a time out period (in seconds) after which the request will be canceled:

+$this->xmlrpc->timeout(6); + +

$this->xmlrpc->method()

+

Sets the method that will be requested from the XML-RPC server:

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

Where method is the name of the method.

+ +

$this->xmlrpc->request()

+

Takes an array of data and builds request to be sent to XML-RPC server:

+$request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/');
+$this->xmlrpc->request($request); + +

$this->xmlrpc->send_request()

+

The request sending function. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally.

+ +

$this->xmlrpc->set_debug(TRUE);

+

Enables debugging, which will display a variety of information and error data helpful during development.

+ + +

$this->xmlrpc->display_error()

+

Returns an error message as a string if your request failed for some reason.

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

$this->xmlrpc->display_response()

+

Returns the response from the remote server once request is received. The response will typically be an associative array.

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

$this->xmlrpc->send_error_message()

+

This function lets you send an error message from your server to the client. First parameter is the error number while the second parameter +is the error message.

+return $this->xmlrpc->send_error_message('123', 'Requested data not available'); + +

$this->xmlrpc->send_response()

+

Lets you send the response from your server to the client. An array of of valid data values must be sent with this method.

+$response = array(
+                 array(
+                        'flerror' => array(FALSE, 'boolean'),
+                        'message' => "Thanks for the ping!")
+                     )
+                 'struct');
+return $this->xmlrpc->send_response($response); + + + +

Data Types

+ +

According to the XML-RPC spec there are seven types +of values that you can send via XML-RPC:

+ + + + +
+ + + + + + + \ No newline at end of file -- cgit v1.2.3-24-g4f1b