CommuniGate Pro
Version 5.4
Applications
 
 
Data

Data Formats

The CommuniGate Pro Server processes most types of data as generic objects. This section describes the generic, fundamental object types used in all Server components.

For each object type, a textual representation of the object data is specified.

When an object is stored in a file, sent in a CLI/API command response, or extracted from the Server in any other way, the object textual representation is used.

When the Server reads an object from outside (from a settings file, from a CLI command, etc.), it converts the provided textual representation into an internal object.

Textual Representation

Objects can be represented as a single-line or multi-line text (depending on the context).

Object representation elements can be separated using "white spaces". Only the space symbol can be used as a "white space" in single-line texts.
In multi-line texts the space and "horizontal tab" symbols, as well as the EOL (End-Of-Line, CR and/or LF) symbols are treated as "white spaces". Additionally, a "comment" is treated as a "white space", where the comment consists of two consecutive periods forward slash symbols (//) and all following symbols up to and including the first EOL symbol.

Atomic Objects

Atomic objects are unstructured, generic data-type objects.

Strings

A string is a sequence of UTF-8 encoded text bytes, not containing a binary zero byte.

A textual representation of a string is either an atom - a sequence of Latin letters (in the ASCII encoding) and digits, or a quoted string - a sequence of any printable symbols (using the UTF-8 encoding) except the quotation mark and the backslash symbol, enclosed into the quotation marks (").
Examples:
MyName   My2ndName   "My Name with spaces and the . symbol"
If you want to include the quotation mark symbol into a quoted string, include the backslash symbol and the quotation mark, if you want to include the backslash symbol into a quoted string, include two backslash symbols.
Examples:
"a \"string\" within string"   "Single \\ backslash"
You can use the \r symbol combination to include the carriage-return symbol into a string, you can use the \n symbol combination to include the line-feed symbol into a string, and your can use the \e symbol combination to include the system-independent End-Of-Line symbol(s) into a string.
Examples:
"Line1\eLine2"   "TEXT3\rTEXT67\nTEXT78"
Use the \r or \n combinations to include the carriage-return and line-feed characters only when they are NOT used as line separators.
You can use the \t symbol combination to include the tabulation symbol into a string.
Example:
"Line1:\tField1\tField2\eLine2:\tField1\tField2"
You can use the \nnn symbol combination to include any symbol into a string, if nnn is a 3-digit decimal number equal to the ASCII code of the desired symbol.
Example:
"Using the \012 (Vertical Tabulation) symbol"

In multi-line texts, a string can be represented as two or more consecutive strings with zero or more white spaces between them. This feature allows you to break very long string objects into several strings and put them on multiple text lines.

DataBlocks

DataBlocks are basic, unstructured blocks of binary data. They are composed as text strings with the Base64 encoding of binary data enclosed into brackets.
Example:
[HcqHfHI=]
this is a binary block containing the following 5 binary data bytes: 0x1D 0xCA 0x87 0x7C 0x72

White spaces can be placed before and after the brackets and between any symbols of the encoded data.

Numbers

Numbers are basic, unstructured data objects. Each Number object contains one 64-bit signed integer value. A Number is presented as a text string starting with the # symbol, followed by an optional minus (-) symbol, followed by 1 or more decimal digits.
Example:
#-234657

Time Stamps

Time Stamps are basic, unstructured data objects. Each Time Stamp object contains one global time value. The time value is presented in GMT time, as a text string starting with the #T symbols, and containing the day, months, year, and, optionally, the hour, minute, and the second values.
Example:
#T22-10-2009_15:24:45
There are 2 special Time Stamps - for the "remote past" (#TPAST) and for the "remote future" (#TFUTURE).

IP Addresses

IP Addresses are basic, unstructured data objects. Each IP Address object contains an IPv4 or IPv6 address, and, optionally a port number. The IP Address is presented as a text string starting with the #I symbols, and containing the canonical IPv4 or IPv6 address, optionally followed by the port number.
Examples:
#I[10.0.44.55]:25  #I[2001:470:1f01:2565::a:80f]:25

Null Object

A null-object is a unique atomic object used to represent absence of any other object.
The Null Object is presented as the #NULL# text string.

Other Objects

When the Server converts internal data objects into the text presentation, it may encounter some custom, application-specific objects. These objects are presented as #(objectName:address) text strings, where objectName is an alpha-numeric object class name, and address is a hexadecimal number - the object memory address.

These objects must NOT be used in text presentation being converted into a data object.

Structured Objects

Arrays

An array object is an ordered set of objects (array elements).

Array textual representation is a list of its element representations, separated with the comma (,) symbols, and enclosed into the parentheses.
Example:
(Element1 , "Element2" , "Element 3")
An array element can be any object - a string, an array, a dictionary, etc.
Example:
(Element1 , ("Sub Element1", SubElement2) , "Element 3")
Any number of spaces, tabulation symbols, and/or line breaks (end-of-line symbols) can be placed between a parenthesis and an element, and between an element and a comma symbol.
Example:
(
  Element1  ,
  (    "Sub Element1",
   SubElement2  )
  ,
"Element 3"  )
An array may have zero elements (an empty array).
Example:
()

Dictionaries

A dictionary object is a set of key-value pairs. Dictionary keys are strings. Each key in a dictionary should be unique. The dictionary keys are processed as case-sensitive strings, unless explicitly specified otherwise.

Any object can be used as a value associated with a key.

A dictionary textual representation is a sequence of its key value pairs, enclosed into the curvy brackets.
Each pair is represented as its key string representation, followed by the equal (=) symbol, followed by the textual representation of the associated value object, followed by the semicolon (;) symbol.
Example:
{Key1=Element1; Key2 ="Element2" ; "Third Key"="Element 3"; }

The value object in any key-value pair can be a string, an array, a dictionary, or any other object.

Example:
{Key1=(Elem1,Elem2); Key2={Sub1="XXX 1"; Sub2=X245;}; }

Any number of spaces, tabulation symbols, and/or line breaks (end-of-line symbols) can be placed between a bracket and a pair, around the equal symbol, and around the semicolon symbol.

Example:
{
 Key1  =   (Elem1,Elem2)   ;
 Key2 = {  Sub1 = "XXX 1";
    Sub2=X245;  };
}

A dictionary may have zero elements (an empty dictionary).

Example:
{}

XML

An XML object is an XML document. It has a name, a set of namespaces (strings), a set attributes with string values, and zero, one, or several body elements. Each body element is either a string or an XML object.

An XML object textual representation is its standard textual representation, starting with the angle bracket symbol.

Formal Syntax Rules

Below is the formal syntax definition for textual representations of the basic type objects.

d-digit ::= 0 .. 9
h-digit ::= d-digit | A | B | C | D | E | F
a-symbol ::= A .. Z | a .. z | d-digit
u-symbol ::= a-symbol | any non-ASCII utf-8 symbol
l-symbol ::= u-symbol | . | - | _ | @
atom ::= 1* l-symbol
b-symbol ::= a-symbol | + | / | =
s-symbol ::= any printable symbol except " and \ | \\ | \" | \r | \n | \e | \ d-digit d-digit d-digit
string ::= " 0* s-symbol " | atom
datablock ::= [ 1* b-symbol ]
day ::= 0 .. 3 d-digit (2-digit number in the 1..31 range)
month ::= 0 .. 1 d-digit (2-digit number in the 1..12 range)
year ::= 1 .. 2 d-digit d-digit d-digit (4-digit number in the 1970..2038 range)
hour ::= 0 .. 2 d-digit (2-digit number in the 0..23 range)
minute ::= 0 .. 5 d-digit (2-digit number in the 0..59 range)
second ::= 0 .. 5 d-digit (2-digit number in the 0..59 range)
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 Objects

CommuniGate Pro can convert complex structures (such as vCards, iCalendar, SDP objects) into generic XML objects. An XML presentation may also be required for Objects such as datablocks, arrays, or dictionaries. This section specifies the CommuniGate Pro XML presentation for all these objects and complex structures.

String

A string is presented as a text element.
If this is a top XML element, a string is presented as an object XML element, with the text body containing this string.


If a string contains special characters, it should be represented as a binString element with a text body containing the base64-encoded string.
An empty string is presented as an empty binString element.

Datablock

A datablock is presented as a base64 XML element.
The XML element body is the base64-encoded datablock content.

Example:
<base64>STYRyui=</base64>

Number

A number is presented as a number XML element.
The XML element body is the decimal text presentation of the number object value.

Example:
<number>123456</number>

Time Stamp

A Time Stamp is presented as a date XML element.
The XML element body is the text presentation of the time stamp in the iCalendar format.

Example:
<date>20101122T123000Z</date>

IP Addresses

An IP Addresses is presented as an ipAddr XML element.
The XML element body is the text presentation of the IP address, enclosed with square brackets, and optional decimal port number separated with the colon symbol.

Example:
<ipAddr>[10.0.2.2]:8010</ipAddr>

Null-value

A null-value object is presented as an empty null XML element.

Array

An array is presented as a sequence of one or more subValue XML elements.
The XML element body represents an Array element.
An empty array is presented as one subValue XML element without a body.
If this is a top XML element, the array is presented as an object XML element, with the text body containing subValue XML elements.

Example:
<subValue>my string</subValue><subValue><number>123456</number>/subValue>

Dictionary

A dictionary is presented as a sequence of one or more subKey XML elements.
The XML element key attribute presents the dictionary element key, and the XML body represents the dictionary element value.
An empty dictionary is presented as one subKey XML element without a key attribute and without a body.
If this is a top XML element, the dictionary is presented as an object XML element, with its body containing subKey XML elements.

Example:
<subKey key="firstKey">my string</subKey><subKey key="secondKey"><number>123456</number>/subKey>

vCard

This XML element represents a vCard object (as specified in the Jabber/XEP vCard XML documents).
Attributes:
modified
This optional attribute contains the value of the REV property (iCalendar-formatted GMT time).

Body:
Contains vCard properties as XML elements with the same names, converted to the uppercase ASCII.
Each property element contains:
Attributes:
none

Body:
a set of XML sub-elements representing property parameters and the property value:
parameters
XML elements with the same names as the parameter names, converted to the uppercase ASCII.
The ENCODING and QUOTED-PRINTABLE vCard property parameters are used to decode the property value and they are not stored.
value
structured value (N,ORG,ADR)
a set of XML elements with structure element names, and text bodies containing a subpart of the structured property value.
binary value
a BINVAL XML element with a text body containing the base64-encoded property value.
text value
a VALUE XML element with a text body containing the property value.

Example:

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

This XML element represents a vCardGroup object.
Attributes:
modified
This optional attribute contains the value of the REV property (iCalendar-formatted GMT time).

Body:
vCardGroup properties as XML elements with the same names, converted to the uppercase ASCII: NAME, NOTE, UID. Each element includes a VALUE XML element with a text body containing the property value.

Zero, one, or several MEMBER XML Elements, one for each group member. The XML element text body is the group member address, while an optional CN attribute can contain the element "real name".

Example:

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

This XML element represents an iCalendar object.
Body:
a vCalendar element.

vCalendar

This XML element represents a vCalendar object.
Attributes:
version
the vCalendar version (2.0 for iCalendar)
method
an optional attribute with a vCalendar method
prodid
an optional identification string of the product used to create this vCalendar object.

Body:
a set of vtimezone, vevent, vtodo, vfreebusy elements.

vtimezone

This XML element represents a VTIMEZONE object.
Body:
a set of XML elements:
  • tzid: the element body contains the zone name.
  • standard and, optionally, daylight: these element bodies contain the following XML elements:
    • tzoffsetto: the element body contains the time shift value.
    • tzoffsetfrom (optional): the element body contains the time shift value.
    • rrule (optional): the element body contains a string with a recurrence descriptor.
Example:
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

These XML elements represent VEVENT and VTODO objects.

Attributes:
localTime
this attribute is present for non-recurrent objects only. It contains the date and time the object starts. The time is the local time in the Time Zone selected for the current user.
localStart
this attribute is present for recurrent objects only. It contains the time the object starts (seconds since midnight). The time is the local time in the Time Zone selected for the current user.

Body:
a set of XML elements, each representing one property.
The property parameters are represented as element attributes.
The property value is represented as the element body.
If the value starts with the MAILTO: prefix, this prefix is removed.
If an object has "exceptions", the exceptions XML element is added. Its XML sub-elements represent the exception VEVENT or VTODO objects.

Example:
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
BEGIN:VEVENT
UID:566852630.4@mail.example.com
RECURRENCE-ID:20051206T180000Z
SUMMARY:test - recurrent (later this time)
DTSTART;TZID=NorthAmerica/Pacific:20051206T120000
DTEND;TZID=NorthAmerica/Pacific:20051206T130000
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>
  <exceptions>
    <uid>566852630.4@mail.example.com</uid>
    <recurrenceId>20051206T180000Z</recurrenceId>
    <summary>test - recurrent (later this time)</summary>
    <dtstart tzid="NorthAmerica/Pacific">20051206T120000</dtstart>
    <dtend tzid="NorthAmerica/Pacific">20051206T130000</dtend>
  </exceptions>
</vevent>

vfreebusy

These XML elements represent VFREEBUSY objects.

Attributes:
dtstart
the start time of the time period covered with this VFREEBUSY object.
dtend
the end time of the time period covered with this VFREEBUSY object.
dtstamp
the time when this VFREEBUSY object was composed.

Body:
a set of freebusy XML elements, each representing one time interval. Time intervals are not intersecting.

Attributes:
dtstart
the start time of the time interval.
dtend
the end time of the time interval.
fbtype
the optional busy-type status. If not specified, the time interval has the BUSY status.

Example:
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

This XML element represents an recurrence object.
Attributes:
freq
the recurrence type.
interval
the interval parameter. If absent, interval is assumed to be 1.
wkst
the week start day name. If absent, the MO (Monday) is assumed.
count
an optional integer attribute specifying the COUNT parameter.
until
an optional attribute specifying the UNTIL parameter in the iCalendar date-time format.

Body:
a set of XML elements:
BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYSETPOS
each element body contains a number - the month number, the week number, etc. Except for the BYMONTH element, the number can be negative.
BYDAY
each element body contains one day name (MO, TU, .. SU); each element can contain an optional numeric week attribute - the week number (it can be negative).

Example:

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>

Example:
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU

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

sdp

This XML element represents an SDP object.
Attributes:
ip
the default media IP address (optional).
origUser
the username field of the session origin (optional).
sessionID
the sess-id field of the session origin.
sessionVersion
the sess-version field of the session origin.
origIP
the IP address specified in the nettype, addrtype, and unicast-address fields of the session origin.
subject
the session subject (optional). If missing the - subject is used.

Body:
a set of media and/or attribute elements.

media

This XML element represents an SDP Media object.
Attributes:
media
the media type (such as audio, video). If this attribute is missing, the audio value is used.
ip
the media address and port.
protocol
the media protocol (such as udp, tcp, RTP/AVP). If this attribute is missing, the RTP/AVP value is used.
direction
the media direction (sendrecv, sendonly, recvonly, inactive).

Body:
a set of codec and/or attribute elements.

codec

This XML element represents an SDP Media codec.
Attributes:
id
the codec ID - the RTP payload number (a number in the 0..127 range).
name
the codec name (such as PCMU/8000).
format
the codec format parameter.

attr

This XML element represents an SDP or SDP Media attribute.
Attributes:
name
the attribute name.

Body:
an attribute value string.

Example: a sample SDP document and its XML presentation:
v=0
o=- 6385718 9999 IN IP4 192.168.1.65
s=-
c=IN IP4 192.168.1.65
t=0 0
a=sdpattr:sdpvalue
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
a=mediaattr:mediavalue

<sdp ip="[192.168.1.65]" origUser="-" sessionID="6385718" sessionVersion="9999" originIP="[192.168.1.65]">
  <attr name="sdpattr">sdpvalue</attr>
  <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" />
    <attr name="mediaattr">mediavalue</attr>
  </media>
</sdp>

ASN.1

CommuniGate Pro can convert ASN.1 structures into generic objects.

Each ASN.1 data element is converted into an array.

For ASN.1 data elements of the Universal class, the array element number 0 is a string with the data element type: boolean, integer, bits, octets, null, oid, objdescr, external, real, enum, embed, string, reloid, rsrv1, rsrv2, seq, set, stringNum, stringPrint, stringT61, stringIA5, string22, timeUTC, time, stringGraphic, stringISO64, stringGeneral, stringUniversal, string29, stringBMP, string31.
Otherwise the array element number 0 is a string with the data element class (application, choice,private), and the array element number 1 is a number - the data element type code.

For "constructed" data elements, the remaining zero or more array elements contain converted ASN.1 data sub-elements.
For "primitive" data elements, the remaining array element contain the the data element presentation, which depends on the data element type:

boolean
a Null object for "false", any other object for "true"
integer, enum (not more than 8 bytes long)
a Number
null
a Null object
string, subtypestring (the data does not contain a binary zero)
a String
time, timeUTC
a Time Stamp
oid, reloid
a String representing the ObjectID (nn.mm.ll.kk.rr)
all other data types
a Datablock
CommuniGate® Pro Guide. Copyright © 1998-2012, Stalker Software, Inc.