Классы XML-RPC и XML-RPC Server

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

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

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

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

За детальными спецификациями вы можете посетить сайт XML-RPC.

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

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

Чтобы загрузить класс XML-RPC, используйте:

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

Загруженный объект класса XML-RPC доступен к использованию как $this->xmlrpc

Чтобы загрузить класс XML-RPC Server, используйте:


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

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

Загруженный объект класса XML-RPCs доступен к использованию как $this->xmlrpcs

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

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

Чтобы отправить запросы XML-RPC серверу, вы должны указать следующую информацию:

URL сервера
Метод сервера, который вы хотите вызвать
Данные запроса (разъяснены ниже).

Вот основной пример, как отправить простой пинг Weblogs.com к 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 $this->xmlrpc->display_error();

}

Объяснение

Код выше инициализирует класс XML-RPC, устанавливает серверный URL и метод, который будет вызван (weblogUpdates.ping). Запрос (в этом случае, заголовок и URL вашего сайта) размещаются в массиве для транспортировки, скомпилированного с использованием функции request(). Наконец, полный запрос отправлен. Если метод send_request() возвращает FALSE, мы отображаем сообщение об ошибке, возвращенное 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 Server в вашем контроллере, где вы ожидаете входящие запросы, потом установите массив с инструкциями, куда должен быть отправлен входящий запрос, в какой класс какому методу, для обработки.

Вот пример:


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

$config['object'] = $this;



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

$this->xmlrpcs->serve();

Пример выше содержит массив, который предусматривает два типа запросов, разрешенных Сервером. Разрешенные методы в левой части массива. Когда получен любой из них, они будут направлены в класс и метод, указанные справа.

Ключ 'object' это специальный ключ, который вы передаете экземпляру класса объекта при необходимости, когда метод, на который вы делаете направление, не является частью суперобъекта CodeIgniter.

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

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

Есть два дополнительных ключа конфигурации, которые вы можете использовать при инициализации серверного класса: debug может бысть установлен в TRUE, чтобы включить отладку, и xss_clean может быть установлено в FALSE, чтобы предотвратить отправку данных через функцию xss_clean библиотеки безопасности.

Обработка серверного запроса

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

Используя пример выше, если запрашивается метод new_post, сервер будет ожидать существующий класс, соответствующий этому прототипу:

class My_blog extends CI_Controller {



    function new_post($request)

    {

	

    }

}

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

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

class My_blog extends CI_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() получает индексированный массив, соответствующий параметрам запроса, отправленных клиентом. В примере выше, параметры вывода будут именем пользователя и паролем.

Если имя пользователя и пароль, отправленные клиентом, не правильные, будет возвращено сообщение об ошибке, используя 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. Вы можете найти больше информации о нем на странице Функции-помощники.

Сервер

Используя текстовый редактор, создайте контроллер, называемый xmlrpc_server.php. В него поместите этот код и сохраните его в вашей директории applications/controllers/:

Попробуйте!

Теперь посетите ваш сайт, используя URL соответствующий этому:

example.com/index.php/xmlrpc_client/

Вы должны увидеть сообщение, отправленное серверу, и его ответ.

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

Использование ассоциативных массивов в параметре запроса

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

$request = array(

	                 array(

	                       // Параметр 0

	                       array(

	                             'name'=>'John'

	                            	),

	                             'struct'

	                       ),

	                       array(

	                             // Параметр 1

	                             array(

	                                  	'size'=>'large',

	                                   'shape'=>'round'

	                                  	),

	                             'struct'

	                       )

	                 );

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

Вы можете получить ассоциативный массив при обработке запроса на сервере.

$parameters = $request->output_parameters();

	$name = $parameters['0']['name'];

	$size = $parameters['1']['size'];

	$size = $parameters['1']['shape'];

Справка по функциям XML-RPC

$this->xmlrpc->server()

Устанавливает URL и номер порта к серверу, который принимает запросы:

$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()

Эта фунция позволяет вам отправить сообщение об ошибке от вашего сервера клиенту. Первый параметр это номер ошибки, а второй параметр содержит текст сообщения об ошибке.