Atomic objects are unstructured, generic data-type objects.
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 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 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 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 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
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.
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.
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:
- ()
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:
- {}
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.
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.
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.
A datablock is presented as a base64 XML element.
The XML element body is the base64-encoded datablock content.
- Example:
- <base64>STYRyui=</base64>
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>
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>
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>
A null-value object is presented as an empty null XML element.
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>
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>
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>
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>
This XML element represents an iCalendar object.
- Body:
- a vCalendar element.
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.
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>
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>
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>
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>
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.
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.
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.
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>
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.