Структура модулей

Все модули для работы с API Шаманграда можно условно разделить на три части:

  1. Базовые модули — содержат базовые определения для работы с АПИ.
  2. Транспортный уровень — модули, которые реализуют протокол общения с сервером.
  3. Прикладные модули — модули содержащие собственно определения RPC-функций.

Базовые модули

В базовом модуле (wsrpcbase) мало интересного для прикладного программиста кроме быть может определений базовых типов и класса исключения (EWSRPCFault): 

  EWSRPCFault = class (Exception)
    private
      FExceptionName: UTF8String;
      FMethodName: UTF8String;
    public
      constructor Create(const AMethodName, AExceptionName, AMessage: UTF8String);
      
      property ExceptionName: UTF8String read FExceptionName;
      property MethodName: UTF8String read FMethodName;
  end;

Транспортный уровень

На данный момент реализован один транспортный уровень (wsxmlrpc) реализующий протокол XML-RPC. В нём есть ряд свойств и методов важных для прикладного программиста. Их и рассмотрим.

  1. Конструктор Create(AGateURL: UTF8String);
    Создает экземпляр шлюза. В единственном параметре он принимает URL шлюза. Он поддерживает два протокола: HTTP и HTTPS. Последний использует защищенное соединение (все запросы, ответы и пароли шифруются перед передачей). В случае использования HTTP протокола, все данные и пароли передаются в открытом виде, поэтому рекомендуется использовать защищенное соединение.
    Для работы с Шаманградом нужно указать один из следующих URL:
    HTTP: http://shamangrad.net/rpc.php
    HTTPS: https://shamangrad.net/rpc.php
    Тестовый шлюз: http://dev.shamangrad.net/rpc.php
    Тестовый шлюз вы можете использовать для экспериментов с API, не боясь что-либо испортить на рабочем сервере. Так же в тестовом шлюзе тестируются новые функции, которые в последствии будут реализованы на рабочем сервере.
  2. Деструктор.
    В большинстве случаев нет никакой необходимости вызывать деструктор — шлюз удаляется автоматически, как только его счётчик ссылок становиться равным нулю, смотрите примеры.
  3. Авторизация authorize(const AUserName, AUserPass: AnsiString);
    Многие функции требуют авторизации пользователя. Функция authorize указывает логин и пароль пользователя, которые будут передаваться вместе с запросом. Метод передачи логина и пароля определяется свойством AuthType. Эту функцию достаточно вызвать один раз перед началом работы.
  4. Свойство AuthType: TAuthType
    Определяет метод передачи пароля. Возможные значения:
    atNone — не передавать данные авторизации. Все запросы передаются без логина и пароля. Некоторые функции не требуют авторизации и могут вызываться анонимными пользователями.
    atBasic — авторизация HTTP Basic — логин и пароль передаются в открытом виде, если вы используете защищенное соединение (HTTPS), то логин и пароль шифруются вместе с телом запроса.
    atDigest — авторизация HTTP Digest — вместо пароля передается специальный хеш, по которому трудно восстановить пароль. HTTP Digest надёжнее HTTP Basic, но тоже не гарантирует 100% защиты, по этому в любом случае рекомендуется использовать защищенное соединение. Т.к. метод HTTP Digest на самом деле не даёт такой защиты как хотелось бы, в Шаманграде реализован более простой HTTP Basic, который рекомендуется использовать вместе с защищенными соединениями. Метод HTTP Digest возможно будет реализован в будущем.
  5. Свойство UserName: AnsiString
    Хранит логин пользователя от имени которого будут производиться вызовы (если AuthType <> atNone).
  6. Свойство CA: AnsiString
    Хранит путь к файлу с сертификатами центров сертификации. Сертификаты используются для проверки подлинности сервера. Если указать пустую строку, то проверка подлинности будет отключена. Рекомендуется указывать полный путь к файлу сертификатов. Данное свойство используется только при работе через защищенное соединение.
  7. Свойство RX: Int64
    Хранит число байт принятых с момента начала работы шлюза.
  8. Свойство TX: Int64
    Хранит число байт переданных с момента начала работы шлюза.
  9. Свойство OnProgress: TProgressFunction
    Указывает обработчик события которое будет периодически вызываться в моменты выполнения запроса. В обработчике можно отслеживать объем передаваемых данных и прерывать выполнение операции (например, если превышено время ожидания ответа или пользователь нажал "Отмену")
  10. Свойство QueryCount: Integer
    Хранит число запросов выполненных с начала работы шлюза.

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

Примечание: транспортный модуль (wsrpcbase) является однозадачным, т.е. в каждый момент времени он способен выполнять только один запрос (по крайней мере пока). Попытка повторного вызова (до завершения обработки вызова) может привести к непредсказуемым последвиям. Поэтому будьте аккуратны при работе с обработчиком события OnProgress и работе в асинхронном или многопоточном режиме. Если вам нужно одновременно выполнять несколько запросов, то вы можете создать несколько экземпляров шлюза и необходимых модулей.

Прикладные модули

Прикладные модули реализуют более удобные обёртки поверх шлюза (транспортного уровня). С которыми и должен работать прикладной программист. Каждый прикладной модуль реализует один класс, в котором определяются все функции модуля (RPC-функции). Все прикладные модули в конструкторе принимают объект-шлюз, через который они будут делать свои вызовы.

Начало