Client API

Для формирования и отправки клиентом запросов по протоколу Протокол Mega-cnt (Client API) используется класс CMegaApi

Примеры Client API examples

• Класс CMegaApi используется для формирования запроса к сервису, отправки запроса, получения ответа и выделения необходимых данных из ответа.
• В классе CMegaApi присутствуют только статические функции, создание экземпляра класса не требуется.

Общее описание процесса обмена данными с сервисом

Для отправки и получения данных используются различные функции класса CMegaApi
Общий порядок действий:

1. Инициализация запроса
2. Помещение данных в запрос
3. Отправка запроса
4. Чтение полученных данных

Для инициализации запроса вызывается функция CMegaApi::NewRequest().
Далее вызывается одна или несколько Функций подготовки запроса.
Запрос отправляется функцией CMegaApi::SendRequest().
Далее вызывается одна или несколько Функций обработки ответа для получения данных из результата запроса.
Если необходимо повторить предыдущий запрос без изменения, то опять вызывается CMegaApi::SendRequest().
Для создания нового запроса вызывается CMegaApi::NewRequest() и т.д.

Функции подготовки запроса

Создание нового запроса

CMegaApi::NewRequest(login, pass)

параметр	описание	значение по умолчанию
login	логин пользователя
pass	пароль пользователя
возвращаемый результат
отсутствует

Создаётся новый запрос. Все данные предыдущего запроса удаляются.
NewRequest() должна быть вызвана перед формированием нового запроса.
Если необходимо повторить предыдущий запрос без изменения, то NewRequest() не вызывается.

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

CMegaApi::SendMessage(addr, text, device=false, sim=false, tFrom=0, tBefore=0, tMaxDelivery=0, flags=0)

параметр	описание	значение по умолчанию
addr	номер телефона получателя в международном формате без '+' (79871234567)
text	текст сообщения произвольной длины
device	id устройства, через которое должно быть отправлено сообщение	false = любое доступное
sim	id sim-карты, через которую должно быть отправлено сообщение	false = любая
tFrom	timestamp (сек.), не раньше которого нужно отправить сообщение	0 = любое
tBefore	timestamp (сек.), не позже которого нужно отправить сообщение	0
tMaxDelivery	timestamp (сек.), до которого ожидать подтверждения доставки ИЛИ если tMaxDelivery<=0 ((-)макс.время, сек, в течение которого ожидать доставку после отправки	0
flags	флаги: CMegaApi::FL_TEST = 0x0100 - тестовое сообщение, не отправляется с телефона, а будет возвращено как входящее*	0
возвращаемый результат
true - сообщение добавлено, false - ошибка в параметрах

Добавляет новое сообщение для отправки
.* Тестовые сообщения не поддерживают кириллицу. Только латинские символы!

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

CMegaApi::SendMessageEncoded($data, $device=false, $sim=false, $tFrom=0, $tBefore=0, $tMaxDelivery=0, $flags=0)

параметр	описание	значение по умолчанию
data	base64(RSA)
..	см. SendMessage
возвращаемый результат
true - сообщение добавлено, false - ошибка в параметрах

Добавляет новое зашифрованное сообщение для отправки. Данные шифруются открытым ключом клиента и расшифровываются на телефоне закрытым ключом (RSA).

Запрос информации по отправленным сообщениям

CMegaApi::RequestMessageStatuses($ids)

параметр	описание	значение по умолчанию
ids	id одного сообщения или массив идентификаторов сообщений
возвращаемый результат
отсутствует

Запрос входящих сообщений

CMegaApi::RequestIncomingMessages($ids='new', $bDelete=1, $bExtra=0, $did=0, $sid=0)

параметр	описание	значение по умолчанию
ids	id сообщения ИЛИ массив идентификаторов сообщений ИЛИ 'all' - все входящие сообщения ИЛИ 'new'- новые (не прочитанные) входящие сообщения	'new'
bDelete	удалить запрошенные сообщения с сервера сразу после запроса	1
bExtra	получить дополнительные данные в ответе, см {im]}	0
did	id устройства, с которого нужно получить сообщения	0
sid	id sim-карты, с которой нужно получить сообщения	0
возвращаемый результат
отсутствует

Указывает, какие входящие сообщения необходимо получить с сервера.

Выполнить команду на сервере

CMegaApi::RequestCmd()

параметр	описание	значение по умолчанию
возвращаемый результат
отсутствует

На данный момент выполнение клиентских команд не поддерживается.

Функции отправки запроса

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

CMegaApi::SendRequest()

возвращаемый результат
HTTP Staus Code или CMegaApi::ERR_NO_CONNECTION = 1001 CMegaApi::ERR_WRONG_SERVER_RESPONSE = 1002 CMegaApi::ERR_WRONG_API_VERSION = 1003

Отправляет запрос на сервер, получает и запоминает результат.

Получение тела запроса

CMegaApi::GetRequestBody()

возвращаемый результат
JSON-строка сформированного запроса

Вспомогательная функция. Может использоваться для отладки.

Функции обработки ответа

Получение общего кол-ва отправленных в запросе новых сообщений

CMegaApi::GetNewMessageNum()

возвращаемый результат
общее кол-во новых сообщений из запроса

Получение кол-ва принятых к отправке сообщений

CMegaApi::GetAcceptedMessageNum()

возвращаемый результат
кол-во принятых к отправке новых сообщений из запроса

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

Получение информации о новых сообщениях, отправленных в запросе

CMegaApi::GetNewMessageInfo($idx=false)

параметр	описание	значение по умолчанию
idx	индекс нового сообщения из запроса 0+ ИЛИ false - информация по всем новым сообщениям	false
возвращаемый результат
структура {oms} ИЛИ массив [{oms},...] для каждого нового сообщения ИЛИ false в случае отсутствия данных

Получение информации о сообщении

CMegaApi::GetMessageInfo($id)

параметр	описание	значение по умолчанию
id	идентификатор сообщения	нет
возвращаемый результат
структура {oms} ИЛИ false в случае отсутствия данных

Возвращает данные о сообщении (статус и другую информацию)

Получение входящих сообщений

CMegaApi::GetIncomingMessages()

возвращаемый результат
ассоциативный массив данных по всем запрошенным входящим сообщениям {id1:{im},...}