Version 5.1

Introduction Installation SysAdmin Network Objects E-mail Signals Access Services Directory Clusters Applications Miscellaneous Licensing   WebMail PBX

Applications Data CLI/API Rules CG/PL PBXApp XIMSS WebApp WSSP Helpers XIMSS Protocol Protocol and Message Syntax Login Operations Service Operations Mailbox Management Mailbox Operations Message Operations Contacts Operations Calendar Operations Signalling Instant Messaging Roster and Presence Preferences File Storage Operations Automated Rule Management Real-Time Application Management Directory XML Data Formats Array Dictionary EMail MIME vCard iCalendar sdp HTTP Access Message Part Retrieval File Uploading The CommuniGate Pro Server implements the XML Interface to Messaging, Scheduling and Signalling (XIMSS) protocol. The Interface is implemented with the XIMSS module supporting TCP/IP networks. The protocol session examples use the S: marker to show the data sent by the Server, and the C: marker to show the data sent by a Client.

Protocol and Message Syntax

XML API clients should open clear-text or secure TCP connections to the CommuniGate Pro Server XML module. When a connection is established, both sides can send and receive messages.
Each message is a text string ending with a binary zero byte.

Each message should be formatted as an XML document.

A client asks the Server to take actions and/or to retrieve data by sending a request message. Each request message must contain the id attribute.

When the Server completes the requested operation, it sends back a response message:

response

attributes:

id

the same as the id attribute of the request message.

errorText

this optional attribute is present only if the operation has failed. It contains the error message text.

errorNum

this optional attribute is present only if the operation has failed. It contains the numeric error code.

Examples:

C:<noop id="A001"/>
S:<response id="A001"/>
C:<myCommand id="A002" myParam="user1@example.dom" />
S:<response id="A002" errorText="unknown command" errorNum="500" />

A client can send the next request message without waiting for the current request response (pipelining).

The Server can send data messages to the client:

when it processes a client request message;
these messages are sent before the response message is sent;
these messages include the same id attribute as the request message.

when an asynchronous Server event (such as arrival of an Alert or an Instant Message) is delivered to the client session.
these messages do not include any id attribute.

Examples:

C:<noop id="A001"/>
S:<alert>Account is over quota</alert>
S:<response id="A001"/>
S:<alert>Please logout, as we are shutting down.</alert>

Note: a Client must send some command to the Server at least once in 10 minutes, otherwise the Server closes the connection.

Login Operations

After a connection with the Server is established, the client can perform only the operations listed in this section, till the login operation succeeds.

listFeatures

This operation tells the server to return the set of the available communication and authentication options.

attributes:

domain

the name of the target Domain. If not specified, Server takes the IP Address the client has connected to and selects the Domain this address is assigned to.

starttls

This operation tells the server to establish SSL/TLS security on this connection.

attributes:

domain

the name of the target Domain. If not specified, Server takes the IP Address the client has connected to and selects the Domain this address is assigned to.

If the server returns a positive response, the client should start SSL/TLS negotiations immediately.

login

attributes:

method

this attribute specifies the SASL method to use. If this attribute is missing the clear-text (password) method is used.

authData

If the clear-textmethod is used, this attribute contains the username.
For all other methods, this is a string with base64-encoded SASL protocol data.

password

This attribute is used for the clear-textmethod only, it contains the user password in the clear-text form.

The Server sends the following data messages:

features

This message is sent when the Server processes the listFeatures operation.

body: a set of XML elements:

sasl

the text body of this element is the name of the SASL mechanism enabled for the target domain.

starttls

if this element is present, the client can perform the starttls operation.

session

This message contains information about the newly created session. It is sent before the positive response for the login operation is sent.

attributes:

urlID

the session ID string. This ID string can be used to access session data via HTTP.

userName

the authenticated Account full name (accountName@domainName).

realName

the authenticated Account user Real Name (this attribute is absent if the Real Name is not specified in the Account Settings).

Examples:

C:<login id="A001" authData="user1@example.dom" password="123rtu" />
S:<session urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

C:<login id="A001" authData="user1@example2.dom" password="rrr123" />
S:<response id="A001" errorCode="account has been moved to a remote system" errorNum="518" />

When the specified SASL method involves sending a challenge to the client, it is sent as a challenge data message, with the value attribute containing the base64-encoded SASL protocol challenge data.
The client should respond by sending an auth request with the same id attribute as one used in the login request, and the value attribute containing the base64-encoded SASL protocol response data.

Example (see RFC2195):

C:<login id="A001" method="CRAM-MD5" />
S:<challenge value="PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+" />
C:<auth id="A001" value="dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw" />
S:<session urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

Service Operations

The following operations can be used to manage the client-server connection.

noop

This operation does not do anything and it always succeeds.

bye

This operation does not do anything and it always succeeds. After the response message is sent to the client, the Server closes the connection and destroys the current session.

passwordModify

This operation modifies the Account Password and/or the Password Recovery E-mail Address. (if )

attributes:

oldPassword

the current Account password. The operation verifies this password before attempting any modification.

newPassword

this optional attribute specifies the new password. The password modification operation must be allowed for this Account

recoveryEMail

this optional attribute specifies the new password recovery E-mail.

SMIMEUnlock

This operation unlocks the Account Private Key stored on the Server.
When the Private Key is unlocked, the Server decrypts encrypted parts of messages retrieved using the folderRead operation.
The Server can also encrypt and/or digitally sign submitted messages.
Note: this operation transfers the unlocking string ("storage password") in clear text. The client application should use this command only over a secure (TLS) connection.
Note: the Private Key is unlocked for the current session only. If a different session is opened for the same Account, it should unlock the Private Key by itself. The Private Key is automatically re-locked after the specified period of time.

attributes:

password

the unlocking string (password).

duration

the time (in second) to keep the Private Key unlocked. If this attribute is not specified, the Private Key is unlocked for 180 seconds (3 minutes).

SMIMEModifyPassword

This operation changes the password string protecting the Account Private Key in the Server storage. The Account Private Key must be unlocked.
Note: this operation transfers the unlocking string ("storage password") in clear text. The client application should use this command only over a secure (TLS) connection.

attributes:

password

the new unlocking string (password).

SMIMELock

This operation locks the Account Private Key stored on the Server.

clearUploaded

This operation removes one or all files from the "uploaded file set".

attributes:

uploadID

if this optional parameter is specified, only the file with this fileID is removed from the "uploaded file set".
If this parameter is not specified, all files are removed from the "uploaded file set".

readStrings

This operation reads the vocabulary (words, tags, button names, etc.) stored on the Server. The Server sends a strings data message with the dictionary data (see below).

attributes:

language

this optional parameter specifies the dictionary language.

readTime

This operation reads the current time from the Server. The Server sends a currentTime message.

readStatus

This operation reads the current Account status. The Server sends a currentStatus message.

listKnownValues

This operation causes the Server to send a knownValues message. This message contains sets of "known values": known Time Zone names, character set names, etc.

cliExecute

This operation executes a Network CLI command.

body:

the CLI command text

If the CLI command produces a result, the Server sends a cliResult message.

retrieveXML

This operation reads an XML document from a remote server.

attributes:

url

the URL (http: or https:) of the XML document.

If the document is successfully retrieved, the Server sends a retrievedXML message with the retrieved document content.

The Server can send the following service data messages at any time:

alert

The authenticated account has received an Alert. As soon as the Server sends the Alert data message to the Client, the Alert message is marked as "confirmed".

attributes:

body:

the Alert text (in the UTF-8 encoding).

The Server can send the following data messages:

strings

These messages are sent when the Server processes the readStrings request.

attributes:

body:

a set of string and strings XML sub-elements. Each subelement has the name attribute - the name (or "key") of the vocabulary element.
String vocabulary elements are presented using string sub-elements. The string sub-element body is the vocabulary element value.
Dictionary vocabulary elements are presented using strings sub-elements. The strings sub-element body is the set of string sub-sub-elements.

Example:
The Client reads the default (english) vocabulary.

C:<readStrings id="A001">
S:<strings>
  <string name="AppendButton">Append</string>
  <strings name="AppendModes">
    <string name="simple">Simple Mode</string>
    <string name="advanced">Advanced Mode</string>
  </strings>
</strings>
S:<response id="A001"/>

currentTime

These messages are sent when the Server processes the readTime request.

attributes:

gmtTime

the current Server time (GMT).

localTime

the current Server time (in the selected time zone).

currentStatus

These messages are sent when the Server processes the readStatus request.

body: a set of XML elements:

messageStore

The information about the Account Message Storage.

attributes:

used

the currently used storage (in bytes).

limit

the storage quota. This attribute is absent if the quota is set to Unlimited.

PrevLogin

The information about the previous successful login.

attributes:

gmtTime

the login time (GMT).

ip

the network address from which the user logged in.

LastFailedLogin

The information about the last failed login.

attributes:

gmtTime

the time of the last failed login attempt (GMT).

ip

the network address from which the failed attempt to log in was made.

RulesAllowed, SignalRulesAllowed, RPOPAllowed, PWDAllowed

The effective Account settings data. These elements do not have attributes, and their text body is the setting value.

knownValues

These messages are sent when the Server processes the listKnownValues request.

the message body contains the following XML elements:

tzid

the element name attribute specifies the name of a known Time Zone;

charset

the element name attribute specifies the name of a known character set;

cliResult

These messages are sent when the Server processes the cliExecute request.

body:

text presentation of the CLI command output.

retrievedXML

These messages are sent when the Server processes the retrieveXML request.

attributes:

url

the document URL.

body:

one sub-element with the retrieved document.

Mailbox Management

A client can use the following set of operations to manipulate Mailboxes in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).

Note: all non-ASCII mailbox names are specified using the UTF-8 charset (and not the IMAP UTF-7 encoding method).

mailboxCreate

This operation creates a new Mailbox.

attributes:

mailbox

this attribute specifies the new mailbox name.

mailboxClass

this optional attribute specifies the mailbox class.

mailboxRename

This operation renames a Mailbox.

attributes:

mailbox

this attribute specifies the existing mailbox name.

newName

this attribute specifies the new mailbox name.

children

if this optional attribute is present, all mailbox "children" (nested mailboxes) are renamed, too.

mailboxRemove

This operation removes a Mailbox.

attributes:

mailbox

this attribute specifies the existing mailbox name.

children

if this optional attribute is present, all mailbox "children" (nested mailboxes) are removed, too.

mailboxList

This operation makes the Server send a mailbox data message (see below) for each visible Mailbox (the Mailboxes for which the authenticated Account has the lookup access right).

attributes:

filter

this optional attribute specifies the filter string in the IMAP protocol format.

The Server sends the following data messages:

mailbox

These messages are sent when the Server processes the mailboxList request.

attributes:

mailboxName

the mailbox name.

UIDVALIDITY, MESSAGES, UIDNEXT, UNSEEN, INTERNALSIZE, OLDEST, CLASS, MEDIA, UNSEENMEDIA

standard and extended IMAP mailbox attributes

pureFolder

this attribute exists and has the YES value is the mailbox is a pure folder - i.e. it cannot contain messages, but it can contain sub-mailboxes.

Mailbox Operations

A client can use the following operations to process a Mailbox in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).

folderOpen

This operation opens the specified mailbox as a "Folder".
A Folder represents a Server mailbox, with all messages being sorted and, optionally, filtered.
Each folder has a name, and one session cannot have two folders with the same name. On the other hand, the same session can open the same mailbox as two different folders (with different names). For example, an application may use one folder to show the mailbox content sorted by the Date field, while maintaining a separate window where it shows the same mailbox, but only the messages containing the Business tag in the Keywords field, with all these messages sorted by the From field.
When mailbox messages are added, removed, or updated, the Server reports these updates to all clients that have opened that mailbox as a folder.
Each folder sends its update notifications independently, so the client does not need to know that two folders are presenting different views on the same Server mailbox.

attributes:

folder

the name for the new Folder to be opened. A client can use an arbitrary string as a Folder name.

mailbox

the mailbox name. If this attribute is not specified, the folder name is used.

sortField

the name of a message RFC822 header field to use for mailbox sorting.
the special names INTERNALDATE, UID, SIZE, and FLAGS can be used to specify (fast) sorting using the message metadata attributes.
See the Mailboxes section for more information on the mailbox message flags.

sortOrder

if this optional attribute is specified and it has the desc value, the sorting order is reversed.

filter

if this optional attribute is specified, only the mailbox messages matching this attribute value are included into the folder.

filterField

if this optional attribute is specified, its value specifies the message header field to compare with the filter attribute. Only the messages containing the specified field and with the field value matching the filter attribute value are included into the folder.
If this attribute value is body, messages containing the filter attribute value in any message body part are included into the server view.
If this attribute is missing, messages containing the filter attribute value in message body part, or in any message header field are included into the server view.

body:

the request body should contain one or more <field> elements.
Each element body should contain a name of a header field to be retrieved for each message.
These fields are called viewer fields.
The special names INTERNALDATE, UID, SIZE, FLAGS can be used to instruct the Server to retrieve message metadata attributes

A session can use several open Folders at the same time.

The client should maintain an internal "view" of the Folder and it should keep that view synchronized with the Server view implemented as a Folder.
Initially the internal view is a table with empty rows.

When a Folder is opened, the Server sends a folderReport data message containing the total number of messages in the Folder. This number is used by the client to create the initial internal view Table.

To display the mailbox content on the screen, the client checks which rows of its internal view table it should use. If some of those rows are empty, the client should ask the Server to send it the information about the Folder messages specified by their index values (positions) in the sorted view (in the Folder).

folderBrowse

This operation makes the Server send data messages for the specified index (position) interval in an open Folder.

attributes:

folder

the Folder name.

indexFrom

the index ("view" position) of the first message to send. Specify 0 to retrieve the first message in the view.

indexTill

the index ("view" position) of the last message to send.

The Server sends a folderReport data message for each position in the specified range. The data message attributes specify the message index (position) in the Folder and the message UID.
The folderReport data message body contains the viewer fields values.
If INTERNALDATE, Date, Resent-Date fields are present, they contain the field or metadata GMT value. These elements also contain the localTime attribute specifying the field value in the Time Zone selected for the current user.

The "on demand" client-server synchronisation model is used. When a message in a Folder is modified, added, or deleted, the client gets a folderReport data message with the mode attribute value set to notify.

The newly added messages do not become visible in the Folder and the deleted messages are not removed from the Folder. Requests to retrieve data from a deleted message return no data items or empty data items.

When the client application is ready to update its internal mailbox view, it should send a folderSync request:

folderSync

This operation tells the Server to send all mailbox modifications to the client.

attributes:

folder

the Folder name.

The Server sends folderReport data messages. The data message mode attribute has the removed, added, or updated value.

After a folderReport notify-mode data message has been sent and before the Server receives the folderSync request, the Server may not sent new folderReport notify-mode data messages when more changes take place in the mailbox.

The client can send requests to the Server asking for certain update operations (such as message deletion), but it should update its internal view only when the Server sends it a folderReport data message informing the client about actual changes in the mailbox.

messageCopy

This operation copies messages from an open Folder to a target mailbox.
Note: the target is specified as a mailbox, not as a Folder.

attributes:

folder

the source Folder name.

targetMailbox

the target mailbox name.

body:

a UID-set (see below).

messageMark

This operation modifies mailbox message flags in an open folder.

attributes:

folder

the Folder name.

flags

this attribute specifies the mailbox message flags to add or delete. Several operations can be specified, separated with the comma symbol. See the Mailbox section for more details.

body:

a UID-set (see below).

A UID-set is a set of UID XML elements. Each element body is a number - a UID of a mailbox message to use in the request.

folderExpunge

This operation removes all messages marked with the Deleted flag from the Folder mailbox.
Note: it removes ALL marked mailbox messages, not only the messages visible in this Folder.

attributes:

folder

the Folder name.

folderClose

This operation closes an open Folder.

attributes:

folder

the Folder name.

The Server sends the following data messages:

folderReport

These messages are sent when a Folder is opened, when a Folder status changes (messages are added, removed, or updated), when the client sends a folderBrowse or a folderSync request.

attributes:

folder

the Folder name.

mode

this optional attribute specifies the type of notification.

• If the attribute value is init then the messages attribute specifies the total number of messages in the Folder.
  This data message is sent when a Folder is being opened.
• If the attribute value is removed then the index and UID attributes specify the message removed from the Folder.
  This data message is sent only in response to the folderSync request.
  The client should immediately update its internal mailbox view: for all messages with the index value larger than the specified index attribute value, the index value is decreased by 1.
• If the attribute value is added then the index and UID attributes specify the message added to the Folder.
  This data message is sent only in response to the folderSync request.
  The client should immediately update its internal mailbox view: for all messages with the index value equal or larger than the specified index attribute value, the index value is increased by 1.
• If the attribute value is updated or the attribute is missing, then the index and UID attributes specify a mailbox message and the body contains the message viewer field values.
• If the attribute value is notify some mailbox message(s) were added, modified, or deleted.
  The client is expected to send the folderSync request for this Folder.

index

the message index in this Folder.
This attribute is not present when the mode attribute value is init.

UID

the message UID (unique ID).
This attribute is not present when the mode attribute value is init.

messages

the total number of messages in the Folder.
This attribute is present when the mode attribute value is init, removed, or added.

body:

The body is absent when the mode attribute value is init or remove.
In all other cases, the body contains a set of elements with viewer field values.

Example 1:

• A001: the Client asks the Server to open the INBOX mailbox as Folder "INBOX" and to sort it by the INTERNALDATE 'field' (this is not an actual message field, but a message metadata element - it specifies the time when the message was added into the mailbox). The Client informs the Server that it needs to retrieve the FLAGS, From, and Subject fields of mailbox messages.
• the Server opens the INBOX mailbox and sorts it; the Server informs the Client that the Folder has 234 messages.
• A002: the Client asks the Server to send it data from the first 4 Folder messages, and the Server sends that information to the Client.
• while the Server was processing this request, one message was added to the mailbox.
• after the Server has sent the response message, the Folder messages number 2 and 35 were deleted.
• A003: the Client asks the Server to send it data from the first 4 messages in the sorted view (again).
• A004: the Client asks the Server to send it all Folder modifications.
• The Server informs the Client about the message number 35 being removed. The Client should remove the element number 35 from its internal view table and update the information on its screen if necessary. The total number of Folder messages has changed to 233.
• The Server informs the Client about the message number 2 being removed. The Client should remove the element number 2 from its internal view table. The message number 3 becomes the message number 2, the message number 4 becomes the message number 3, etc.
• The Server adds a newly added message to the Folder and informs the Client that it has instered the message as the message number 1. The Client should update its internal view table by inserting a new element as the element number 1. The element number 1 becomes the element number 2, the element number 2 becomes the element number 3, etc.
• A005: the Client asks the Server to send it data from the first 4 messages in the Folder (again).

C:<folderOpen id="A001" folder="INBOX" mailbox="INBOX" sortField="INTERNALDATE" sortOrder="asc">
   <field>FLAGS</field><field>From</field><field>Subject</field>
  </folderOpen>
S:<folderReport folder="INBOX" mode="init" messages="234" />
S:<response id="A001"/>

C:<folderBrowse id="A002" folder="INBOX" indexFrom="0" indexTill="3" />
S:<folderReport folder="INBOX" index="0" UID="123">
   <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From><Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="1" UID="543">
   <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From><Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="2" UID="343">
   <FLAGS>Seen,Media</FLAGS><From>&lt;user@example.com&gt;</From><Subject>Meeting reminder</Subject>
  </folderReport>
S:<folderReport folder="INBOX" mode="notify">
S:<folderReport folder="INBOX" index="3" UID="512">
   <FLAGS>Seen,Flagged</FLAGS><From>&lt;Admin@hq.example.com&gt;</From><Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A002" />

S:<folderReport folder="INBOX" mode="notify">

C:<folderBrowse id="A003" folder="INBOX" indexFrom="0" indexTill="3" />
S:<folderReport folder="INBOX" index="0" UID="123">
   <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From><Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="1" UID="543">
   <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From><Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="2" UID="343">
   <FLAGS>Seen,Media</FLAGS><From></From><Subject></Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="3" UID="512">
   <FLAGS>Seen,Flagged</FLAGS><From>&lt;Admin@hq.example.com&gt;</From><Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A003" />

C:<folderSync id="A004" folder="INBOX" />
S:<folderReport folder="INBOX" index="35" UID="117" mode="deleted" messages="233" />
S:<folderReport folder="INBOX" index="2" UID="343" mode="deleted" messages="232" />
S:<folderReport folder="INBOX" index="1" UID="976" mode="added" messages="233" >
   <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From><Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<response id="A004" />

C:<folderBrowse id="A005" folder="INBOX" indexFrom="0" indexTill="3" />
S:<folderReport folder="INBOX" index="0" UID="123">
   <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From><Subject>Hello - just a test</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="1" UID="976">
   <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From><Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="2" UID="543">
   <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From><Subject>This is the best offer!</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="3" UID="512">
   <FLAGS>Seen,Flagged</FLAGS><From>&lt;Admin@hq.example.com&gt;</From><Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A005" />

Example 2:

• A010: the Client asks the Server to copy 3 messages from the already opened INBOX mailbox to the Archive mailbox.
• The Archive mailbox appears to be opened, and the Server sends a mailbox notification message to the Client:

C:<messageCopy id="A010" folder="INBOX" targetMailbox="Archive">
   <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageCopy>
S:<folderReport folder="Archive" mode="notify">
S:<response id="A010"/>

Example 3:

• A020: the Client asks the Server to mark 3 messages (UIDs 512, 123, and 976) with the Deleted flag.
• The Server sets these flags, and it sends a mailbox notification message to the Client.
• A021: the Client asks the Server to send it all mailbox modifications.
• The Server sends the updated information for the messages with UID 512 and 976. The message with the UID 123 already had the Deleted flag set, so this request has not modified that message and the Server does not send information for this message.
• A022: the Client asks the Server to expunge the mailbox.
• The Server deletes the messages with UIDs 512, 123, and 976, as well as message with UIDs 446 and 756 which also happened to have the Deleted flag set. The Server sends a mailbox notification message to the Client.
• A023: the Client asks the Server to send it all mailbox modifications.
• The Server sends data messaging informing the client that it has removed the messages with UIDs 512, 123, 976, 446, and 756 from its sorted mailbox view.
• A024: the Client closes the INBOX mailbox.

C:<messageMark id="A020" folder="INBOX" flags="Deleted">
   <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageMark>
S:<folderReport folder="INBOX" mode="notify">
S:<response id="A020"/>

C:<folderSync id="A021" folder="INBOX" />
S:<folderReport folder="INBOX" index="1" UID="976" mode="updated" >
   <FLAGS>Recent,Deleted</FLAGS><From>CGatePro Discussions</From><Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>
S:<folderReport folder="INBOX" index="3" UID="512" mode="updated" >
   <FLAGS>Seen,Deleted,Flagged</FLAGS><From>&lt;Admin@hq.example.com&gt;</From><Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>
S:<response id="A021"/>

C:<folderExpunge id="A022" folder="INBOX" />
S:<folderReport folder="INBOX" mode="notify">
S:<response id="A022"/>

C:<folderSync id="A023" folder="INBOX" />
S:<folderReport folder="INBOX" index="0" UID="123" mode="deleted" messages="232" />
S:<folderReport folder="INBOX" index="0" UID="976" mode="deleted" messages="231" />
S:<folderReport folder="INBOX" index="29" UID="446" mode="deleted" messages="230" />
S:<folderReport folder="INBOX" index="123" UID="756" mode="deleted" messages="229" />
S:<folderReport folder="INBOX" index="1" UID="512" mode="deleted" messages="228" />
S:<response id="A023"/>

C:<closeMailbox id="A024" folder="INBOX" />
S:<response id="A024"/>

Message Operations

A client can use the following set of operations to retrieve Messages from Mailboxes.

folderRead

This operation tells the Server to retrieve a Message or its part.

attributes:

folder

the Folder name.

UID

the message UID.

totalSizeLimit

the maximum total size of all message parts returned.

body:

messageAppend

This operation tells the Server to compose a Message and append it to an existing mailbox.

attributes:

targetMailbox

the target mailbox name.

mailboxClass

if the target mailbox does not exist and this optional attributes is specified, the target mailbox name is created. If this attributes value is a non-empty string, it is assigned as the Mailbox Class to the newly created mailbox.

flags

this optional attribute specifies the message flags the newly created message will have in the mailbox. Several flags can be specified, separated with the comma symbol. See the Mailbox section for more details.

internalDate

this optional attribute specifies the "internal timestamp" for the newly created message. If this parameter is not specified, the current time is used.

body:

The XML presentation of the Message (the EMail data).
The text parts of the message XML presentation should use the Line Feed (0x0A) symbol as the EOL (end of line) symbol.
If the XML presentation does not include the Message-ID or Date fields, the server creates these message fields itself.

Example:

The Client appends a simple text message to the mailbox "Sent", with the Seen and Answered flags. If the mailbox does not exist, it is created.

C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" mailboxClass="" >
  <EMail>
    <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
    <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
    <MIME type="text" subtype="plain">Dear Susan,&#0A;&#0A;I will come to your place tomorrow, thank you for the invitation!&#0A;Mary.&#0A;</MIME>
  </EMail>
</messageAppend>
S:<response id="A001"/>

This operation adds the following message to the mailbox:

From: "Sender Name" <fromName@domain> Subject: I'll be there! To: "Recipient Name" <toName@domain> X-Mailer: SuperClient v7.77 Date: Wed, 21 Jun 2006 21:51:24 -0800 Message-ID: <ximss-38150012@this.server.dom> Content-Type: text/plain; charset="utf-8" Dear Susan, I will come to your place tomorrow, thank you for the invitation! Mary.

To create messages with file attachments, put the files into the "uploaded file set" first. Then you can specify them in the MIME elements by using the uploadID attribute.

Example:

The Client first uploads 2 files - test.gif (using uploadID att01) and sample.pdf (using uploadID att02). Then the client appends a message to the "Drafts" mailbox, with the "Draft" message flag.
The message contains some text in the alternative (plain and html) formats, and the uploaded files as attachments. The client then clears the "uploaded file set".

C:<messageAppend id="A001" targetMailbox="Drafts" flags="Draft">
  <EMail>
    <From realName="Sender Name">fromName@domain</From><Subject>Text with attachments</Subject>
    <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
    <MIME type="multipart" subtype="mixed">
      <MIME type="multipart" subtype="alternative">
        <MIME type="text" subtype="plain">Dear Susan,&#0A;&#0A;I will come to your place tomorrow, thank you for the invitation!&#0A;Mary.&#0A;</MIME>
        <MIME type="text" subtype="html">&lt;html&gt;&lt;body&gt;&lt;i&gt;Dear Susan,&lt;/i&gt;&lt;p&gt;I will come to your place tomorrow, thank you for the invitation!&lt;p&gt;&lt;i&gt;Mary.&lt;/i&gt;</MIME>
      </MIME>
      <MIME uploadID="att01" />
      <MIME uploadID="att02" />
    </MIME>
  </EMail>
</messageAppend>
S:<response id="A001"/>
C:<clearUploaded id="A002" />
S:<response id="A002"/>

This operation adds the following message to the mailbox:

From: "Sender Name" <fromName@domain> Subject: Text with attachments To: "Recipient Name" <toName@domain> X-Mailer: SuperClient v7.77 Date: Wed, 21 Jun 2006 21:59:55 -0800 Message-ID: <ximss-38330025@my.server.domain> Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_" --_===38330025====my.server.domain===_ Content-Type: multipart/alternative; boundary="_===38330025-X====my.server.domain===_" --_===38330025-X====my.server.domain===_ Content-Type: text/plain; charset="utf-8" Dear Susan, I will come to your place tomorrow, thank you for the invitation! Mary. --_===38330025-X====my.server.domain===_ Content-Type: text/html; charset="utf-8" <html><body><i>Dear Susan,</i><p>I will come to your place tomorrow, thank you for the invitation!<p><i>Mary.</i> --_===38330025-X====my.server.domain===_-- --_===38330025====my.server.domain===_ Content-Type: image/gif; name="test.gif" Content-Disposition: attachment; filename="test.gif" Content-Transfer-Encoding: base64 R0lGODlhCgAMAPf/AP//////zP//mf//Zv//M///AP/M///MzP/Mmf/MZv/MM//MAP+Z//+Z zP+Zmf+ZZv+ZM/+ZAP9m//9mzP9mmf9mZv9mM/9mAP8z//8zzP8zmf8zZv8zM/8zAP8A//8A zP8Amf8AZv8AM/8AAMz//8z/zMz/mcz/Zsz/M8z/AMzM/8zMzMzMmczMZszMM8zMAMyZ/8yZ zMyZmcyZZsyZM8yZAMxm/8xmzMxmmcxmZsxmM8xmAMwz/8wzzMwzmcwzZswzM8wzAMwA/8wA zMwAmcwAZswAM8wAAJn//5n/zJn/mZn/Zpn/M5n/AJnM/5nMzJnMmZnMZpnMM5nMAJmZ/5mZ zJmZmZmZZpmZM5mZAJlm/5lmzJlmmZlmZplmM5lmAJkz/5kzzJkzmZkzZpkzM5kzAJkA/5kA zJkAmZkAZpkAM5kAAGb//2b/zGb/mWb/Zmb/M2b/AGbM/2bMzGbMmWbMZmbMM2bMAGaZ/2aZ zGaZmWaZZmaZM2aZAGZm/2ZmzGZmmWZmZmZmM2ZmAGYz/2YzzGYzmWYzZmYzM2YzAGYA/2YA zGYAmWYAZmYAM2YAADP//zP/zDP/mTP/ZjP/MzP/ADPM/zPMzDPMmTPMZjPMMzPMADOZ/zOZ zDOZmTOZZjOZMzOZADNm/zNmzDNmmTNmZjNmMzNmADMz/zMzzDMzmTMzZjMzMzMzADMA/zMA zDMAmTMAZjMAMzMAAAD//wD/zAD/mQD/ZgD/MwD/AADM/wDMzADMmQDMZgDMMwDMAACZ/wCZ zACZmQCZZgCZMwCZAABm/wBmzABmmQBmZgBmMwBmAAAz/wAzzAAzmQAzZgAzMwAzAAAA/wAA zAAAmQAAZgAAM+4AAN0AALsAAKoAAIgAAHcAAFUAAEQAACIAABEAAADuAADdAAC7AACqAACI AAB3AABVAABEAAAiAAARAAAA7gAA3QAAuwAAqgAAiAAAdwAAVQAARAAAIgAAEe7u7t3d3bu7 u6qqqoiIiHd3d1VVVURERCIiIhEREQAAACH+HUdpZkJ1aWxkZXIgMC40IGJ5IFl2ZXMgUGln dWV0ACH5BAUEALkALAAAAAAKAAwAAAg1AHPlG0gw379cAgEoXHgw4UKFDfM9hIhQ4sSIEwFg vCiQ4L+PIC1m/Cfx34qQGkVeBMkSZEAAOw== --_===38330025====my.server.domain===_ Content-Type: application/pdf; name="sample.pdf" Content-Disposition: attachment; filename="sample.pdf" Content-Transfer-Encoding: base64 JVBERi0xLjIgDSXi48/TDQogDTggMCBvYmoNPDwNL0xlbmd0aCA5IDAgUg0vRmlsdGVyIC9G bGF0ZURlY29kZSANPj4Nc3RyZWFtDQpIic2X3VLjuBaFn6DfQXfDuaCP5X9fJiQEpkNI2eFQ [......skipped......] Ug0vSUQgWzxjNjIyNzFiYzY4YmFlYjY3YzBkM2ViNTk4MjJiZTA4Nz48YzYyMjcxYmM2OGJh ZWI2N2MwZDNlYjU5ODIyYmUwODc+XQ0+Pg1zdGFydHhyZWYNODc1NA0lJUVPRg0= --_===38330025====my.server.domain===_--

To create messages with MIME parts (attachments) copied from other messages stored on the Server, use the copyMIME element instead of a MIME element:

copyMIME

attributes:

folder or calendar

the name of an open Folder or Calendar.

UID

the message UID.

partID

this optional attribute specifies the message part to copy. If it is not specified, the entire message is copied.

body:

Example:

The Client stores a note in the "Notes" mailboxes, appending parts 3 and 4 (attachments) of the message 156 stored in the INBOX folder:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
  <EMail>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Vacation Pictures</Subject>
    <MIME type="multipart" subtype="mixed">
      <MIME type="text" subtype="plain">The first part of the underwater shots.</MIME>
      <copyMIME folder="INBOX" UID="156" partID="3"/>
      <copyMIME folder="INBOX" UID="156" partID="4"/>
  </EMail>
</messageAppend>
S:<response id="A001"/>

messageSubmit

This operation tells the Server to compose a Message and submit it to the Queue for delivery. A message copy can be stored in a mailbox.

attributes:

useDSN

if this optional attribute is present, delivery reports are generated when a message is delivered, or if delivery fails.
If this attribute is absent, delivery reports are generated only when message delivery fails.

targetMailbox, mailboxClass, flags, internalDate

if the optional targetMailbox attribute is specified the composed message is appended to the specified mailbox. These attributes have the same meaning as for the messageAppend operation.

body:

The XML presentation of the Message (the EMail element), and zero, one, or several Envelope-To elements. Each Envelope-To element should have a text body - the E-mail address to send the message to.
If no Envelope-To element is specified, the message is sent to the addresses specified in all To, Cc, and Bcc sub-elements of the EMail element.
When the message MIME text is generated, all EMail element Bcc sub-elements are skipped.

Example:

The Client sends a simple text message to the toName@domain address and the Bcc copy is sent to bccName@domain address. The Client requests delivery notification.

C:<messageSubmit id="A001" useDSN="yes" >
  <EMail>
    <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
    <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
    <Bcc>bccName@domain</Bcc>
    <MIME type="text" subtype="plain">Dear Susan,&#0A;&#0A;I will come to your place tomorrow, thank you for the invitation!&#0A;Mary.&#0A;</MIME>
  </EMail>
</messageSubmit>
S:<response id="A001"/>

Example:

The Client sends a simple text message to the a1@domain and a2@domain addresses (different from the addresses specified in the To and Cc sub-elements).
The message copy should be stored in the "Sent Items" mailbox with the "Seen" flag.
The Client requests delivery notification.

C:<messageSubmit id="A001" targetMailbox="Sent Items" flags="Seen" >
  <Envelope-To>a1@domain address</Envelope-To>
  <Envelope-To>a2@domain address</Envelope-To>
  <EMail>
    <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
    <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
    <Cc>ccName@domain</Bcc>
    <MIME type="text" subtype="plain">Dear Susan,&#0A;&#0A;I will come to your place tomorrow, thank you for the invitation!&#0A;Mary.&#0A;</MIME>
  </EMail>
</messageSubmit>
S:<response id="A001"/>

Example:

The Client forwards the message 156 stored in the INBOX folder to the a1@domain address:

C:<messageSubmit id="A001">
  <EMail>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Fwd: Sorry, I cannot make it :-(</Subject>
    <To realName="Recipient Name">a1@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
    <MIME type="multipart" subtype="mixed">
      <MIME type="text" subtype="plain">Dear Susan,&#0A;&#0A;Attached please find the message I received this morning...&#0A;Mary.&#0A;</MIME>
      <copyMIME folder="INBOX" UID="156" />
  </EMail>
</messageSubmit>
S:<response id="A001"/>

This operation adds the following message to the mailbox:

From: "Sender Name" <fromName@domain> Subject: Fwd: Sorry, I cannot make it :-( To: "Recipient Name" <toName@domain> X-Mailer: SuperClient v7.77 Date: Wed, 21 Jun 2006 22:55:24 -0800 Message-ID: <ximss-38150012@this.server.dom> Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_" --_===38330025====my.server.domain===_ Content-Type: text/plain; charset="utf-8" Dear Susan, Attached please find the message I received this morning... Mary. --_===38330025====my.server.domain===_ Content-Type: message/rfc822 From: "Barbara Smith" <barbara@domain> Subject: Sorry, I cannot make it :-( To: "Sender Name" <fromName@domain> X-Mailer: OtherClient v8.88 Date: Wed, 21 Jun 2006 21:51:24 -0800 Message-ID: <zzzzzzzzz@other.server.dom> Content-Type: text/plain; charset="utf-8" Mary, Sorry, but I will be out of town tomorrow... Barbara. --_===38330025====my.server.domain===_--

messageRedirect

This operation tells the Server to compose a copy of a message stored in a mailbox, and to submit it to the Queue for delivery.

attributes:

folder

the Folder name.

UID

the message UID.

body:

A set of one or more To elements specifying the recipient address(es).

Example:

The Client redirects the message 156 stored in the INBOX folder to the a1@domain and a2@domain addresses:

C:<messageRedirect id="A001" folder="INBOX" UID="156">
  <To realName="Recipient Name">a1@domain</To>
  <To realName="Recipient-2">a2@domain</To>
</messageRedirect>
S:<response id="A001"/>

messageForward

This operation tells the Server to compose a copy of a message stored in a mailbox, and to submit it to the Queue for delivery. The operation uses the same attributes as the messageRedirect operation.

messageConfirm

This operation tells the Server to compose an MDN (Message Delivery Notification) report for a message stored in a mailbox, and to submit it to the Queue for delivery.
Client applications should use this operation when:

• the message has been displayed to the user, and
• the message has the Disposition-Notification header field, and
• the message does not have the $MDNSent Message Flag, and
• the user Preference SendMDNMode is set to Automatically or it is set to Manually and the user has explicitly requirested to send a confirmation.

attributes:

folder

the Folder name.

UID

the message UID.

type

this attribute should be set to auto (if the confirmation is generated automatically) or to manual (if the user has explicitly requirested to send a confirmation).

The Server sends the following data messages:

folderMessage

These messages are sent when the Server processes the folderRead request.

attributes:

folder

the Folder name.

UID

the message UID.

body:

The XML presentation of the Message.

Contacts Operations

Contacts (vCard) information can be stored as an E-mail item in any Mailbox. A vCard data element can be attached (as a MIME part) to any E-mail message. Each message can contain several MIME parts each containing several vCard objects.

MIME parts with the text type and x-vcard or dictionary subtype contain vCard elements.

To include vCard data into a message message (using the messageAppend, messageSubmit operations) include a MIME element with type="text" and subtype="directory". The element body should contain one or more vCard elements.

The Contact-class Mailboxes are used to store special messages ("items") containing only vCard data. In a properly composed item:

• the Subject field contains the vCard FN property.
• the To field contains the vCard EMAIL property.
• the X-Has-Certificate field exists and contains the true value if the vCard contains a KEY property.

Use the following operations to compose and store such a special message:

appendVCard

This operation composes a special E-mail message containing the vCard data as its body, forms all necessary E-mail message header fields and stores the resulting message in the specified mailbox.

attributes:

targetMailbox

the target mailbox name.
if the target mailbox does not exist, it is created.

body:

exactly one vCard element.

The operation adds the vCard UID and FN attributes if they are missing.

Example 1:

The Client appends a vCard object to the Contacts mailbox.

C:<appendVCard id="A011" targetMailbox="Contacts" >
<vCard>
  <NAME>Bjorn Jensen</NAME>
  <N><FAMILY>Jensen</FAMILY><GIVEN>bjorn</GIVEN><MIDDLE>A</MIDDLE><PREFIX>Mr.</PREFIX><SUFFIX>II</SUFFIX></N>
  <EMAIL><INTERNET /><USERID>bjorn@domain.dom</USERID></EMAIL>
  <TEL><WORK /><VOICE /><MSG /><NUMBER>+1 313 747-4454</NUMBER></TEL>
  <KEY><x509 /><BINVAL>dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK</BINVAL></KEY>
</vCard>
</appendVCard>
S:<response id="A011"/>

Calendar Operations

A client can use the following operations to process a Calendar in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).

calendarOpen

This operation opens the specified mailbox as a "Calendar".
A Calendar represents a Server mailbox, with all messages being parsed and all calendaring information retrieved.
Each calendar has a name, and one session cannot have two calendars with the same name. On the other hand, the same session can open the same mailbox as two different calendars (with different names).

attributes:

calendar

the name for the new Calendar to be opened. A client can use an arbitrary string as a Calendar name.

mailbox

the mailbox name. If this attribute is not specified, the calendar name is used.

A session can use several open Calendars at the same time.

findEvents

This operation retrieves the VEVENT objects from the specified Calendar. Only the Events that fall into the specified time interval are retrieved.

attributes:

calendar

the Calendar name.

timeFrom, timeTill

the beginning and the end of the time interval (time values should be specified for the selected time zone).

limit

this optional numeric attribute limits the number of the Events returned.

skip

this optional numeric attribute specifies how many "to be returned" Events should be skipped. Using this attribute, a client can retrieve a large Event set in smaller "chunks".

The Server sends an events data message if at least one event is found in the specified time interval.

calendarClose

This operation closes an open Calendar.

attributes:

calendar

the Calendar name.

calendarRead

This operation tells the Server to retrieve a Message or its part.

attributes:

calendar

the Calendar name.

UID

the message UID.

totalSizeLimit

the maximum total size of all message parts returned.

calendarPublish

This operation places a calendaring item into a Calendar. The existing items(s) with the same UID are removed.

attributes:

calendar

the Calendar name.

sendRequests

if this optional attribute exists and its value is no, the item is stored without notifying participants.
Otherwide, a meeting or task request is sent to all participants, and, if there was an existing item with the same UID, Cancel requests are sent to all participants existing in the old item, but excluded from the new item.

body:

The iCalendar element to place into the selected Calendar, and optionalMIME and/or copyMIME elements to add (the same as elements used with the messageAppend operation).

The iCalendar element should contain optional vtimezone elements and exactly one calendaring item element.
It is possible not to include the vtimezone element for the time zone used in the calendaring item element if this time zone is one of the standard time zones known to the Server.
If the item does not contain an UID element, the Server generated a unique one and adds it to the item.

Example 1:
The Client published an iCalendar object to the Calendar calendar.

C:<calendarPublish id="A021" calendar="Calendar">
 <iCalendar xmlns="urn:ietf:params:xml:ns:xcal">
  <vCalendar method="PUBLISH" prodid="CommuniGate Pro 5.1.7" version="2.0">
   <vevent>
    <organizer CN="Big Boss">MAILTO:boss@company.dom</organizer>
    <attendee CN="Small Boy">MAILTO:boy@company.dom</attendee>
    <rrule>FREQ=WEEKLY;BYDAY=MO,TH</rrule>
    <dtstamp>20061022T091143Z</dtstamp>
    <uid>18927897984@kjjkjkjk-123444</uid>
    <sequence>0</sequence>
    <summary>Report Meeting</summary>
    <dtstart tzid="NorthAmerica/Pacific">20060515T100000</dtstart>
    <dtend tzid="NorthAmerica/Pacific">20060515T110000</dtend>
    <busystatus>BUSY</busystatus>
    <last-modified>20060516T034850Z</last-modified>
    <created>20060516T034850Z</created>
    <priority>5</priority>
    <description>A twice-a-week meeting to discuss the progress of the assigned projects.</description>
   </vevent>
  </vCalendar>
 </iCalendar>
 <MIME uploadID="att01" />
 <copyMIME folder="INBOX" UID="156" partID="3"/>
</calendarPublish>
S:<response id="A021"/> Note: If a time value is specified withtout the "Z" suffix, it is assumed to be a local time in the Time Zone selected for the current user.

calendarCancel

This operation removes a calendaring item from a Calendar. Cancel requests are sent to all participants.

attributes:

calendar

the Calendar name.

UID

the message UID.

body:

The iCalendar element to cancel.

If an iCalendar element is not specified, the item with the specified message UID (this is a number, and it is not the calendar item UID) is taken from the Calendar. Then all items with the same item UIDs are removed.

calendarUpdate

This operation updates a calendaring item in a Calendar using a reply-type iCalendar object.

attributes:

calendar

the Calendar name.

body:

The iCalendar element (its method should be set to REPLY). This element specifies if a particular attendee has accepted or rejected the invitation.

calendarAccept

This operation places a calendaring item into a Calendar. The existing items(s) with the same UID are removed.

attributes:

calendar

the Calendar name.

PARTSTAT

the acceptance status: ACCEPTED, TENTATIVE, IN-PROCESS (Tasks only), COMPLETED (Tasks only).

body:

The iCalendar element to place into the selected Calendar, and optionalMIME and/or copyMIME elements to add (the same as elements used with the messageAppend operation).

If the item is placed successfully, the iCalendar reply message is sent to the item origanizer. Replies are not sent for Event items specifying the current user as an attendee with RSVP=FALSE parameter.

calendarDecline

This operation rejects a calendaring item and sends a negative reply message to the item origanizer.

attributes:

calendar

the Calendar name. This parameter is optional. If specified, the items with the same UID are removed from this Calendar.

body:

The iCalendar element to decline.

The Server sends the following data messages:

events

These messages are sent when the findEvents operation is used.

attributes:

calendar, timeFrom, timeTill, skip

the same as in the findEvents request.

items

the total number of Events found.

body:

a set of the event elements for each Event found.

attributes:

UID

the Event message UID.

timeFrom

the time when this Event starts (in the selected time zone). This attribute is not included for "all-day" Events.

duration

the Event duration (in seconds). This attribute is not included for "all-day" Events.

busyStatus

the Event busy status (BUSY, TENTATIVE, UNAVAILABLE, FREE).

body:

Event fields: summary

Signalling

A client should use the "bind" operation to start receiving signals directed to the authenticated user.

A client can maintain one or several concurrent communication sessions ("calls"). Each call is identified with its callLeg identifier.

signalBind

This operation allows the current XIMSS session to receive signals directed to the authenticated user.

attributes:

deviceName

an optional parameter specifying the device used.

presence

an optional parameter. If set to yes, the client starts to receive Roster and Presence notifications.

body:

optional: the XML presentation of the client SDP descriptor.
The descriptor is used to specify the client capabilities (ability to accept audio/video calls) and to detect "far-end NAT" configurations.
Note: to detect "far-end NAT" configurations, the SDP descriptor must contain the ip attribute with the default media IP address used by the client (see below).

signalUnbind

After this operation is complete, the current XIMSS session does not receive signals directed to the authenticated user.

callKill

Use this operation to end the call and reslease all associated resources.
If the call was in the 'calling' state, the outgoing call is cancelled.
If the call was in the 'alerting' state, the incoming call is rejected.
If the call was in the 'connected' state, the disconnect signal is sent to the peer.

attributes:

callLeg

the call identifier.

After this operation succeeds, it is possible to create a new call with the same identifier.

callStart

Use this operation to start an outgoing call.

attributes:

callLeg

the new call identifier. The current XIMSS session should have no other call with this identifier.

peer

an E-mail address or a SIP URI to call.

body:

the XML presentation of the client SDP descriptor.

If this operation succeeds, the new call object is created and an outgoing call is initiated. The server may send zero, one, or several callProvisioned messages, followed by a callDisconnect or callConnected message.
Note: the client should be ready to process these Server messages even before the client receives the positive response for this callStart request.
Note: to process "behind-the-NAT" calls correctly, the SDP descriptor must contain the ip attribute with the default media IP address used by the client (see below).
Note: if the call fails (the callDisconnected message is received), the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

callProvision

Use this operation to provision an incoming call.

attributes:

callLeg

the incoming call identifier.

body:

optional: the XML presentation of the client SDP descriptor.

callRedirect

Use this operation to redirect an incoming call.

attributes:

callLeg

the incoming call identifier.

body:

one or more XML To elements. Each element should have a text body specifying a URI to redirect the call to.

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

Example:

Redirecting an incoming call inp003 to the user1@example.com and user2@example.com.

C:<callRedirect id="A018" callLeg="inp003" >
  <To>user1@example.com</To><To>user2@example.com</To>
</callRedirect>
S:<response id="A018"/>

callReject

Use this operation to reject an incoming call. You can also use the callKill operation, but this operation allows you to specify an error code.

attributes:

callLeg

the incoming call identifier.

signalCode

a numeric code (defined with the SIP standards) to pass the the signalling component as an error code.
Use the 486 code ("Busy here") to signal that this device is "busy" (but other devices registered for this user will continue to ring).
Use a 6xx code (600 - "Busy Everywhere" or 603 - "Declined") to signal that the user does not want to accept this call on any device (all other devices will stop ringing, too).

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

Example:

Rejecting an incoming call inp004 with the 603 "Declined" code:

C:<callReject id="A020" callLeg="inp004" signalCode="603" />
S:<response id="A020"/>

callAccept

Use this operation to accept an incoming call.

attributes:

callLeg

the incoming call identifier.

body:

the XML presentation of the client SDP descriptor.

callSendDTMF

Use this operation to send a DTMF signal via the signalling path.

attributes:

callLeg

the call identifier.

body:

a string with the DTMF code to send (10 for '*', 11 for '#').

callTransfer

Use this operation to transfer the connected peer to a different party.

attributes:

callLeg

the call identifier.

peer

an E-mail address or a SIP URI to transfer the call to. Use this attribute to initiate a "blind transfer" operation.

otherLeg

the call identifier. It should specify some other "call" in this session. Both calls should be in the 'connected' state. Use this attribute to complete an "attended transfer" operation. The remote peer of the "callLeg" call is connected to the remote peer of the "otherLeg" call.

If the otherLeg attribute is specified, the peer attribute is ignored.

If the call transfer operation succeeds, the "callLeg" call is disconnected (the callDisconnected message is sent to the client). Additionally, if the operation was the "attended transfer" one, the client receives the callDisconnected message for the "otherLeg" call, too.

The Server can send the following data messages:

callProvisioned

These messages are sent when there is an outgoing call in progress (after the callStart was received by the Server):

attributes:

callLeg

the call identifier.

body:

Optionally, the XML presentation of the provisioning response SDP.

callDisconnected

These messages are sent when an outgoing call fails, when an incoming call is cancelled, or when an established call disconnects:

attributes:

callLeg

the call identifier.

errorText

this optional attribute specifies the call disconnect reason.

signalCode

this optional attribute specifies the numeric signalling error code.

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

callConnected

These messages are sent when an outgoing call succeeds and the call is established:

attributes:

callLeg

the call identifier.

body:

The XML presentation of the remote party SDP.

callIncoming

These messages are sent when there new incoming calls are received (you need to use the signalBind operation to receive incoming calls):

attributes:

callLeg

the call identifier. The Server generates these identifiers itself.

body:

The XML presentation of the request SDP.

callOpFailed

These messages are sent when in-call operations (such as callSendDTMF) fail.

attributes:

callLeg

the call identifier.

errorText

the error message.

callDTMF

These messages are sent when a DTMF signal is received via the signalling path.

attributes:

callLeg

the call identifier.

body:

A string with the numeric DTMF code received.

Instant Messaging

The Instant Messaging (IM) model assumes that a client maintains a separate window for each "peer", where a "peer" is some other IM user taking part in an IM conversation.

sendIM

This operation sends an Instant Message to the specified user. The Server sends a XIMSS response without waiting till the Instant Message is actually delivered (or failed).
There is no explicit IM session opening operation. If the Server does not have an open IM session with the specified peer, a new session is created.

attributes:

peer

the E-mail address of the user to send this message to.

body:

the Instant Message text (in the UTF-8 encoding).

closeIM

A request to close all IM sessions with the specified user.
A client application should send this request when it closes an IM conversation window.

attributes:

peer

the user E-mail address.

The Server sends the following data messages:

readIM

The Server has received an Instant Message for the client user.

attributes:

peer

the sender E-mail address.

body:

the Instant Message text (in the UTF-8 encoding).

There is no explicit session opening operation. If the client has no open conversation window for the specified user, it should open a new one.

errorIM

The Server has failed to deliver an Instant Message.

attributes:

peer

the recipient E-mail address.

errorText

the error message text.

errorNum

the error message numeric code.

body:

the failed Instant Message text (in the UTF-8 encoding).

Roster and Presence

The Roster and Presence model resembles that of the XMPP protocol.

A Roster is a set of items, each item describing a "contact" - some other local or remote user. The user can monitor the presence information of a "contact", and a "contact" can be granted a right to monitor the user's presence information.

rosterList

This operation retrieves all active Roster items.

attributes:

The Server sends rosterItem data messages for all currently active Roster "contacts".

rosterSet

This operation modifies a Roster "contact".

attributes:

peer

the contact E-mail address.

subscription

an optional parameter:
• remove: remove the contact from the Roster.
• subscribed: confirm the contact request to monitor the user's presence information.
• unsubscribed: reject the contact request to monitor the user's presence information, or revoke the already granted right to monitor.
• subscribe: send a request to monitor the contact's presence information.
• unsubscribe: stop monitoring the contact's presence information.
• update or none: update the contact information.

name

an optional attribute specifying the Contact real name.

body:

a set of group XML elements; each element body specifies the name of a Group this contact belongs to.

the update, subscribed, and subscribe operations create a new Roster item if the item with the specified E-mail address does not exist.

presenceSet

This operation sets the user presence information. The Server aggregates the presence information reported by all currently connected clients (XIMSS, XMPP, SIP) and distributes it to all network entities subscribed to that information.

attributes:

type

this optional element may have the unavailable value. It indicates that the user is "virtually offline".
If this attribute is absent, the user is online.

body:

an optional show XML element; its text body specifies the detailed user presence status:

• dnd - do not disturb, busy, on-the-phone.
• away - will be right back, on a meeting, out-to-lunch.
• xa - away ("extended away").

When a session starts, the user is "virtually offline". The client should use this operation to indicate that the user is online.

When the user disconnects, its session status is automatically changed to unavailable (offline).

The Server sends the following data messages:

rosterItem

These messages are sent when the Server processes a rosterList request. One message is sent for each Roster item ("Contact").

attributes:

peer

the contact E-mail address.

subscription

• to: the user can monitor the contact.
• from: the contact can monitor the user.
• both: the user and the contact can monitor each other.
• none: the user and the contact do not monitor each other.

ask

this optional attribute has the subscribe value if the user has requested a subscription to the contact's presence information, but this request has not been confirmed yet.

name

an optional attribute specifying the Contact real name.

body:

a set of group XML elements; each element body specifies the name of a Group this contact belongs to.

If the signalBind operation was used to enable Roster and Presence notifications:

• Every time a Roster item is added or updated, the Server sends rosterItem messages with the new or updated data.
• Every time a Roster item is deleted, the Server sends the rosterItem message with the subscription attribute set to remove.
• The Server sends the presence data messages.

presence

attributes:

peer

the Contact E-mail address.

type

an optional attribute:

• unavailable: the contact is offline.
• subscribe: the contact is requesting subscription to the user's presence information.
• absent: the contact is online.

body:

an optional show XML element; its text body specifies the detailed contact presence status (see above).

Preferences

A client can retrieve and update the authenticated user Preferences.

prefsRead

This operation retrieves authenticated user Preferences.

attributes:

type

this is an optional parameter. If the specified value is default, the default Preferences for the Account Domain are retrieved. If the specified value is custom, the explicitly specified Account Preferences are retrieved. If the attribute is not specified, the effective Account Preferences are retrieved.

prefsStore

This operation retrieves authenticated user Preferences.

attributes:

body:

XML sub-elements, with the names equal to the Preference element names. The sub-element body contains the new Preference element value. If the value is the default string, the custom Preference value is removed, and the default value becomes the effective Preference element value.
If the value is an array, if should be presented using the array XML presentation.
If the value is a dictionary, if should be presented using the dictionary XML presentation.

The Server sends the following data messages:

prefs

This message is sent when the Server processes the prefsRead request.

attributes:

type

an optional attribute, the same as the request attribute.

body:

XML subelements, with the names equal to Preference element names. The subelement body contains the Preference element value.
If the value is an array, it is presented using the array XML presentation.
If the value is a dictionary, it is presented using the dictionary XML presentation.

File Storage Operations

A client can manage the Account File Storage.
If the authenticated user has the CanAccessWebSites Domain Administrator right, this client can manage files in someone else's Account by using the prefix when specifying file names: ~accountName/fileName.

fileList

This operation provides a list of stored files.

attributes:

directory

an optional attribute with the File Storage subdirectory name. If absent, the content of the Account top File Storage directory is returned.

The Server returns one fileInfo message for each file or directory in the specified File Storage directory.

fileWrite

This operation stores data in a file.

attributes:

fileName

the name of file to write to.

position

If this attribute is absent, then this operation completely rewrites the specified file. If the file did not exist, it is created.
If this attribute value is append, this operation adds the data to the file end (atomically).
If this attribute value is a number, the operation rewrites the existing file from the byte position specified with this number.

body:

Either a text with file data, or the base64 subelement. The body of the subelement is base64-encoded file data (base64 encoding allows you to store binary data).

fileStore

This operation stores an uploaded file as a File Storage file.

attributes:

fileName

the name of file to be created.

uploadID

a string identifing a file in the "uploaded file set".

If a file under this name already exists, the old file is removed first.

fileRead

This operation reads data from a file.

attributes:

fileName

the name of file to read from.

position

This numeric attribute specifies the file position to start reading from. If this attribute is absent, then the file is read from its start (from the file position 0).

limit

This numeric attribute specifies the maximim size of the file data portion to read. If not specified, 1MB limit is used.

type

If this optional attribute exists and its value is binary, the file data is returned base64-encoded.

The Server returns a fileData message.

fileRename

This operation removes a file or directory from the File Storage.

attributes:

fileName

the name of file or directory to rename.

fileName

the new name for the file or directory.

fileRemove

This operation removes a file or directory from the File Storage.

attributes:

fileName

the name of file or directory to remove. Only empty directories can be removed.

The Server sends the following data messages:

fileInfo

This message is sent when the Server processes the fileList request.

attributes:

fileName

the file or subdirectory name.

directory

an optional attribute, the same as the directory attribute in the fileList request.

type

an optional attribute exists and contains the directory value, if this message describes a subdirectory.

size

an optional attribute with the file size in bytes (absent if this message describes a subdirectory).

timeModified

an optional attribute with the file modification date and time (GMT).

fileData

This message is sent when the Server processes the fileRead request.

attributes:

fileName

the name of read file.

position

the file position of the read data.

slice

the size of read data (in bytes). To read the next portion of the file, add the position and slice values to get the new position value.

size

the file total size.

timeModified

an optional attribute with the file modification date and time (GMT).

body:

Either a text with file data, or the base64 subelement. The body of the subelement is base64-encoded file data (base64 encoding allows you to retrieve binary data).

Examples:

C:<fileRead id="A001" fileName="test.txt" />
S:<fileData fileName="test.txt"position="0" slice="22" size="22" timeModified="20061018T115836">This is not your file!</fileData>
S:<response id="A001"/>

C:<fileRead id="A002" fileName="test.txt" limit="15" />
S:<fileData fileName="test.txt"position="0" slice="15" size="22" timeModified="20061018T115836">This is not you</fileData>
S:<response id="A002"/>

C:<fileRead id="A003" fileName="test.txt" limit="15" position="15" />
S:<fileData fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836">r file!</fileData>
S:<response id="A003"/>

C:<fileRead id="A004" fileName="test.txt" limit="15" position="15" type="binary" />
S:<fileData fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836"><base64>ciBmaWxlIQ==</base64></fileData>
S:<response id="A004"/>

C:<fileRead id="A005" fileName="test.txt" position="25" />
S:<response id="A005" errorText="reading beyond the EOF mark" errorNum="500" />

Automated Rule Management

A client can manage the Account Automated Rules. Rules sets are addressed using the type parameter. The following parameter values are supported:

• mailIn - incoming E-mail (Queue) Rules.
• signalIn - incoming Signal Rules.

Each Rule in a set has name and priority attributes. Signal Rules also have a stage attribute, specifying when the Rule should be applied.

Each Rule contains zero or more condition elements, zero or more action elements, and zero or one comment subelements:

condition

See the Rules section for more information.

attributes:

opCode

the Rule condition data.

operator

the Rule condition operation.

body:

the Rule condition parameter.

action

See the Rules section for more information.

attributes:

opCode

the Rule action operation.

body:

the Rule action parameter.

comment

body:

the Rule comment text.

Example: a Mail Rule storing all messages with the X-Junk: 5 header field in the Junk mailbox. Exception is made for messages coming from authenticated users.

<rule type="mailIn" name="Junk Filter" priority="2" >
  <condition opCode="Header Field" operator="is">X-Junk: 5*</condition>
  <condition opCode="Source" operator="is not">authenticated</condition>
  <action opCode="Store in">Junk</action>
  <action opCode="Discard"></action>
  <comment>This is my test Rule&#21;</comment>
</rule>

ruleList

This operation tells the Server to send one rule message for each Account Rule of the specified type. These messages do not have any subelement.

attributes:

type

the Rule set.

ruleRead

This operation tells the Server to send one rule message for the specified Rule. This message contains subelements with the Rule condition(s), action(s), and the optional comment.

attributes:

type

the Rule set.

name

the Rule name.

ruleSet

This operation stores a new Rule. If there is an existing Rule with the same name, it is removed.
The user should have a right to specify conditions and actions used in both new and old Rules.

attributes:

type

the Rule set.

name

the Rule name.

priority

the Rule priority.

stage

the Rule stage (for Signal Rules).

body:

the same subelements as used in the rule message: zero or more condition elements, zero or more action elements, and zero or one comment subelements.

ruleUpdate

This operation modifies the existing Rule priority and/or its stage (for Signal Rules).
The user should have a right to specify conditions and actions used in the Rule it tries to modify.

attributes:

type

the Rule set.

name

the Rule name.

priority

the Rule priority.

stage

the Rule stage (for Signal Rules).

ruleRename

This operation renames an existing Rule.
The user should have a right to specify conditions and actions used in the Rule it tries to rename.

attributes:

type

the Rule set.

name

the existing Rule name.

newName

the new Rule name.

ruleRemove

This operation removes an existing Rule.
The user should have a right to specify conditions and actions used in the Rule it tries to remove.

attributes:

type

the Rule set.

name

the existing Rule name.

The Server sends the following data messages:

rule

This message is sent when the Server processes a ruleList request or a ruleRead request. See above for the rule message format.

Real-Time Application Management

A client can interact with the Real-Time Applications running on the CommuniGate Pro Server or Cluster.

A XIMSS session can communicate with Tasks by sending them Events. Tasks see a XIMSS session as a yet another Task, so they can send Events back to it.

Each XIMSS session maintains a list of Tasks Handles for the Tasks it communicates with. Each handle in the list is associated with an taskID string. The XIMSS client uses these taskID strings to address the Tasks in the list.

taskFindMeeting

This operation implements the FindMeeting operation. See the CG/PL section for more information.

attributes:

meetingSet

the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.

meetingName

the unique ID or name for the Meeting.

If this operation succeeds, the Server returns a taskMeeting message with the found meeting data.

taskCreateMeeting

This operation implements the CreateMeeting operation. See the CG/PL section for more information.

attributes:

meetingSet

the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.

meetingName

the unique ID or name for the Meeting.

body:

The text to add to the Meeting Event as a parameter.

taskRemoveMeeting, taskClearMeeting, taskActivateMeeting, taskDeactivateMeeting

These operations implement the Meeting operations. See the CG/PL section for more information.

attributes:

meetingSet

the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.

meetingName

the unique ID or name for the Meeting.

taskSendEvent

This operation send an Event to a Task.

attributes:

taskRef

the internal taskID of the Task to send an Event to.

eventName

the name of the Event to send.

body:

The text to send with the Event as a parameter.

taskClose

There are some session resources associated with each internal taskID. If your client works with many different Tasks, it is recommended that it uses the taskClose operation when it ends communication with a particular Task, so its session-internal taskID is released.
If the same Task sends an Event to this session, or its Task Handle is discovered using other mechanisms, the new taskID is assigned to this Task in this session.

attributes:

taskRef

the internal taskID to release.

The Server sends the following data messages:

taskMeeting

This message is sent when the Server processes the taskFindMeeting request.

attributes:

meetingSet, meetingName

copies of the taskFindMeeting request attributes.

taskRef

an optional attribute: the internal taskID of the Task that has activated this Meeting.

expires

an optional attribute with the Meeting expiration date and time (GMT).

body:

The XML presentation of the Meeting parameters.

taskEvent

This message is sent when some Task or the Server itself sends an Event to the current XIMSS session.

attributes:

taskRef

the internal taskID of the Task that has sent this Event. If this attribute is absent, then the Event was generated and sent by the Server itself.

eventName

the name of the received Event.

body:

The text or the XML presentation of the Event parameter.

Directory

A client can access the global Directory.

listDirectory

This operation retrieves data from the Directory.

attributes:

baseDN

the directory record DN to start the search from. If the attribute value is $, the baseDN is set to the Directory subtree containing records for the current Account Domain.

filter

this optional attribute specifies a search filter in the RFC2254 format.

scope

this optional attribute spcifies the search type:

• base - the baseDN record is retrieved (the filter attribute is ignored)
• one (default) - the baseDN immediate subtree is searched (one-level search)
• sub - the entire baseDN subtree is searched (multi-level search)

limit

this optional attribute specifies the maximum number of directory records to retrieve.

body:

an optional set of field subelements. Each element should have a text body containing the name of an attribute to retrieve. If no field subelement is specified, all non-service Directory record attributes are retrieved.
Note: if the mail attribute is explicitly specified, the Server will compose this attribute value for all CommuniGate Pro Object records without this attribute.

The Server sends a directoryData message for each record found.

The Server sends the following data messages:

directoryData

This message is sent for each Directory record retrieved with the listDirectory request.

attributes:

name

the record DN.

body:

The XML presentation of the Record attributes.