Структура файла исходящих сообщений nhsms
Файл имеет структуру INI файла, каждый раздел задаёт одно исходящее сообщение или один USSD запрос.
Благодаря этому:
- файл может содержать практически неограниченное число исходящих смс или ussd запросов – при условии размера файла до 100 МБ
- для каждого смс или ussd можно указывать только те поля, которые нужны для него – гибкая структура, в отличие от таблицеобразных форматов типа csv
- файл удобен для чтения – в отличие от xml
Файл может быть сохранён в Unicode, UTF-8, ANSI, OEM. Кодировка определяется автоматически по заголовкам и содержимому файла, кроме OEM. Чтобы отправить СМС в кодировке OEM, необходимо сформировать текст СМС в кодировке OEM и добавить параметр CodePage=OEM для каждой СМС в кодировке OEM. Таким образом, в одном файле можно смешивать СМС в кодировках ANSI и OEM.
Параметры смс
[Обозначение СМС]
Phone=номер телефона адресата, без плюса, можно несколько номеров через запятую
PhoneType=international*|national
international - международный номер вида 79851234567
national - короткий номер, например, 111
SMSC=номер центра обслуживания, без плюса
Alert=0*|1
0 - обычная смс
1 - сразу по приёму смс выводится на экран (alert-sms, flash-sms)
StatusReportRequest=0*|1
0 - не запрашивать статус смс
1 - запрашивать статус смс
Text=текст сообщения в одну строку
CodePage=
OEM - означает, что поле Text записано в кодировке OEM.
Для других кодировок этот параметр не используется.
ValidityPeriod=срок действия смс (подробнее)
SendingPriority=B|L|N*|P|T
B - низший приоритет
L - низкий приоритет
N - обычный приоритет
P - высокий приоритет
T - высший приоритет
SendingTime=время с,время до,дни
время с - в формате h:mm
время до - в формате h:mm
дни - дни недели Sun,Mon,Tue,Wed,Thu,Fri,Sat или дата yyyy-M-d
Параметры ussd
[Обозначение USSD запроса]
USSD=запрос ответа,"текст запроса"[,схема кодирования данных]
запрос ответа - 0|1, 0 = не показывать ответ, 1 = показывать ответ
текст запроса - собственно запрос, например, *100#
схема кодирования данных - число, по умолчанию 15
Coding=text*|pdu
Кодирование запроса перед отправкой (смотря какую кодировку
поддерживает ваш модем):
text - в виде текста, т.е. без перекодировки
pdu - кодирование в 7 бит
CommandLine=команда, которая будет запущена после выполнения запроса
Описание параметров файла исходящих сообщений
ValidityPeriod — период действия смс
5m,10m…55m значения от 5 до 55 минут с шагом 5 минут или 1h,1h5m…11h55m значения от 1 часа до 11 часов 55 минут с шагом 5 минут или 12h,12h30m…24h значения от 12 часов до 24 часов с шагом 30 минут или 1d,2d…30d значения от 1 до 30 дней или 5w,6w…63w значения от 5 до 63 недель.
Все значения ‘включительно’.
Вместо латинских букв m, h, d, w можно использовать русские м, ч, д, н.
Примеры:
15m или 15м 15 минут 1h или 1ч 1 час 1h30m или 1ч30м полтора часа 24h или 24ч один день 1d или 1д один день 30d или 30д один месяц 25w или 25н примерно полгода (25 недель)
SendingPriority — приоритет отправки смс и ussd
Параметр SendingPriority применяется к каждому смс или ussd и задаёт приоритет отправки этого сообщения.
Используя этот параметр, можно отправить более важное смс или ussd вне очереди.
Приоритет сообщения задаётся латинской буквой:
B - низший приоритет (Bottom) L - низкий приоритет (Low) N - обычный приоритет (Normal) P - высокий приоритет (Priority) T - высший приоритет (Top)
Программа отправляет в первую очередь сообщения с высшим приоритетом (T), затем с высоким (P) и так далее.
SendingPriority добавлен в версии nhsms v3.0, в предыдущих версиях он игнорируется.
SendingPriority используется только в конфигурации с базой данных. В конфигурации с отключенной базой данных этот параметр не влияет на очерёдность отправки.
SendingTime — время отправки смс и ussd
Параметр SendingTime применяется к каждому смс или ussd и задаёт разрешённое время отправки этого сообщения.
Используя этот параметр, можно ограничить время отправки сообщения, например:
- смс о статусе заказа – в рабочие дни с 9 до 19 часов
- смс-поздравления с днём рождения – строго в день рождения, начиная с 10 часов утра
- ussd запроса баланса – в заданное время суток
Отправка в рабочее время:
SendingTime=10:00,19:00,Mon,Tue,Wed,Thu,Fri
Отправка в определённую дату:
SendingTime=10:00,19:00,2017-03-07
SendingTime добавлен в версии nhsms v3.0, в предыдущих версиях он игнорируется.
SendingTime используется только в конфигурации с базой данных. В конфигурации с отключенной базой данных этот параметр не влияет на очерёдность отправки.
Примеры файла исходящих сообщений
Пример файла с двумя сообщениями и одним USSD запросом
[1] Phone=79161111111 Alert=1 Text=Нет связи с контроллером домена ValidityPeriod=2d [2] Phone=79162222222,79163333333 Text=Нет связи с контроллером домена ValidityPeriod=1d [balance] USSD=1,"#100#",15 CommandLine=ussd_balance.js
Там, где параметры SMSC, Alert, StatusReportRequest не заданы, используются значения, заданные в конфиг файле.
Особенности отправки сообщений
Конфигурация с базой данных
В nhsms v3.0 и старше, если использование базы включено в файле конфигурации, см. раздел база данных, программа отправляет сообщения из базы данных, в соответствии приоритетом и разрешённым временем отправки.
Программа выбирает из очереди сообщений (из базы данных) сообщение для отправки:
- выбираются сообщения, которые можно отправить сейчас (по разрешенному времени отправки)
- из них выбираются сообщения с максимальным приоритетом
- из них выбирается одно сообщение – которое было поставлено в очередь первым
Таким образом, ведение общей очереди сообщений в базе данных даёт больший контроль над очерёдностью отправки смс, по сравнению с отправкой из файлов.
В этом режиме отправка непосредственно из файлов не производится, вместо этого программа импортирует смс/ussd в базу данных, включая заданный в файле приоритет (параметр SendingPriority) и день/время отправки(параметр SendingTime). Все файлы сообщений импортируются в единую таблицу, образуя общую очередь сообщений.
Информация о сообщениях сохраняется в базе данных.
- Статус сообщения – ожидает отправки, отправлено, доставлено или ошибка
- Время постановки в очередь
- Время отправки
Конфигурация без базы данных
В этом режиме работает nhsms версии версии v3.0+ при отключенной базе данных (см. раздел база данных) и nhsms v1-v2.
Программа nhsms отправляет сообщения из файла в том порядке, в котором они перечислены в файле. После отправки каждого сообщения программа переносит информацию о нём в файл отправленных сообщений (файл, заданный параметром Parameters|SmsFileOnComplete). Записываемая информация включает результаты отправки и описана в параграфе Особенности отправки смс.
Поскольку программа nhsms выполняет запись в файл исходящих сообщений, то на время обработки файла она блокирует доступ к этому файлу со стороны других программам для избежания конфликтов одновременного доступа и возможного повреждения файла.
Сохраненная информация используется при повторной обработке файла, например, если работа программы была прервана пользователем во время обработки файла, то этот файл будет обработан при следующем запуске, и будут отправлены только те сообщения, которые не были отправлены ранее.
Отправка смс
Программа проверяет результат отправки сообщения, в случае ошибки, делает повторную попытку. По умолчанию, делается не больше трёх попыток отправки СМС.
Если неправильно заданы параметры СМС, например, поле Phone не содержит номера, программа не пытается отправить СМС, а сразу записывает соответствующий результат отправки.
Кодировка сообщения 7 или 16 бит выбирается автоматически: если отправляемый текст совместим с кодировкой GSM 7 bit, смс будет закодирована в 7 бит, иначе в 16 бит. Одно 7 битное сообщение может содержать 160 символов, одно 16-битное — 70 символов.
Более длинные сообщения автоматически разбиваются на части. Каждая часть может содержать 153 символа в 7-битной кодировке или 67 символов в 16-битной кодировке.
Результаты отправки сообщений записываются в соответствующий файл. Для сообщений, отправляемых из файлов, выходной файл определяется параметром Parameters|SmsFileOnComplete. Для сообщений, заданных параметром командной строки, файл определяется параметром CommandLineSmsFile. Для коротких сообщений программа записывает параметры сообщения и следующие поля:
SentTm=2010-04-06 18:45:40 Дата и время отправки ГГГГ-ММ-ДД чч:мм:сс ResultCode=0 Код выполнения (0-успешно, иначе код ошибки) ResultText= Текстовое пояснение для ошибок Parts=1 Число частей (1 означает короткое СМС) MessageReference=0 Идентификационный номер сообщения (только для короткого)
Для длинных сообщений программа записывает информацию по сообщению в целом и по каждой части (нумерация частей с нуля):
SentTm=2010-04-06 18:45:40 Дата и время отправки сообщения (последней части) ГГГГ-ММ-ДД чч:мм:сс ResultCode=0 Код выполнения (итоговый код отправки для всего длинного сообщения) ResultText= Текстовое пояснение для ошибок Parts=2 Число частей (2 или больше означает длинное СМС) SentTm_Part0=2010-04-06 18:45:30 Информация по первой части ResultCode_Part0=0 ResultText_Part0= MessageReference_Part0=8 SentTm_Part1=2011-04-06 18:45:40 Информация по второй части ResultCode_Part1=0 ResultText_Part1= MessageReference_Part1=48
Отправка ussd
После выполнения USSD запроса программа запускает команду, заданную параметром CommandLine. В создаваемый процесс передаются параметры запроса в виде переменных окружения:
ussd_request Отправленный USSD запрос
ussd_response Ответ на запрос - текстовая часть (то, что между кавычками)
из ответа +CUSD: 0,"..."
ussd_resultcode Код ошибки (0-успешно, иначе - ошибка)
ussd_resulttext Описание результата: текст ошибки, может включать полный ответ модема
Для USSD запросов программа добавляет в выходной файл поля:
USSDResponse=Minus:1974,18r,Limit:50000000r Текст ответа SentTm=2010-04-06 18:45:40 Дата и время отправки ResultCode=0 Код выполнения (0-успешно) ResultText=+CUSD: 0,"Minus:1974,18r,Limit:50000000r " Полный ответ модема