CodeIgniter, руководство пользователя к версии 1.6.1

Классы XML-RPC и XML-RPC Сервер

Класс XML-RPC позволяет отправлять запросы на другие сервера или сделать собственный XML-RPC сервер для получения запросов.

Что такое XML-RPC?

Это технология, позволяющая устанавливать связь между двумя компьютерами с помощью языка XML. Один компьютер, называемый клиент, отправляет XML-RPC запросы на другой компьютер, называемый сервер. После этого сервер обрабатывает запрос и отправляет ответ клиенту.

К примеру, используя MetaWeblog API, XML-RPC клиент (обычно это пользовательское приложение) отправляет данные XML-RPC серверу, расположенному в Интернете. Запросом является обычно или новый пост блога, или отредактированная запись. Когда сервер XML-RPC получает данные, они обрабатываются, а пользователю - клиенту - отправляется ответ - результат обработки запроса

Для более полной спецификации посетите сайт XML-RPC.

Инициализация Класса

Как и многие классы, XML-RPC и XML-RPCS инициализируются с использованием функции $this->load->library:

Для загрузки XML-RPC клиента используется этот код:

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

А для загрузки XML-RPC сервера - этот:

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

Объект будет доступен по вызову $this->xmlrpc (клиент) и $this->xmlrpcs (сервер)

Важно:  При использовании XML-RPC сервера также необходимо загрузить и класс XML-RPC клиента.

Отправка XML-RPC запросов

Для отправки запросов XML-RPC серверу следует указать следующие данные:

Вот пример простой отправки данных на Weblogs.com с использованием Ping-o-Matic

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

$this->xmlrpc->server('http://rpc.pingomatic.com/', 80);
$this->xmlrpc->method('weblogUpdates.ping');

$request = array('Мой фотоблог', 'http://www.my-site.com/photoblog/');
$this->xmlrpc->request($request);

if ( ! $this->xmlrpc->send_request())
{
    echo $this->xmlrpc->display_error();
}

Объяснение

Приведенный код запускает XML-RPC класс, устанавливает URL сервера и метод (тут - weblogUpdates.ping). Запрос (в этом случае URL и заголовок сайта) размещается в массиве и подготавливается к передаче функцией request() . Затем готовый запрос посылается с помощью send_request(), и если произошла ошибка, то отображается ее текст, полученный с XML-RPC сервера.

Структура запроса

XML-RPC запрос это данные, посылаемые на XML-RPC сервер. Каждая часть данных является параметром запроса. Приведенный выше пример имел два параметра: URL и заголовок сайта. Когда XML-RPC получает запрос, он извлекает из него переданные параметры.

Все параметры должны находится в одном массиве, и каждый из параметров должен соответствовать определенному типу данных (строка, число и пр.).

Пример массива с тремя переменными :

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

Если типы данных разные, то следует поместить каждый параметр в субмассив и вторым индексом указывать их тип, например:

$request = array (
                   array('John', 'string'),
                   array('Doe', 'string'),
                   array(FALSE, 'boolean'),
                   array(12345, 'int')
                 );
$this->xmlrpc->request($request); Раздел Типы данных содержит полный список доступных типов.

Создание XML-RPC сервера

XML-RPC сервер включает в себя функции получения и обработки данных в соответствии с заданными методами.

Что бы создать XML-RPC сервер следует инициализировать класс XML-RPC сервера в контроллере, указать, что посылать в ответе клиенту и какие методы будут обрабатывать данные.

Пример, описывающий это:

$this->load->library('xmlrpc');
$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();

Приведенный пример загружает сервер и указывает, какими методами будут обрабатываться данные. Методы указываются в левой части выражения, а обрабатывающие их функции - в правой.

К примеру, XML-RPC отправляет запрос с использованием метода new_post, а сервер загружает класс My_blog и вызывает функцию new_entry Аналогично метод update_post указывает серверу использовать функцию update_entry класса My_blog.

Имена функций и методов приведены к примеру. Вы можете сами решить, разрабатывать новый способ обработки, или использовать уже готовые стандарты, такие как Blogger или MetaWeblog API.

Обработка запросов

Когда XML-RPC сервер получил данные и вызвал соответствующую методу функцию, следует обработать полученные данные и отправить ответ.

Продолжаем на основе приведенных выше примеров. Получив метод new_post , сервер загружает класс, оформленный подобным образом:

class My_blog extends Controller {

    function new_post($request)
    {

    }
}

Переменная $request является объектом с данными, принятыми от XML-RPC клиента. Используя этот объект, можно получить доступ к параметрам запроса . Когда запрос обработан, следует отправить ответ клиенту.

Рассмотрим реальный пример с использованием Blogger API. Один из методов Blogger API - getUserInfo(). Используя его, XML-RPC клиент отправляет серверу логин и пароль, и сервер возвращает данные об этом пользователе ( ник, ID, email адрес и пр.). Вот реализация этого способа:

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');

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

Примечания:

Функция output_parameters() возвращает индексированный массив с данными, полученными от клиента. В нашем примере это username (логин) и password (пароль).

Если логин и/или пароль не верные, сообщение об ошибке отправляется с помощью send_error_message().

Если все прошло успешно, то клиент в ответе получит массив с данными о пользователе

Формат ответа

Как и запрос, ответ должен быть оформлен в виде массива.. Но ответный массив должен содержать только одно значение . Это значение может быть массивом с субмассивами, но должно иметь только один индекс.. Иначе говоря, структура ответа должна быть такой:

$response = array('Response data', 'array');

Вот пример структуры готового ответа:

$response = 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'
                 );

Заметьте, что ответ имеет тип struct. Это наиболее предпочтительный тип для отправки ответов.

Как и массиве запроса, в ответе могут содержаться данные определенных типов .

Отправка сообщения об ошибке

Для отправки сообщения от ошибке используется следующий код :

return $this->xmlrpc->send_error_message('123', 'Запрашиваемые данные недоступны');

Первый параметр - код ошибки, второй - ее описание.

Создание собственного клиента и сервера

Для полного понимания данного раздела давайте создадим собственные XML-RPC клиент и сервер. вы можете использовать данный клиент для отправки запросов, а сервер - для из получения, анализа и ответов.

Клиент

Создадим контроллер xmlrpc_client.php и поместим его в директорию applications/controllers/ :

Примечание: приведенный код использует "url helper". Информация о нем доступна на странице Вспомогательных функций .

Сервер

Создадим контроллер с именем xmlrpc_server.php и сохраним его в папке applications/controllers/:

Пробуйте!

Теперь можете проверить работу, перейдя по ссылке, подобной этой:

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

Вы увидите отправленное сообщение серверу и полученный ответ.

Созданный клиент посылает сообщение ("How's is going?") серверу, использую метод "Greetings". Сервер обрабатывает его в функции "process" , где и формируется ответ.

 

Описание функций XML-RPC

$this->xmlrpc->server()

Устанавливает адрес и порт сервера для передачи запроса:

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

$this->xmlrpc->timeout()

Задает тайм-аут (в секундах) после которого запрос отменяется:

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

$this->xmlrpc->method()

Задает метод, которым будет обрабатывать запрос XML-RPC сервер:

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

Где method имя метода.

$this->xmlrpc->request()

Получает массив данных и создает запрос для отправки XML-RPC серверу:

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

$this->xmlrpc->send_request()

Отправка запроса. Возвращает TRUE или FALSE

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

Включение отладочного режима - отображение различной информации и сообщения об ошибках.

$this->xmlrpc->display_error()

Возвращает описание и номер ошибки, если она произошла .

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

$this->xmlrpc->display_response()

Возвращает ответ сервера в виде ассоциативного массива .

$this->xmlrpc->display_response();

$this->xmlrpc->send_error_message()

Функция отправляет сообщение об ошибке клиенту. Параметры: номер ошибки и ее описание:

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

$this->xmlrpc->send_response()

Отправляет ответ сервера клиенту. Параметр: массив с данными.

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

Типы данных

В соответствии с XML-RPC спецификацией предопределены семь типов данных, используемых при передаче XML-RPC: