CommuniGate Pro
Версия 6.0
Программы
 
 
Данные

Форматы Данных

Сервер CommuniGate Pro обрабатывает большинство типов данных как базовые объекты. В этом разделе описывается исходные, фундаментальные типы объектов, используемые всеми компонентами Сервера.

Для каждого типа объекта указывается текстовое представление объекта.

Когда объект сохраняется в файле, отправляется в ответ по команде CLI/API или извлекается с Сервера любым другим способом, то используется текстовое представление объекта.

Когда Сервер читает объект извне (из файла настроек, из команды CLI и т.д.), он преобразовывает полученное текстовое представление во внутренний объект.

Простые Объекты

Прострые объекты являются неструктурированными, обычными объектами одного из типов данных.

Строки

Строка является последовательностью байт, представляющих текст в кодировке UTF-8 и не содержащих двоичный нулевой байт.

Текстовое представление строки является либо атомарным - последовательностью букв латинского алфавита (в кодировке ASCII) и цифр, либо строкой в кавычках - последовательностью любых отображаемых символов (используя кодировку UTF-8), исключая символ кавычки и символ обратной косой черты, заключённую в кавычки (").
Примеры:
MyName My2ndName "My Name with spaces and the . symbol"
Если вы хотите включить символ кавычки в строку в кавычках, укажите символ обратной косой черты и кавычки, а если вы хотите включить символ обратной косой черты в строку в кавычках, укажите два символа обратной косой черты подряд.
Примеры:
"a \"string\" within string" "Single \\ backslash"
Вы можете использовать комбинацию символов \r для того, что бы включить символ возврата каретки в строку; вы можете использовать комбинацию символов \n для того, что бы включить символ перевод строки в строку и вы можете использовать комбинацию символов \e для того, что бы включить независимый от системы символ Конца Строки в строку.
Примеры:
"Line1\eLine2" "TEXT3\rTEXT67\nTEXT78"
Используйте комбинацию \r или \n для включения знаков возврата каретки и конца строки только если они НЕ используются как разделители строк.
Что бы включить в строку символ табуляции, вы можете использовать комбинацию символов \t.
Пример:
"Line1:\tField1\tField2\eLine2:\tField1\tField2"
Вы можете использовать комбинацию символов \nnn что бы включить в строку любой символ; здесь nnn - трехзначное десятичное число, равное коду ASCII требуемого символа.
Пример:
"Using the \012 (Vertical Tabulation) symbol"

Блоки Данных

Блоки данных (datablock) являются базовыми, неструктурированными блоками двоичных данных. Они создаются как текстовые строки двоичных данных в кодировке Base64, заключённые в квадратные скобки.
Пример:
[HcqHfHI=]
это блок двоичных данных, содержащих следующие 5 двоичных байт данных: 0x1D 0xCA 0x87 0x7C 0x72

Числа

Числа (number) являются основными неструктурированными объектами данных. Каждый объект Число содержит одно 64-битное целое значение, имеющее знак. Число представляется в виде текстовой строки, начинающейся с символа #, за которым следует (необязательный) символ минуса (-), за которым, в свою очередь, следует одно или более десятичное число.
Пример:
#-234657

Отметки о времени

Отметки о Времени (time stamp) являются основными неструктурированными объектами данных. Каждая Отметка о Времени содержит одно значение глобального времени. Значение времени представляется в GMT времени как текстовая строка, начинающаяся с символов #T и содержащая значение дня, месяца, года и, опционально, часа, минуты и секунды.
Пример:
#T22-10-2009_15:24:45
Существуют также две Отметки о Времени - одна для "далёкого прошлого" (#TPAST) и другая для "далёкого будущего" (#TFUTURE).

IP Адреса

IP Адреса (IP Address) являются основными неструктурированными объектами данных. Каждый объект IP Адрес содержит в себе IPv4 или IPv6 адрес и, опционально, номер порта. IP Адрес представляется в виде текстовой строки, начинающейся с символов #I и содержащей канонический IPv4 или IPv6 адрес, за которым опционально может следовать номер порта.
Примеры:
#I[10.0.44.55]:25 #I[2001:470:1f01:2565::a:80f]:25

Нулевой Объект

Нулевой объект является уникальным простым объектом, представляющим отсутствие любого другого объекта.
Нулевой объект представляется в виде текстовой строки #NULL#.

Структурированные Объекты

Массивы

Объект Массив (array) - это упорядоченный набор объектов (элементов массива).

Текстовое представление массива - список представлений его элементов, разделённых символами запятой (,) и заключенный в круглые скобки.
Пример:
(Element1 , "Element2" , "Element 3")
Элементом массива может быть любой объект - строка, массив, словарь и т.д.
Пример:
(Element1 , ("Sub Element1", SubElement2) , "Element 3")
Любое число пробелов, символов табуляции и/или символов новой строки (символов конца строки) может находиться между скобками и элементом, а также между элементом и символом запятой.
Пример:
(
  Element1 ,
  ( "Sub Element1",
   SubElement2 )
  ,
"Element 3" )
Массив может содержать ноль элементов (пустой массив).
Пример:
()

Словари

Объект Словарь (dictionary) является набором пар ключ-значение. Ключи словаря являются строками. Каждый ключ в словаре должен быть уникальным. Ключи словаря обрабатываются как зависимые от регистра строки, за исключением случая, если явно не указано иное.

Любой объект может использоваться как значение, связанное с ключом.

Текстовым представлением словаря является последовательность его пар ключ/значение, заключённое в фигурные скобки.
Каждая пара представляется как строка с ключом, за которым следует знак равно (=) и текстовое представление значения связанного объекта, оканчивающегося символом точка с запятой (;).
Пример:
{Key1=Element1; Key2 ="Element2" ; "Third Key"="Element 3"; }

Значением объекта в любой паре ключ/значение может быть строка, массив, словарь или любой другой объект.

Пример:
{Key1=(Elem1,Elem2); Key2={Sub1="XXX 1"; Sub2=X245;}; }

Любое число пробелов, символов табуляции и/или символов новой строки (символов конца строки) может находиться между фигурными скобками и парой, рядом с символом равно и рядом с символом точка с запятой.

Пример:
{
 Key1 = (Elem1,Elem2) ;
 Key2 = { Sub1 = "XXX 1";
    Sub2=X245; };
}

Словарь может иметь ноль элементов (пустой словарь).

Пример:
{}

XML

XML Объект является XML документом. Он имеет имя, набор пространств имён (строки), набор атрибутов со значениями типа строка и ноль, один или несколько элементов тела. Каждый элемент тела является либо строкой, либо XML Объектом.

Текстовым представлением XML Объекта явояется его стандартное текстовое представление, начинающееся с символа угловая скобка.


Правила Синтаксиса

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

d-digit ::= 0 .. 9
h-digit ::= d-digit | A | B | C | D | E | F
a-symbol ::= A .. Z | a .. z | d-digit
l-symbol ::= a-symbol | . | _
atom ::= 1* l-symbol
b-symbol ::= a-symbol | + | / | =
s-symbol ::= любой отображаемый символ кроме " и \ | \\ | \" | \r | \n | \e | \ d-digit d-digit d-digit
string ::= " 0* s-symbol " | atom
datablock ::= [ 1* b-symbol ]
day ::= 0 .. 3 d-digit (двухзначное число в диапазоне 1..31)
month ::= 0 .. 1 d-digit (двухзначное число в диапазоне 1..12)
year ::= 1 .. 2 d-digit d-digit d-digit (четырёхзначное число в диапазоне 1970..2038)
час ::= 0 .. 2 d-digit (двухзначное число в диапазоне 0..23)
минуту ::= 0 .. 5 d-digit (двухзначное число в диапазоне 0..59)
second ::= 0 .. 5 d-digit (двухзначное число в диапазоне 0..59)
number ::= # [ -] 1* d-digit
timestamp ::= # T day - month - year [ _ hour : minute : second ]
ip4 ::= 1* d-digit . 1* d-digit . 1* d-digit . 1* d-digit
ip6 ::= 0*(1* h-digit :) [: [ 0*(1* h-digit :) ] ]
ip-address ::= # I[ [ip4 | ip6] ] [ : 1*d-digit ]
null-object ::= #NULL#
array ::= ( [object 0*( , object ) ] )
dictionary ::= { 0*( string = object ; ) }
XML ::= <XML standard format >
object ::= string | datablock | number | timestamp | ip-address | null-object | array | dictionary | XML

XML Объекты

CommuniGate Pro может преобразовывать сложные структуры (такие как vCards, iCalendar, SDP объекты) в простые XML объекты. XML презентация может также потребоваться для таких объектов как блоки данных, массивы или словари. Этот раздел описывает XML презентацию для всех таких объектов и сложных структур.

Строка

Строка представляется как текстовый элемент.
Если это верхний XML элемент, то строка представляется как XML элемент object с текстовым телом, содержащим эту строку.

Блок Данных

Блок данных представляется как base64 XML элемент.
Телом XML элемента является содержимое блока данных в кодировке base64.

Число

Число представляется как XML элемент number.
Телом XML элемента является десятичное текстовое представление значения числового объекта.

Отметка о Времени

Отметка о Времени представляется как XML элемент date.
Телом XML элемента является текстовое представление отметки о времени в формате iCalendar.

IP Адреса

IP адреса представляются как XML элемент ipAddr.
Телом XML элемента является текстовое представление IP адреса, заключённое в квадратные скобки и опциональное десятичное число - номера порта, отделённое двоеточием.

Нулевое значение

Объект с нулевым значением представляется как пустой XML элемент null.

Массив

Массив представляется как последовательность из одного или более XML элементов subValue.
Тело XML элемента представляет элемент массива.
Пустой массив представляется как один элемент subValue, не имеющий тела.
Если верхний XML элемент, то массив представляется как XML элемент объект, с текстовым телом, содержащим элементы XML subValue.

Словарь

Словарь представляется как последовательность из одного или более XML элементов subKey.
Атрибут key XML элемента представляет ключ элемента словаря, а тело XML представляет значение элемента словаря.
Пустой словарь представляется как один элемент subKey без атрибута key и без тела.
Если верхний XML элемент, то словарь представляется как XML элемент объект, с текстовым телом, содержащим элементы XML subKey.

vCard

Этот XML элемент представляет объект vCard (согласно XML Vcard документов Jabber/JEP).
Атрибуты:
modified
Этот опциональный атрибут содержит значение свойства REV (время GMT в формате iCalendar).

Тело:
Содержит свойства vCard как XML элементы с такими же именами, преобразованными к верхнему регистру ASCII.
Каждый элемент свойства содержит:
Атрибуты:
отсутствуют

Тело:
набор XML подэлементов, представляющих параметры свойства и значение свойства:
параметры
XML элементы с такими же именами, как и имена параметров, преобразованные к верхнему регистру ASCII.
Параметры свойства vCard ENCODING и QUOTED-PRINTABLE используются для декодирования значений свойства и поэтому они не сохраняются.
value
структурированные значения (N,ORG,ADR)
набор XML элементов с именами элементов структуры и текстовые тела, содержащие подчасть структурированного значения свойства.
двоичное значение
XML элемент BINVAL с текстовым телом, содержащим значение свойства в кодировке base64.
текстовое значение
XML элемент VALUE с текстовым телом, содержащим значение свойства.

Пример:

begin:VCARD
source:ldap://cn=bjorn Jensen, o=university of Michigan, c=US
name:Bjorn Jensen
n:Jensen;bjorn;A;Mr;II
email;type=INTERNET:bjorn@umich.edu
org:U of Michigan;Computer Science Dept.
tel;type=WORK,MSG:+1 313 747-4454
key;type=x509;encoding=B:dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK
end:VCARD

<vCard>
  <SOURCE><VALUE>ldap://cn=bjorn Jensen, o=university of Michigan, c=US</VALUE></SOURCE>
  <NAME><VALUE>Bjorn Jensen</VALUE></NAME>
  <N><FAMILY>Jensen</FAMILY><GIVEN>bjorn</GIVEN>
    <MIDDLE>A</MIDDLE><PREFIX>Mr.</PREFIX><SUFFIX>II</SUFFIX></N>
  <EMAIL><VALUE>bjorn@umich.edu</VALUE></EMAIL>
  <ORG><ORGNAME>U of Michigan</ORGNAME><ORGUNIT>Computer Science Dept.</ORGUNIT></ORG>
  <TEL><WORK /><MSG /><VALUE>+1 313 747-4454</VALUE></TEL>
  <KEY><x509 /><BINVAL>dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK</BINVAL></KEY>
</vCard>

vCardGroup

Этот XML элемент представляет собой объект vCardGroup.
Атрибуты:
modified
Этот опциональный атрибут содержит значение свойства REV (время GMT в формате iCalendar).

Тело:
vCardGroup свойства как XML элементы с такими же именами, преобразованные к верхнему регистру ASCII: NAME, NOTE, UID. Каждый элемент включает в себя XML элемент VALUE с текстовым телом, содержащим значение свойства.

Ноль, один или несколько XML Элементов MEMBER, по одному на каждого члена группы. Текстовым телом XML элемента является адрес члена группы, а опциональный атрибут CN содержит "настоящее имя" элемента.

Пример:

BEGIN:VGROUP
PRODID:CommuniGate Pro 5.2
VERSION:1.0
NAME:Basket Buddies
NOTE:My basketball team.
UID:594895837.1@team.dom
REV:20071214T174114Z
MEMBER;CN="Jack Nimble":jack@nimble.dom
MEMBER;CN="Tim Slow":tim@slow.dom
END:VGROUP

<vCardGroup modified="20071214T174114Z">
  <NAME><VALUE>Basket Buddies</VALUE></NAME>
  <NOTE><VALUE>My basketball team.</VALUE></NOTE>
  <UID><VALUE>594895837.1@team.dom</VALUE></UID>
  <MEMBER CN="Jack Nimble">jack@nimble.dom</MEMBER>
  <MEMBER CN="Tim Slow">tim@slow.dom</MEMBER>
</vCardGroup>

iCalendar

Этот XML элемент представляет объект iCalendar.
Тело:
элемент vCalendar.

vCalendar

Этот XML элемент представляет объект vCalendar.
Атрибуты:
version
версия vCalendar (2.0 для iCalendar)
method
опциональный атрибут с методом vCalendar
prodid
опциональная строка, идентифицирующая продукт, использованный для создания этого объекта vCalendar.

Тело:
набор элементов vtimezone, vevent и/или vtodo, vfreebusy.

vtimezone

Этот XML элемент представляет объект VTIMEZONE.
Тело:
набор XML элементов:
  • tzid: тело элемента содержит название часового пояса.
  • standard и, опционально daylight: эти тела элементов содержат следующие XML элементы:
    • tzoffsetto: тело элемента содержит значение сдвига времени.
    • tzoffsetfrom (опционально) тело элемента содержит значение сдвига времени.
    • rrule (опционально): тело элемента содержит строку с описателем повторяемости.
Пример:
BEGIN:VTIMEZONE
TZID:Europe/Central
BEGIN:STANDARD
DTSTART:19710101T030000
TZOFFSETFROM:+0200
TZOFFSETTO:+0100
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19710101T020000
TZOFFSETFROM:+0100
TZOFFSETTO:+0200
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
END:DAYLIGHT
END:VTIMEZONE

<vtimezone>
  <tzid>Europe/Central</tzid>
  <standard>
    <dtstart>19710101T030000</dtstart>
    <tzoffsetto>+0100</tzoffsetto>
    <rrule>FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU</rrule>
  </standard>
  <daylight>
    <dtstart>19710101T020000</dtstart>
    <tzoffsetto>+0200</tzoffsetto>
    <rrule>FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU</rrule>
  </daylight>
</vtimezone>

vevent, vtodo

Эти XML элементы представляют объекты VEVENT и VTODO.

Атрибуты:
localTime
этот атрибут присутствует только для неповторяемых объектов. В нём содержится дата и время начала объекта. Время является местным временем в Часовом Поясе, выбранном для текущего пользователя.
localStart
этот атрибут присутствует только для повторяющихся объектов. В нём содержится время начала объекта (секунды, начиная с полуночи). Время является местным временем в Часовом Поясе, выбранном для текущего пользователя.

Тело:
набор XML элементов, каждый представляющий одно свойства.
Параметры свойства представляются как атрибуты элемента.
Значение свойства представляется в теле Элемента.
Если значение начинается с префикса MAILTO:, то этот префикс удаляется.

Пример:
BEGIN:VEVENT
ORGANIZER;CN="Jim Smith":MAILTO:jim_smith@example.com
RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU,WE,TH;UNTIL=20060305T000000Z
DTSTAMP:20051204T140844Z
UID:566852630.4@mail.example.com
SEQUENCE:1
SUMMARY:test - recurrent
DTSTART;TZID=NorthAmerica/Pacific:20051204T100000
DTEND;TZID=NorthAmerica/Pacific:20051204T110000
X-MICROSOFT-CDO-BUSYSTATUS:BUSY
LAST-MODIFIED:20051204T140844Z
CREATED:20051204T140844Z
PRIORITY:5
END:VEVENT

<vevent>
  <organizer CN="Jim Smith">jim_smith@example.com</organizer>
  <rrule>FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU,WE,TH;UNTIL=20060305T000000Z</rrule>
  <dtstamp>20051204T140844Z</dtstamp>
  <uid>566852630.4@mail.example.com</uid>
  <sequence>1</sequence>
  <summary>test - recurrent</summary>
  <dtstart tzid="NorthAmerica/Pacific">20051204T100000</dtstart>
  <dtend tzid="NorthAmerica/Pacific">20051204T110000</dtend>
  <busystatus>BUSY</busystatus>
  <last-modified>20051204T140844Z</last-modified>
  <created>20051204T140844Z</created>
  <priority>5</priority>
</vevent>

vfreebusy

Эти XML элементы представляют объекты VFREEBUSY.

Атрибуты:
dtstart
время начала временного периода, покрываемого объектом VFREEBUSY.
dtend
время окончания временного периода, покрываемого объектом VFREEBUSY.
dtstamp
время, когда был создан этот объект VFREEBUSY.

Тело:
набор XML элементов freebusy, каждый из которых представляет один временной интервал. Временные интервалы не пересекаются.

Атрибуты:
dtstart
время начала временного интервала.
dtend
время окончания временного интервала.
fbtype
опциональный статус типа занятости. Если он не указан, то интервал имеет статус BUSY.

Пример:
BEGIN:VFREEBUSY
DTSTART:20080329T075517Z
DTEND:20080604T075517Z
DTSTAMP:20080405T075517Z
FREEBUSY:20080329T075517Z/20080329T120000Z
FREEBUSY:20080330T070000Z/20080330T120000Z
FREEBUSY:20080331T070000Z/20080331T120000Z
END:VFREEBUSY

<vfreebusy dtend="20080604T075517Z" dtstamp="20080405T075517Z" dtstart="20080329T075517Z">
  <freebusy dtend="20080329T120000Z" dtstart="20080329T075517Z" />
  <freebusy dtend="20080330T120000Z" dtstart="20080330T070000Z" />
  <freebusy dtend="20080331T120000Z" dtstart="20080331T070000Z" />
</vfreebusy>

xrule

Этот XML элемент представляет повторяющийся объект.
Атрибуты:
freq
тип повторяемости.
interval
параметр с интервалом. Если отсутствует, интервал подразумевается равным 1.
wkst
название дня, с которого начинается неделя. Если отсутствует, то подразумевается MO (Понедельник).
count
опциональный атрибут, имеющий целочисленное значение, в котором указывается параметр COUNT.
until
опциональный атрибут, указывающий параметр UNTIL в формате даты-времени iCalendar.

Тело:
набор XML элементов:
BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYSETPOS
каждое тело элемента содержит число - номер месяца, номер недели и т.д. За исключением элемента BYMONTH, число может быть отрицательным.
BYDAY
каждое тело элемента содержит одно наименование дня (MO, TU, .. SU); каждый элемент может содержать опциональный числовой атрибут week номер недели (он может быть отрицательным).

Пример:

RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU,WE,TH;UNTIL=20060305T000000Z

<xrule freq="WEEKLY" interval="2" until="20060305T000000Z">
  <BYDAY>MO</BYDAY><BYDAY>TU</BYDAY><BYDAY>WE</BYDAY><BYDAY>TH</BYDAY>
</xrule>

Пример:
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU

<xrule freq="YEARLY">
  <BYMONTH>10</BYMONTH><BYDAY week="-1">SU</BYDAY>
</xrule>

sdp

Этот XML элемент представляет SDP объект.
Атрибуты:
ip
IP адрес медиа по умолчанию (опционально).
origUser
поле username оригинальной сессии (опционально).
sessionID
поле sess-id оригинальной сессии.
sessionVersion
поле sess-version оригинальной сессии.
origIP
IP адрес, указанный в полях nettype, addrtype и unicast-address оригинальной сессии.
subject
subject сессии (опционально). Если отсутствует, то используется subject -.

Тело:
набор media элементов.

media

Этот XML элемент представляет SDP Медиа объект.
Атрибуты:
media
типа медиа (такой, как audio, video). Если этот атрибут отсутствует, то используется значение audio.
ip
адрес и порт медиа.
protocol
медиа протокол (такой, как udp, tcp, RTP/AVP). Если этот атрибут отсутствует, то используется значение RTP/AVP.
direction
направление медиа (sendrecv, sendonly, recvonly, inactive).

Тело:
набор элементов codec.

codec

Этот XML элемент представляет SDP Медиа кодек.
Атрибуты:
id
идентификатор кодека RTP - номер из диапазона 0..127.
name
имя кодека (такое, как PCMU/8000).
format
параметр формата кодека.

Пример: образец SDP документа и его XML представления:
v=0
o=- 6385718 9999 IN IP4 192.168.1.65
s=-
c=IN IP4 192.168.1.65
t=0 0
m=audio 16398 RTP/AVP 0 4 8 101
a=rtpmap:0 PCMU/8000
a=rtpmap:4 G723/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv

<sdp ip="[192.168.1.65]" origUser="-" sessionID="6385718" sessionVersion="9999" originIP="[192.168.1.65]">
  <media media="audio" ip="[192.168.1.65]:16398" protocol="RTP/AVP" direction="sendrecv">
    <codec id="0" name="PCMU/8000" />
    <codec id="4" name="G723/8000" />
    <codec id="8" name="PCMA/8000" />
    <codec id="101" name="telephone-event/8000" format="0-15" />
  </media>
</sdp>

Руководство CommuniGate® Pro. Copyright © 1998-2009, Stalker Software, Inc.