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

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

• Что такое XML-RPC?
• Использование класса XML-RPC
  • Инициализация класса
  • Отправка запросов XML-RPC
    • Описание
  • Структура запроса
  • Создание сервера XML-RPC
  • Обработка запросов сервера
    • Примечания:
  • Форматирование ответа
  • Отправка ответа об ошибке
  • Создание собственного клиента и сервера
    • Клиент
    • Сервер
    • Попробуйте!
  • Использование ассоциативных массивов в параметре запроса
  • Типы данных
• Справочник по классам

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

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

Например, используя API MetaWeblog, клиент XML-RPC (обычно инструмент для настольного веб-публикования) отправляет запрос на сервер 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 используйте:

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

После загрузки объект библиотеки xml-rpcs будет доступен с помощью: $this->xmlrpcs

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

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

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

Вот пример, который отправляет простой ping 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() Security библиотеки.

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

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

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

class My_blog extends CI_Controller {

        public function new_post($request)
        {

        }
}

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

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

class My_blog extends CI_Controller {

        public function getUserInfo($request)
        {
                $username = 'smitty';
                $password = 'secretsmittypass';

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

                $parameters = $request->output_parameters();

                if ($parameters[1] != $username && $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'
);

Обратите внимание, что приведенный выше массив отформатирован как структура. Это наиболее распространённый тип данных для ответов.

Как и запросы, ответ может быть одним из семи типов данных, перечисленных в разделе Типы данных.

Отправка ответа об ошибке

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

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

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

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

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

Клиент

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

<?php

class Xmlrpc_client extends CI_Controller {

        public function index()
        {
                $this->load->helper('url');
                $server_url = site_url('xmlrpc_server');

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

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

                $request = array('How is it going?');
                $this->xmlrpc->request($request);

                if ( ! $this->xmlrpc->send_request())
                {
                        echo $this->xmlrpc->display_error();
                }
                else
                {
                        echo '<pre>';
                        print_r($this->xmlrpc->display_response());
                        echo '</pre>';
                }
        }
}
?>

Сервер

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

<?php

class Xmlrpc_server extends CI_Controller {

        public function index()
        {
                $this->load->library('xmlrpc');
                $this->load->library('xmlrpcs');

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

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


        public function process($request)
        {
                $parameters = $request->output_parameters();

                $response = array(
                        array(
                                'you_said'  => $parameters[0],
                                'i_respond' => 'Not bad at all.'
                        ),
                        'struct'
                );

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

Попробуйте!

Теперь посетите ваш сайт с помощью URL, подобного этому:

example.com/index.php/xmlrpc_client/

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

Созданный вами клиент отправляет сообщение («Как дела?») на сервер вместе с запросом на метод «Greetings». Сервер получает запрос и сопоставляет его с методом process(), где отправляется ответ.

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

Если вы хотите использовать ассоциативный массив в параметрах своего метода, вам необходимо использовать тип данных struct:

$request = array(
        array(
                // Param 0
                array('name' => 'John'),
                'struct'
        ),
        array(
                // Param 1
                array(
                        'size' => 'large',
                        'shape'=>'round'
                ),
                'struct'
        )
);

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

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

$parameters = $request->output_parameters();
$name = $parameters[0]['name'];
$size = $parameters[1]['size'];
$shape = $parameters[1]['shape'];

Типы данных

Согласно спецификации XML-RPC, существует семь типов значений, которые можно отправлять через XML-RPC:

• int или i4
• boolean
• string
• double
• dateTime.iso8601
• base64
• struct (содержит массив значений)
• array (содержит массив значений)

Справочник по классам

class CI_Xmlrpc

initialize([$config = array()])

Параметры:	$config (array) – Данные конфигурации
Тип возвращаемого значения:	void

Инициализирует библиотеку XML-RPC. Принимает ассоциативный массив, содержащий ваши настройки.

server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]])

Параметры:	$url (string) – URL сервера XML-RPC $port (int) – Порт сервера $proxy (string) – Необязательный прокси-сервер $proxy_port (int) – Порт прокси-сервера
Тип возвращаемого значения:	void

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

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

Поддержка базовой аутентификации HTTP также поддерживается, просто добавьте ее в URL сервера:

$this->xmlrpc->server('http://user:pass@localhost/', 80);

timeout($seconds = 5)

Параметры:	$seconds (int) – Время ожидания в секундах
Тип возвращаемого значения:	void

Устанавливает время ожидания (в секундах), после которого запрос будет отменен:

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

Это время ожидания будет использоваться как для первоначального подключения к удаленному серверу, так и для получения ответа от него. Убедитесь, что вы установили время ожидания до вызова send_request().

method($function)

Параметры:	$function (string) – Имя метода
Тип возвращаемого значения:	void

Устанавливает метод, который будет запрошен у сервера XML-RPC:

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

Где метод – это имя метода.

request($incoming)

Параметры:	$incoming (array) – Данные запроса
Тип возвращаемого значения:	void

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

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

send_request()

Возвращаемое значение:	ИСТИНА при успехе, ЛОЖЬ при ошибке
Тип возвращаемого значения:	bool

Метод отправки запроса. Возвращает логическое значение ИСТИНА или ЛОЖЬ в зависимости от успеха или неудачи, позволяя использовать его условно.

display_error()

Возвращаемое значение:	Строка сообщения об ошибке
Тип возвращаемого значения:	string

Возвращает строку сообщения об ошибке, если запрос завершился неудачей по какой-либо причине.

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

display_response()

Возвращаемое значение:	Ответ
Тип возвращаемого значения:	mixed

Возвращает ответ с удаленного сервера после получения запроса. Ответ обычно будет ассоциативным массивом.

$this->xmlrpc->display_response();

send_error_message($number, $message)

Параметры:	$number (int) – Номер ошибки $message (string) – Сообщение об ошибке
Возвращаемое значение:	Экземпляр XML_RPC_Response
Тип возвращаемого значения:	XML_RPC_Response

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

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