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.
- exeTime
- this optional attribute is present if the operation request contained exeTime attribute with non-zero value. It contains the command execution time in milliseconds measured by the Server.
Example:
C:<noop id="A001"/>
S:<response id="A001"/>
C:<myCommand id="A002" myParam="user1@example.dom" exeTime="1"/>
S:<response id="A002" errorText="unknown command" errorNum="500" exeTime="211"/>
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.
-
Example:
C:<noop id="A001"/>
S:<alert gmtTime="20070502T083313" localTime="20070502T003313">Account is over quota</alert>
S:<response id="A001"/>
S:<alert gmtTime="20070502T083500" localTime="20070502T003500">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.
After a connection with the Server is established, and before the
client performs the login operation,
the client can perform only the operations listed in this section.
When a connection is established, the Server takes the IP Address the client has connected to
and selects the Domain this IP address is assigned to.
Operations in this section can explicitly specify an alternative target Domain: if it is found,
the new target Domain is set and it is used in the next operations.
- listFeatures
- This operation tells the Server to return a features message containing available communication and authentication options.
- Attributes:
- domain
- optional target Domain name.
- readStrings
- This operation reads the vocabulary (words, tags, button names, etc.) stored in the current Domain Skin.
The Server sends a strings data message with the dictionary data.
- Attributes:
- skinName
- the Skin name. If not specified, the unnamed Skin is used.
- language
- the vocabulary language. If the attribute is missing, the Account Defaults Language preference string is used.
- timeModified
- if this attribute is specified, it should contain a date and time value (GMT time).
If this attribute is specified, the strings data message does not have any body element
if the requested vocabulary modification time is not newer than this attribute value.
- starttls
- This operation tells the server to establish SSL/TLS security on this connection.
- Attributes:
- domain
- optional target Domain name.
If the server returns a positive response, the client should start SSL/TLS negotiations immediately.
- recoverPassword
- This operation asks the server to E-mail the password of the specified Account to the E-mail address
the Account user has specified.
- Attributes:
- domain
- optional target Domain name.
- userName
- the Account name.
If the server returns a positive response, the Account password has been E-mailed.
Note: this operation introduces a delay before returning a response.
- signup
- This operation tells the Server to create a new Account.
- Attributes:
- domain
- optional target Domain name.
- userName
- the new Account name.
- password
- the new Account password.
- realName
- a Real Name of the new Account owner (optional).
- recoverPassword
- an E-mail address that can be used to recover a forgotten password (optional).
If the server returns a positive response, the Account has been created.
Note: this operation does not log user into a newly created Account.
Note: this operation introduces a delay before returning a response.
The Server sends the following data messages:
- features
- This synchronous data message is sent when the Server processes the listFeatures operation.
- Body:
- a set of XML elements:
- domain
- the target Domain name.
- 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.
- nonce
- a valid "nonce" data. This "nonce" data can be used with SASL HTTP Login methods.
- language
- the text body of this element contains the default language selected for the target Domain.
If this element is absent, the default (English) language is selected.
- signup
- if this element is present, the client can perform the signup operation with the target Domain.
- connect
- if this element is present, it specifies the connection method the client should use for the login and session requests.
It is based on the Recommended XIMSS Method Domain Setting for the target Domain.
The element has the following attributes:
- protocol
- the protocol to use: http or ximss. The recommended protocol should be a secure one (such as https) if the listFeatures operation was issued over a secure protocol.
- port
- the TCP port number to use. If not specified, the client should use the same port as it used to send this listFeatures operation.
The client should perform the login operation to authenticate the user and to create a XIMSS session.
- login
-
- Attributes:
- domain
- optional target Domain name.
- 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-text method 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-text authentication method only, it contains the user password in the clear-text form.
- version
- This attribute specifies the protocol version this Client is designed for (for example, 6.0).
If the version is not specified, the 5.4 version is assumed.
Example:
C:<login id="A001" authData="user1@example.dom" password="123rtu" version="6.1" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>
The Server sends the following data messages:
- 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).
- version
- the protocol version supported with the Server (for example, 6.1).
Examples:
C:<login id="A001" authData="user1@example2.dom" password="rrr123" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith" version="6.1.2" />
S:<response id="A001"/>
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 id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>
If Two-Factor Authentication is enabled and required to complete the login operation the session response contains the x2auth dictionary that describes the methods available for Two-Factor Authentication, with the key of each element being the method name and the value being the dictionary with method parameters:
-
- Parameters:
- address
- optional parameter with the obfuscated address where the one-time password will be sent to.
This parameter may be an array when one method supports multiple addresses.
- icon
- this optional attribute specifies the icon file name to represent this method in the user interface.
- humanTag
- this optional attribute specifies the name of the string element in the Skin to name this method in UI.
- humanName
- this optional attribute specifies the string to name this method in UI. It's used when humanTag element is not present. When neither humanTag nor humanName are present, the raw method name can be used in UI.
Example:
C:<login id="A001" authData="user1@example2.dom" password="rrr123" x2auth="1" />
S:<session id="A001" urlID="14-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith" version="6.2c1">
S:<x2auth>
S: <subKey key="sms">
S: <subKey key="address">+1555***2207</subKey>
S: <subKey key="humanName">Send SMS to</subKey>
S: </subKey>
S: <subKey key="call">
S: <subKey key="address">+1555***2207</subKey>
S: <subKey key="humanTag">x2auth_voip_tag</subKey>
S: <subKey key="icon">x2auth_voip.png</subKey>
S: </subKey>
S: <subKey key="email">
S: <subKey key="address">d***6@gmail.com</subKey>
S: <subKey key="humanTag">x2auth_email_tag</subKey>
S: </subKey>
S: <subKey key="push">
S: <subKey key="address">
S: <subValue>John's iPhone</subValue>
S: <subValue>Samsung Galaxy S6</subValue>
S: </subKey>
S: <subKey key="humanTag">x2auth_push_tag</subKey>
S: <subKey key="icon">x2auth_voip.png</subKey>
S: </subKey>
S:</x2Auth>
S:<session/>
S:<response id="A001"/>
The client should present the user interface to select a method and then use x2AuthStart command to start the second stage of authentication and x2AuthComplete to complete it.
- x2AuthStart
-
- This operation starts transmission of the one-time secret to the devices possessed by the user, using the specified method.
On a success the Server sends the x2auth data message.
- Attributes:
- index
- Optional index of element in the array of addresses available for the selected method.
- Body:
- String with the selected method name.
- x2AuthComplete
-
-
- Body:
- Optional string with the one-time secret to confirm the second stage of authentication.
The server sends the following empty data message in response to the x2AuthStart command:
- x2auth
-
-
- Attributes:
- user
- Set if the x2AuthComplete expects the one-time secret from user input to unlock the session. This is the default.
- background
- Set when the one-time secret verification is expected to complete in background. In this case x2AuthComplete can be executed without one-time password to check for that completion.
The server sends the following asynchronous empty data message in response to the x2AuthStart and x2AuthComplete commands when second stage of the authentication is completed in background:
- x2AuthCompleted
-
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.
- 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.
- name
- this optional attribute specifies the tag for "application-specific" password.
- remove
- when this optional attribute is set to yes, the "application-specific" password with the tag specified in the the name parameter is removed.
- listSpecPasswords
- This command is used to retrieve the list of application passwords tags.
- setSessionOption
- This operation sets an option value for the current session.
- Attributes:
- name
- the option name
- value
- the option value
The following session options are supported:
- reportMailboxChanges
- if the option value is yes, the Server sends mailboxModified data messages,
for any other value, the Server stops sending these data messages.
- idleTimeout
- the session idle time-out is set to the specified number of seconds or to a some larger value, if the specified value is unavailable.
- listUploaded
- This operation retrieves information for one or all files from the "uploaded file set".
The Server sends uploaded file information in an uploadedFile data message (see below).
- Attributes:
- uploadID
- if this optional parameter is specified, information is retrieved only for the file with this fileID.
If this parameter is not specified, information for all "uploaded file set" files is retrieved.
- 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
- the vocabulary language. If the attribute is missing, the Account Language preference string is used.
- timeModified
- if this attribute is specified, it should contain a date and time value (GMT time).
If this attribute is specified, the strings data message does not have any body element
if the requested vocabulary modification time is not newer than this attribute value.
- readConfigFile
- This operation reads a configuration file stored on the Server.
The Server sends a configFile data message with the configuration file data (see below).
- Attributes:
- name
- the configuration name.
- timeModified
- if this attribute is specified, it should contain a date and time value (GMT time).
If this attribute is specified, the configFile data message does not have any body element
if the requested configuration modification time is not newer than this attribute value.
- 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.
- readSession
- This operation makes the Server to resend the session message (which is sent when a new session is created).
- 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.
- skinList
- This operation lists Skins in the current Domain.
- Attributes:
- filter
- an optional attribute specifies a picture with the star (*) symbol used as wildcards. Only the Skin names
matching this picture are reported.
The Server returns one skinInfo message for each Skin found.
- skinFileList
- This operation provides a list of the selected Skin file names.
- Attributes:
- skinName
- the Skin name. If not specified, the unnamed Skin is used.
- filter
- an optional attribute specifies a picture with the star (*) symbol used as wildcards. Only the file names
matching this picture are reported.
The Server returns one skinFileInfo message for each file found.
- skinFileRead
- This operation reads a file from the specified Skin in the current Domain.
- Attributes:
- skinName
- the Skin name. If not specified, the unnamed Skin is used.
- fileName
- the name of file to read.
- type
- If this optional attribute exists and its value is binary, the file data is returned base64-encoded.
The Server returns a skinFileData message.
- cliExecute
- This operation executes a Network CLI command.
- Attributes:
- report
- if this attribute is present, and its value is xml, the resulting object will be sent as its XML presentation.
- 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. The current user must have the HTTP Service enabled.
- Attributes:
- url
- the XML document URL (http: or https:).
- timeout
- the operation time-out (in seconds).
If the document is successfully retrieved, the Server sends a retrievedXML message with the retrieved document content.
- httpCall
- This operation sends an HTTP request to and receive an HTTP response from a remote server.
The current user must have the HTTP Service enabled.
This operation uses the specified URL, a composed request dictionary, and a maximum time-out of 30 seconds
to call the HTTP Client module to execute an HTTP request.
- Attributes:
- url
- the document URL (http: or https:).
- other attributes
- other attributes are used to compose the request dictionary.
- Body:
- If specified, it is used to compose the body element of the request dictionary (the HTTP request body).
It should use one of the following formats:
- a text body
- the text is used as the request body.
- one body XML element
- the element text body is used as the request body.
- one base64 XML element
- the element text body is base64-decoded and the resulting datablock is used as the request body.
- a set of field XML elements
- a dictionary with these elements is used as the request body (the HTTP POST request data).
Each field element specifies a form field: the element name attribute specifies
the form field name; the field value is specified with the field element body, which
should be either a text or an XML presentation of a number, datablock, or a dictionary
(see the HTTP Client module section for the details).
Besides these body data elements, the httpCall request body can contain:
- one supplFields XML element
- the element body should contain one or more subKey elements;
they form a dictionary specifying additional HTTP request fields.
- one urlParams XML element
- the element body should contain one or more subKey elements -
they form a dictionary specifying HTTP request URL parameters.
When the transaction completes, the Server sends a retrievedURL message with the transaction results.
- spellerList
- This operation causes the Server to send speller messages, containing the names of installed spell checkers.
- spellerCheck
- This operation checks the spelling of an arbitrary text. For each spelling error found, the Server sends a spellerReport message.
- Attributes:
- speller
- the spell checker name.
- mode
- if this attribute exists and it has the "glyphs" value, offsets and lengths in the spellerReport messages define symbols (UTF8-encoded) rather than bytes.
Body:
- the text to check.
- getSessionData
- This operation causes the Server to reply with the sessionData message -
XML representation of the session custom parameters dictionary or its subpart specified with the name attribute.
- Attributes:
- name
- the name of the key in the custom session data dictionary.
- setSessionData
- This operation modifies the contents of the custom session parameters dictionary.
- Attributes:
- name
- the name of the key in the custom session data dictionary.
- delete
- if this options attribute is set the operation removed the subpart of the session data specified with the delete attribute.
Body:
- The XML representation of the session custom parameters dictionary or its subpart specified with the name attribute.
- getLanguage
- This operation causes the Server to reply with the language message -
the language that is used by default for session operation with scripts or WSSP templates.
- setLanguage
- This operation modifies the default language to be used in the session for operation with scripts and WSSP templates.
- Attributes:
- language
- the name of the language.
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:
- gmtTime
- the time when the Alert was posted (GMT).
- localTime
- the time when the Alert was posted (in the selected time zone).
- Body:
- the Alert text (in the UTF-8 encoding).
- bye
- The Server has decided to close a session (time-out, administrator action, etc.)
The client is supposed to close its Server connection (if it has one), and to inform the user.
- newUploaded
- A new file has been added to the session "uploaded file set".
- Attributes:
- uploadID
- a string identifying the file in the "uploaded file set".
- mailboxModified
- Some of the current Account mailboxes has been modified. These messages are sent only if the session option reportMailboxChanges value was set to yes.
- Attributes:
- mailbox
- the modified mailbox name.
- sessionData
- The Server sends this message in response to the getSessionData command.
It contains the XML-representation of the requested custom session parameters dictionary.
- sessionDataModified
- The Server sends this message when the dictionary with custom session parameters has been modified externally.
The Server can send the following data messages:
- uploadedFile
- This synchronous data message is sent when the Server processes the listUploaded request.
- Attributes:
- uploadID
- a string identifying a file in the "uploaded file set".
- fileName
- the uploaded file name (optional)
- size
- the uploaded file size
- type
- the uploaded file Content type
- subtype
- the uploaded file Content subtype (optional)
- charset
- the uploaded file Content charset (optional)
- strings
- This synchronous data message is sent when the Server processes the readStrings request.
- Attributes:
- skinName
- the Skin name.
- language
- the selected language.
- timeModified
- the vocabulary modification date and time (GMT time).
Body:
- a set of string and strings XML elements. Each element has the name attribute -
the name (or "key") of the vocabulary element.
String-type vocabulary elements are presented using string elements. The string element body is the
vocabulary element value.
Dictionary-type vocabulary elements are presented using strings elements. The strings element body
is the set of string XML elements.
Array-type vocabulary elements are presented using strings elements. The strings element body
is the set of string XML elements without the name attribute.
Example:
The Client reads the default (english) vocabulary.
C:<readStrings id="A001" />
S:<strings id="A001" language="" >
<string name="AppendButton">Append</string>
<strings name="AppendModes">
<string name="simple">Simple Mode</string>
<string name="advanced">Advanced Mode</string>
</strings>
<strings name="KnownFields">
<string>From</string>
<string>Subject</string>
</strings>
</strings>
S:<response id="A001"/>
- configFile
- This synchronous data message is sent when the Server processes the readConfigFile request.
- Attributes:
- skinName
- the Skin name.
- name
- the configuration name.
- timeModified
- the configuration modification date and time (GMT time).
Body:
- the config XML element.
- 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.
- fileStore
- The information about the Account File Storage.
- Attributes:
- limit
- the file storage quota. This attribute is absent if the quota is set to Unlimited.
- fileSizeLimit
- the file size quota. This attribute is absent if the quota is set to Unlimited.
- fileLimit
- the quota on the number of all files. 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).
- localTime
- the login time (in the selected time zone).
- 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).
- localTime
- the time of the last failed login attempt (in the selected time zone).
- ip
- the network address from which the failed attempt to log in was made.
- RulesAllowed, SignalRulesAllowed, RPOPAllowed, RSIPAllowed, PWDAllowed, PasswordRecovery, EncryptedMailboxesAllowed
- The effective Account settings data. These elements do not have attributes,
and their text body is the setting value.
- option
- zero, one, or several XML elements. The element body is a string, specifying an option enabled for the current Account:
- S/MIME
- Secure Mail services are enabled.
- SMIMEActive
- Secure Mail services are unlocked.
- SMIMEInactive
- Secure Mail services are locked (but the Account does have a Private PKI key).
- WebCAL
- Calendaring services are enabled.
- WebSite
- Web access to File Storage is enabled.
- Signal
- Signaling services are enabled.
- PBX
- PBX services are enabled.
- HTTP
- HTTP transaction Services are enabled.
- signalBind
- The information about the session Real-Time parameters.
- Attributes:
- name
- the "clientID" name assigned to this session.
- hiddenModules
- Comma-separated list of disabled client modules.
- timeout
- The information about the session time-out parameters.
- Attributes:
- limit
- the session time limit, in seconds.
- idle
- optional; the idle time-out, in seconds. If this attribute is not present, idle time-outs for this session are disabled.
- knownValues
- These messages are sent when the Server processes the listKnownValues request.
- Body:
- a set of XML elements:
- tzid
- the element name attribute specifies a known Time Zone name;
- charset
- the element name attribute specifies a known character set name;
- mailRuleAllowed
- the element name attribute specifies a supported Allowed Mail Rule mode. Each mode defines which Mail Rule actions the user is allowed to modify;
Elements are sorted, with the "most restrictive" mode listed first.
- mailRuleCondition
- the element name attribute specifies a supported Mail Rule condition.
- mailRuleAction
- the element name attribute specifies a supported Mail Rule action;
the element allowedSet attribute specifies the enabling Allowed Mail Rule name.
The user can modify a Rule containing this operation only if the user Account RulesAllowed setting value
is the specified or a less restrictive Allowed Mail Rule mode.
- signalRuleAllowed, signalRuleCondition, signalRuleAction
- the same elements as the mailRuleAllowed, mailRuleCondition, mailRuleAction elements,
but for the Signal Rules.
- safeSchema
- the element name attribute specifies a URL schema that can be considered safe in mail content.
- webAccessURL
- the element name attribute specifies the preferred URL (schema, host, port) for accessing web services of the domain.
- skinInfo
- This synchronous data message is sent when the Server processes the skinList request.
- Attributes:
- skinName
- the Skin name.
- skinFileInfo
- This synchronous data message is sent when the Server processes the skinFileList request.
- Attributes:
- skinName
- the Skin name.
- fileName
- the file name.
- size
- the file size in bytes.
- timeModified
- an optional attribute with the file modification date and time (local time).
- skinFileData
- This message is sent when the Server processes the skinFileRead request.
- Attributes:
- fileName
- the name of read file.
- timeModified
- the file modification date and time (local time).
Body:
- Either a text with file data, or the base64 element.
The text body of this XML element is base64-encoded file data (base64 encoding allows you to retrieve binary data).
- cliResult
- These messages are sent when the Server processes the cliExecute request.
- Body:
- text or XML presentation of the CLI command output.
Example:
The Client reads some Account aliases.
C:<cliExecute id="A001">GETACCOUNTALIASES user@domain.com<cliExecute/>
S:<cliResult id="A001">(alias1,alias2)</strings>
S:<response id="A001"/>
C:<cliExecute id="A002" report="xml">GETACCOUNTALIASES user@domain.com<cliExecute/>
S:<cliResult id="A002"><subValue>alias1</subValue><subValue>alias2</subValue></strings>
S:<response id="A002"/>
- retrievedXML
- These messages are sent when the Server processes the retrieveXML request.
- Attributes:
- url
- the document URL.
Body:
- one XML element with the retrieved document.
- retrievedURL
- These messages are sent when the Server processes the httpCall request.
- Attributes:
- url
- the document URL.
- other attributes
- the elements of the result dictionary returned with the HTTP Client module (excluding the body element).
Body:
- the body element of the result dictionary:
- the element is a string
- the text body containing this string
- the element is a datablock
- a base64 XML element containing base64-encoded datablock data
- the element is an XML Object
- the XML Object
- speller
- These messages are sent when the Server processes the spellerList request.
- Attributes:
- speller
- the spell checker name; usually - the language name or the dialect name (such as English-US or French-CA).
- spellerReport
- These messages are sent when the Server processes the spellerCheck request and detects a spelling error.
- Attributes:
- position
- the misspelled word position in the supplied text.
- size
- the misspelled word size in the supplied text (in bytes).
Body:
- zero, one, or more guess XML elements. The text body of each element is a suggested replacement for the misspelled word.
Note: the supplied text is XML-decoded first, and the attributes specify the word position and size in the resulting decoded text (which must use UTF-8 character set).
Note:the position and size specify either bytes or symbols, depending on the request mode attribute value.
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
- an 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.
- mailboxClass
- if this optional attribute is specified, only the Mailboxes of the specified class are listed.
Specify an empty string value to list only "mail"-class Mailboxes.
- pureFolder
- if this optional attribute exists, and its value is yes, then the result includes "pure" folders, if the value is no, "pure" folders are not included.
See the mailbox data message description for the details.
- mailboxSubList
- This operation makes the Server send a mailboxSubscription data message (see below) for each element in the Account mailbox subscription set.
Note that Mailboxes in this set may or may not exist.
- Attributes:
- filter
- this optional attribute specifies the filter string in the IMAP protocol format.
- mailboxSubUpdate
- This operation modifies Account mailbox subscription set.
- Body:
- a set of mailboxSubscription elements.
- Attributes:
- mailbox
- a Mailbox name in the UTF-8 character set.
- mode
- if this attribute value is add the mailbox name is added to the Mailbox subscription set (unless the set already contains this name).
otherwise, the mailbox name is removed from the mailbox subscription set.
- mailboxAliasList
- This operation makes the Server send a mailboxAlias data message (see below) for each Mailbox Alias in the current Account.
- mailboxAliasUpdate
- This operation modifies the Account Mailbox Aliases set.
- Body:
- a set of mailboxAlias elements.
- Attributes:
- name
- the Mailbox Alias name in the UTF-8 character set.
- mode
- if this attribute value is add the name Alias is added to the Mailbox Aliases set.
If the set already contains an Alias with this name, it is replaced.
otherwise, the name Alias is removed from the Mailbox Aliases set.
Body:
- a string: the target Mailbox name in the UTF-8 character set.
- mailboxRightsGet
- This operation makes the Server send a mailboxRight data message (see below) with the user access rights for the specified Mailbox.
- Attributes:
- mailbox
- an existing Mailbox name.
- mailboxACLList
- This operation makes the Server send a mailboxACL data message (see below) with the Mailbox Access Control List data.
- Attributes:
- mailbox
- an existing Mailbox name.
- mailboxACLUpdate
- This operation modifies the Mailbox Access Control List for the specified Mailbox.
- Attributes:
- mailbox
- an existing Mailbox name.
Body:
- A set of aclElem XML elements:
- Attributes:
- pattern
- the ACL element "name". It can be an Account name, a name with "+" or "-" prefix, etc. See the Mailbox Access Control Lists section for more details.
- mode
- if this optional attribute value is add, the specified rights are added to the right set already specified for this ACL element. If the ACL element did not exist, it is created.
if this optional attribute value is sub, the specified rights are removed from the right set specified for this ACL element.
if this optional attribute value is clear, this ACL element is removed.
if this optional attribute has any other value, or if this attribute is absent, the specified rights replace the right set already specified for this ACL element. If the ACL element did not exist, it is created.
Body:
- a string; each symbol specifies a Mailbox Access Right.
The Server sends the following data messages:
- mailbox
- These synchronous data messages are sent when the Server processes the mailboxList request.
- Attributes:
- mailbox
- the Mailbox name in the UTF-8 character set.
- UIDVALIDITY, MESSAGES, UIDNEXT, UNSEEN, OLDEST, CLASS, MEDIA, UNSEENMEDIA
- standard and extended IMAP Mailbox attributes
- SIZE
- Mailbox size (internal, same as INTERNALSIZE in IMAP).
- pureFolder
- this attribute exists and it has the yes value if the Mailbox is a pure folder - i.e. it cannot contain messages, but it can contain sub-Mailboxes.
Note: a Mailbox is seen as a pure folder if it can contain messages, but the Mailbox class does not match the class specified in the mailboxList request.
- isFolder
- this attribute exists and it has the yes value if the Mailbox is a mailbox and a folder - i.e. it can contain messages, and it can contain sub-Mailboxes.
- rights
- the effective access rights for the Mailbox. If this attribute is absent, access to the Mailbox is not restricted.
- mailboxSubscription
- These messages are sent when the Server processes the mailboxSubList request.
- Attributes:
- mailbox
- the Mailbox name in the UTF-8 character set.
- mailboxAlias
- These messages are sent when the Server processes the mailboxSubList request.
- Attributes:
- name
- the Mailbox Alias name in the UTF-8 character set.
Body:
- a string; the target Mailbox name in the UTF-8 character set.
- mailboxRights
- This message is sent when the Server processes the mailboxRightsGet request.
- Attributes:
- mailbox
- the Mailbox name.
Body:
- a string; each symbol specifies an effective Mailbox Access Right granted to the current user.
- mailboxACL
- This message is sent when the Server processes the mailboxACLList request.
- Attributes:
- mailbox
- the Mailbox name.
Body:
- A set of aclElem XML elements, one element for each Mailbox Access Control List element:
- Attributes:
- pattern
- the ACL element "name". It can be an Account name, a name with "+" or "-" prefix, etc. See the Mailbox Access Control Lists section for more details.
Body:
- a string; each symbol specifies a Mailbox Access Right granted to or revoked from the "name".
Example:
- A001: the Client asks the Server to create the MyNotes Notes-type Mailbox.
- A002: the Client asks the Server to rename the MyNotes Mailbox into SharedNotes.
- A003: the Client asks the Server to grant the Lookup and Select rights for the SharedNotes Mailbox to users user1 and user2.
- A004: the Client asks the Server to add the Delete and Insert rights for the SharedNotes Mailbox to user user1 and to revoke the Select right from the user user2.
- A005: the Client asks the Server to retrieve the ACL data for the SharedNotes Mailbox.
C:<mailboxCreate id="A001" mailbox="MyNotes" mailboxClass="IPF.StickyNote" />
S:<response id="A001"/>
C:<mailboxRename id="A002" mailbox="MyNotes" newName="SharedNotes" />
S:<response id="A002"/>
C:<mailboxACLUpdate id="A003" mailbox="SharedNotes">
<aclElem pattern="user1">lr</aclElem>
<aclElem pattern="user2">lr</aclElem>
</mailboxACLUpdate>
S:<response id="A003"/>
C:<mailboxACLUpdate id="A004" mailbox="SharedNotes">
<aclElem pattern="user1" mode="add">di</aclElem>
<aclElem pattern="user2" mode="sub">r</aclElem>
</mailboxACLUpdate>
S:<response id="A004"/>
C:<mailboxACLList id="A005" mailbox="SharedNotes"/>
S:<mailboxACL id="A005" mailbox="SharedNotes">
<aclElem pattern="user1">lrdi</aclElem>
<aclElem pattern="user2">l</aclElem>
</mailboxACL>
S:<response id="A005"/>
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.
- mailboxClass
- an optional attribute. If the specified Mailbox does not exist and this optional attribute is specified, the specified Mailbox is created.
If this attribute value is a non-empty string, that value is assigned as the Mailbox Class to the newly created Mailbox.
- sortField
- the name of a message header field to use for Mailbox sorting.
- 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 FLAGS, the filter attribute value should contain a
comma-separated list of message flags names and/or negative names.
Only the messages with the specified flags set and the specified negative flags not set are included into the Server view.
For example, the filter="Media,Unseen" attribute will tell the Server to build a view
using only the messages with the Media flags set and the Seen flag not set.
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.
- hideDeleted
- If this optional attribute is present, the "hide deleted" folder mode is switched on if the attribute value is yes.
If this optional attribute is absent, the "hide deleted" folder mode is switched on if the current effective value of the DeleteMode Account Preference is not Mark.
When the "hide deleted" mode is on, a mailbox message is removed from the folder list as soon as the "Deleted" flag is assigned to it. If the "Deleted" flag is removed later, the message does not re-appear in the folder, but it will become visible again after the folder is re-opened.
- UIDValidity, UIDMin
- If these optional numeric attributes are present, and the Folder Mailbox UIDValidity value is equal to the UIDValidity request attribute value,
then only the messages with UID not smaller than the UIDMin value are included into the Folder.
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 following sortField and viewer fields can be specified:
- From, To, Cc, Bcc, Reply-To, Sender, Return-Path, or
other Email-field name. If a message header contains the specified Email-field, it is parsed.
If the field contains a "comment" (i.e. a "real name"), it is used. Otherwise, the parsed E-mail address is used.
- Date, Resent-Date. The field date value is converted to GMT.
When elements with these field values are sent within a folderReport message, they contain
the localTime attribute specifying the field value in the Time Zone selected for the current user.
- any other E-mail header field name (Subject, X-Mailer, etc). The field MIME-decoded value is used.
- E-From, E-To, or other E-Email-field name.
If a message header contains the specified Email-field, it is parsed, and the parsed E-mail address is used.
- Pty. The X-Priority field value is converted to the strings High, Low, or to an empty string.
- UID. The message metadata - its UID (unique ID) in the Mailbox.
- ORIGUID. The message metadata - its original UID in the Mailbox. Unless the message is an updated version of some older (and now deleted) message, the ORIGUID value is the same as the UID value.
- SIZE. The message metadata - its "raw" size in the Mailbox.
- INTERNALDATE. The message metadata - its "timestamp". It is formatted in the same way as the Date element.
- FLAGS the message metadata attribute values are used.
See the Mailboxes section for more information on the Mailbox message flags.
A session can use several open Folders at the same time.
A client should maintain an internal view of the Folder - an array or a table with one element for
each Folder message. A client should keep that view synchronized with the Server view (implemented with that Folder).
When a Folder is opened, the Server sends a folderReport
data message containing the total number of messages in the Folder.
The client uses this number to create the initial internal view table, filling it with empty elements.
To display the Mailbox content on the screen, the client checks which
elements of its internal view table it should use. If some of those elements 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).
Some Mailbox operations use a message set to specify the Mailbox messages to apply the operation to.
Messages can be specified either by their UIDs, or by their index numbers (their positions in the folder view).
To specify messages by their UIDs, use one or more UID elements.
Each UID element can include one message, in this case the message UID is specified as the element body:
<UID>12377</UID>.
An UID element can include a range of message UIDs specified as the from and till attributes:
<UID from="12377" till="12455" />.
The operation is applied to all Mailbox messages with UIDs not smaller than the from attribute value and not larger than the till attribute value.
Please remember that Folder messages are not sorted by their UIDs, unless the sortField="UID" attribute was used in the folderOpen operation.
To specify messages by index, use one or more index elements.
Each index element can include one message, in this case the message index is specified as the element body:
<index>14</index>.
An index element can include an index range specified as the from and till attributes:
<index from="12" till="10000" />.
The operation is applied to all Folder messages with position (index) not smaller than the from attribute value and not larger than the till attribute value.
A message set can include one or more UID elements, or it can include one or more index elements, but it cannot include both UID and index elements.
- folderBrowse
- This operation makes the Server send data messages for the specified message set in an open Folder.
- Attributes:
- folder
- the Folder name.
Body:
- a message set (see above).
The Server sends a folderReport data message for each message with the index or UID in the specified set.
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.
The "on demand" client-server synchronization model is used. When a Folder message is modified, added, or deleted,
the client gets an asynchronous folderReport data message with the mode attribute value set to notify
(a "notify-mode" message).
The newly added messages do not become visible in the logical Folder and the deleted messages are not
removed from the logical Folder. Requests to retrieve deleted message data return no data items or empty data items.
When the client application is ready to update its "internal view", it should use the
folderSync operation:
- folderSync
- This operation tells the Server to send all pending Folder modifications to the client.
- Attributes:
- folder
- the Folder name.
- limit
- optional; the maximum number of data messages to return.
The Server sends folderReport data messages with the mode attribute
set to the removed, added, updated, or attrsUpdated value.
After the Server sends a "notify-mode" message to the Client,
the Server may choose not to send further "notify-mode" messages for this Folder until the client
performs the folderSync operation on this Folder.
If the limit attribute is specified and the specified number of data message has been sent,
the Server finishes the the folderSync operation, but expects the client to perform an additional
folderSync operation on this Folder before it sends further "notify-mode" messages for this Folder.
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 Folder.
Note: unlike UIDs, Folder message index can change any time when the folderSync operation is performed.
Before you start any operation using an index-based message set, make sure that you have correctly updated the internal view with all folderReport data messages generated
with the previously sent folderSync operation.
Note: when a message has been removed from or added to a Mailbox, the Server only sends folderReport data messages with the mode="notify" attribute.
The Server-side "view" of the modified Folder (the logical Folder) is not updated, and it is safe to use an index-based message set to start a Folder operation.
- folderSearch
- This operation searches messages in an open Folder.
- Attributes:
- folder
- the Folder name.
- filter
- the search string as for IMAP SEARCH command.
- limit
- optional; the maximum number of data messages to return.
- timeout
- optional; the operation time-out (in seconds). The maximum is 5.
Body:
- a message set (see above).
The Server sends folderSearchResult data messages with the UIDs or indexes of the messages matching the search criteria.
If the search did not complete due to timeout or result limit then the reply will contain next attribute with the message UID/index where to start the next search.
Example:
C:<folderSearch id="A001" folder="INBOX" limit="5" timeout="1" filter="SINCE 1-Feb-2008 NOT FROM Smith OR SUBJECT test SUBJECT xxx">
<UID from="0" till="1000"/>
</folderSearch>
S:<folderSearchResult id="A001" folder="INBOX" next="480"><UID>285</UID><UID>386</UID><UID>479</UID></folderSearchResult>
S:<response id="A001"/>
- mailboxSync
- This operation sends the report on modified items since the last synchronization.
- Attributes:
- folder
- the Folder name.
- clientID
- the string that identifies the client; for each such client the serer keeps the separate history of changes in the mailbox.
- syncID
- the string that identifies the last synchronization point; for the first synchronization run it should be set to "0".
- limit
- optional; the maximum number of data messages to return.
- timeFrom
- optional; the time stamp for the oldest item to retrieve.
- totalSizeLimit
- optional; the maximum number of bytes for new message data to retrieve.
The Server sends mailboxSyncReport data messages that indicate the changes since the last synchronization.
- 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.
- mailboxClass
- If the target Mailbox does not exist and this optional attribute is specified, the target Mailbox is created.
If this attribute value is a non-empty string, the value is assigned as the Mailbox Class to the newly created Mailbox.
- encrypt
- if this optional attribute exists, and its value is yes, the messages are copied encrypted, using the current user S/MIME certificate.
- decrypt
- if this optional attribute exists, and its value is yes, and the encrypt attribute is not specified, the messages are copied decrypted. The Account Private Key should be unlocked, otherwise an error is returned.
- report
- If this optional attribute is specified, it should have the uid value.
For each message copied to the target mailbox, the Server sends the synchronous messageAdded message containing the UID of the copied message.
Body:
- a message set (see above).
- messageMove
- This operation is the same as the messageCopy operation, but if the messages have been copied successfully,
the operation deletes the original messages.
This operation can also be used to implement the "encrypt/decrypt message" functionality:
the selected messages should be moved to the same Mailbox using the encrypt or decrypt operation attribute.
- 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.
- mode
- an optional attribute. If specified and equals to delete then the specified flags are deleted (flags with negative names are not set).
Body:
- a message set (see above).
- messageRemove
- This operation removes messages from an open Folder.
- Attributes:
- folder
- the Folder name.
- mode
- an optional attribute, specifying the delete operation method.
If specified, it should have one of the following values:
- Immediately - the messages are physically removed from the Folder Mailbox.
- Move To Trash - the messages are moved to the Trash Mailbox (its name is specified with the TrashBox Account preference).
If the specified Folder is the Trash Mailbox itself, the messages are physically removed.
- Mark - the messages are marked with the Deleted flag.
If this attribute is not specified, the method specified with the DeleteMode Account Preference is used.
Body:
- a message set (see above).
- 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.
- folderReopen
- This operation re-builds an open Folder by re-scanning its Mailbox using different sorting and filtering parameters.
- Attributes:
- folder
- the Folder name.
- sortField, sortOrder, filter, filterField, hideDeleted, UIDValidity, UIDMin
- these attributes have the same meaning as the same folderOpen operation attributes.
Body:
- if the request body contains at least one <field> element, these elements specify
the new viewer fields set. If no <field> element is specified, the viewer fields set is not modified.
When a client uses this command, the Server sends the folderReport message with the mode attribute set to init,
notifying the client about the new Folder size.
The client should clear its internal Folder view, and re-populate it again.
Note:if a Client receives a folderReport message with the mode attribute set to notify
when the Client has already sent the folderReopen command,
the Client should use the folderSync command after it receives response for the folderReopen command.
- emptyTrash
- This operation physically removes all messages from the Trash Mailbox (if it has been specified).
- emptyMailbox
- This operation physically removes all messages from the specified mailbox.
- Attributes:
- mailbox
- the mailbox name.
- duration
- time limit (in "time delta" format) between the current time and the internal date of the newest message to keep in the mailbox.
Specify 0 to delete all messages.
The Server sends the following data messages:
- folderReport
- These messages are sent synchronously when a Folder is being opened or re-opened, and when the client sends a folderBrowse or a folderSync request.
These messages are sent asynchronously when a Folder status changes (messages are added, removed, or updated), in this case its mode attribute is set to notify.
- 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,
and the unseen attribute specifies the total number of unseen messages (messages without the Seen flag) in the Folder.
This is a synchronous data message sent when a Folder is being opened or re-opened.
- If the attribute value is notify some Mailbox messages have been added, modified, or deleted.
This message is sent as an asynchronous data message.
The client is expected to send the folderSync request for this Folder.
- 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 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 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 attrsUpdated, or the attribute is missing,
then the index and UID attributes specify a Mailbox message and the body
contains the message viewer field values.
This attribute is present and it is set to error when the folderBrowse request
fails to retrieve the message data (for example, when a message has been already deleted, but it has not been removed from the view, because the folderSync request has not been issued yet.
- 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 removed, updated, attrsUpdated, or added.
- messages
- the total number of messages in the Folder.
This attribute is present when the mode attribute value is init, removed, or added.
- unseen
- the total number of unseen messages in the Folder.
This attribute is present when the mode attribute value is init, removed, updated, attrsUpdated, or added.
- rights
- the effective access rights for the Folder.
This attribute is present when the mode attribute value is init. If this attribute is absent, access to the Folder is not restricted.
- UIDValidity, UIDNext
- the Folder Mailbox UIDValidity and UIDNext values.
These attributes are present when the mode attribute value is init.
Body:
- The body is present when the mode attribute value is absent (folderBrowse response message),
or when the mode attribute value is updated, attrsUpdated, or added (folderSync response message).
The body contains a set of XML 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 inserted
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 id="A001" folder="INBOX" mode="init" messages="234" unseen="12" />
S:<response id="A001"/>
C:<folderBrowse id="A002" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A002" folder="INBOX" index="0" UID="123">
<FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
<Subject>Hello - just a test</Subject>
</folderReport>
S:<folderReport id="A002" folder="INBOX" index="1" UID="543">
<FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
<Subject>This is the best offer!</Subject>
</folderReport>
S:<folderReport id="A002" folder="INBOX" index="2" UID="343">
<FLAGS>Seen,Media</FLAGS><From>user@example.com</From>
<Subject>Meeting reminder</Subject>
</folderReport>
S:<folderReport folder="INBOX" mode="notify" />
S:<folderReport id="A002" folder="INBOX" index="3" UID="512">
<FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
<Subject>Shutdown @ 4:45AM</Subject>
</folderReport>
S:<response id="A002" />
S:<folderReport folder="INBOX" mode="notify" />
C:<folderBrowse id="A003" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A003" folder="INBOX" index="0" UID="123">
<FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
<Subject>Hello - just a test</Subject>
</folderReport>
S:<folderReport id="A003" folder="INBOX" index="1" UID="543">
<FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
<Subject>This is the best offer!</Subject>
</folderReport>
S:<folderReport id="A003" folder="INBOX" index="2" UID="343">
<FLAGS>Seen,Media</FLAGS><From></From>
<Subject></Subject>
</folderReport>
S:<folderReport id="A003" folder="INBOX" index="3" UID="512">
<FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
<Subject>Shutdown @ 4:45AM</Subject>
</folderReport>
S:<response id="A003" />
C:<folderSync id="A004" folder="INBOX" />
S:<folderReport id="A004" folder="INBOX" index="35" UID="117" mode="deleted" messages="233" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="2" UID="343" mode="deleted" messages="232" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="1" UID="976" mode="added" messages="233" unseen="12" >
<FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
<Subject>[CGP] Re: Session Timer?</Subject>
</folderReport>
S:<response id="A004" />
C:<folderBrowse id="A005" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A005" folder="INBOX" index="0" UID="123">
<FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
<Subject>Hello - just a test</Subject>
</folderReport>
S:<folderReport id="A005" folder="INBOX" index="1" UID="976">
<FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
<Subject>[CGP] Re: Session Timer?</Subject>
</folderReport>
S:<folderReport id="A005" folder="INBOX" index="2" UID="543">
<FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
<Subject>This is the best offer!</Subject>
</folderReport>
S:<folderReport id="A005" folder="INBOX" index="3" UID="512">
<FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</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 messages 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 id="A021" folder="INBOX" index="1" UID="976" mode="updated" unseen="12" >
<FLAGS>Recent,Deleted</FLAGS><From>CGatePro Discussions</From>
<Subject>[CGP] Re: Session Timer?</Subject>
</folderReport>
S:<folderReport id="A021" folder="INBOX" index="3" UID="512" mode="updated" unseen="12" >
<FLAGS>Seen,Deleted,Flagged</FLAGS><From>Admin@hq.example.com</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 id="A023" folder="INBOX" index="0" UID="123" mode="deleted" messages="232" unseen="12" />
S:<folderReport id="A023" folder="INBOX" index="0" UID="976" mode="deleted" messages="231" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="29" UID="446" mode="deleted" messages="230" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="123" UID="756" mode="deleted" messages="229" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="1" UID="512" mode="deleted" messages="228" unseen="11" />
S:<response id="A023"/>
C:<closeMailbox id="A024" folder="INBOX" />
S:<response id="A024"/>
- mailboxSyncReport
- These messages are sent synchronously when the client sends a mailboxSync request.
- Attributes:
- folder
- the Folder name.
- mode
- this attribute specifies the type of record.
- If the attribute value is info then the hasMore attribute specifies whether there are not reported yet changes,
and the syncID attribute specifies the value to be used with the next synchronization request.
- Other records contain the attribute origUID to refer to the messages that have been added, modified, or deleted.
The mode attribute then contains the type of the change:
removed for messages that were deleted since the last synchronization run;
flagsUpdated or attrUpdated for messages with modified flags or attributes;
added or updated for new messages and messages whose body has been modified;
Body:
- The body is present when the mode attribute value is not deleted.
The body contains a set of XML elements with viewer field values.
When the mode attribute value is added or updated the body also contains the message.
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. It is sent to the client as a folderMessage data message.
- Attributes:
- folder
- the Folder name.
- UID
- the message UID.
- partID
- this optional attribute specifies the message part to read. If it is not specified, the entire message is read.
- mode
- if this optional attribute is set to replyFrom or replyAll, the partID attribute should either be absent or it should specify
an EMail subpart element. The folderMessage response message body is an EMail element with a pre-composed reply E-mail.
if this optional attribute is set to forward, the partID attribute should either be absent or it should specify
an EMail subpart element. The folderMessage response message body is an EMail element with a pre-composed inline forward E-mail.
The replyFromHTML, replyAllHTML and forwardHTML variants can be used to choose the HTML part of the original message.
- totalSizeLimit
- the maximum total size of all message parts returned.
- x509
- if this optional attribute is set to base64, the x509 subelements in the retrieved messages (digital signatures) will contain the base64-encoded certificate data.
- messageAppend
- This operation tells the Server to compose a Message and append it to an open folder or to an arbitrary Mailbox.
- Attributes:
- folder
- the target Folder name. If specified, the targetMailbox attribute is ignored.
- targetMailbox
- the target Mailbox name. It must be specified if the folder attribute is absent.
- mailboxClass
- this optional attribute can be specified if the targetMailbox attribute is specified.
If the target Mailbox does not exist and this optional attribute is specified, the target Mailbox is created.
If this attribute value is a non-empty string, the value 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.
- replacesUID
- this optional attribute can be specified if the folder attribute is specified.
If the message has been successfully composed and appended to the Folder, the message with the replacesUID UID is removed from the Folder Mailbox.
- replaceMode
- this optional attribute can be specified if the replacesUID attribute is specified.
if the attribute value is checkOld, the the operation fails if the Folder Mailbox
does not contain a message with replacesUID real UID. This check and the append/delete operations are executed atomically.
if the attribute value is copyOrigUID, the operation fails if the Folder Mailbox
does not contain a message with replacesUID real UID.
If the message does exist, then its ORIGUID attribute is copied to the newly created message.
This check, the append/delete operations, and the attribute assignment are executed atomically.
if the attribute value is origUID, replaceUID attribute specified the ORIGUID attribute of the message to be replaced.
The operation fails if the Folder Mailbox does not contain a message with replacesUID ORIGUID.
If the message does exist, then its ORIGUID attribute is copied to the newly created message.
This check, the append/delete operations, and the attribute assignment are executed atomically.
- report
- If this optional attribute is specified, it should have the uid value.
If the message has been successfully composed and appended to the target Mailbox or Folder, the Server sends the synchronous messageAdded message containing the UID of the newly appended message.
Body:-
The XML presentation of the Message (the EMail data).
If the EMail element contains the uploadID attribute, the RFC message body is built from the contents of the respective file in the session "uploaded file set".
The text parts of the message XML presentation should use the Line Feed (0x0A) symbol as the EOL (end of line) symbol.
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>
<Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME type="text" subtype="plain">Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</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 -0700
Message-ID: <web-40721383@domain.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.
You can specify the type, subtype, and (for text files) charset attributes.
If you do not explicitly specify them, they are copied from the Content-Type field of the HTTP request used to upload the file.
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" Folder, with the "Draft" message flag, replacing the existing message with the 578 UID.
The message contains some text in the alternative (plain and html) formats, and the uploaded files as attachments.
The client requests the Server to send the UID of the newly created message (756).
While the client was adding the new message, a different process added some other message (with UID=755) to the "Drafts" Folder Mailbox.
The client then clears the "uploaded file set", and re-syncs its state with the "Drafts" Folder.
C:<messageAppend id="A001" folder="Drafts" flags="Draft,Seen" replacesUID="578" report="uid" >
<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>
<Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME type="multipart" subtype="mixed">
<MIME type="multipart" subtype="alternative">
<MIME type="text" subtype="plain">Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</MIME>
<MIME type="text" subtype="html"><html><body><i>Dear Susan,</i><p>I will come to your place tomorrow, thank you for the invitation!<p><i>Mary.</i></MIME>
</MIME>
<MIME uploadID="att01" />
<MIME uploadID="att02" type="application" subtype="pdf" />
</MIME>
</EMail>
</messageAppend>
S:<folderReport folder="Drafts" mode="notify" />
S:<messageAdded id="A001" folder="Drafts" UID="756" />
S:<response id="A001"/>
C:<clearUploaded id="A002" />
S:<response id="A002"/>
C:<folderSync id="A003" folder="Drafts"/>
S:<folderReport id="A003" folder="Drafts" index="17" UID="578" mode="removed" messages="301" unseen="0"/>
S:<folderReport id="A003" folder="Drafts" index="127" UID="755" mode="added" messages="302" unseen="1">
<FLAGS>Recent,Drafts</FLAGS>
<From>Other Name</From>
</folderReport>
S:<folderReport id="A003" folder="Drafts" index="17" UID="756" mode="added" messages="303" unseen="1" >
<FLAGS>Recent,Drafts,Seen</FLAGS>
<From>Sender Name</From>
</folderReport>
S:<response id="A003"/>
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:51:24 -0700
Message-ID: <web-40721383@domain.dom>
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"
Content-Transfer-Encoding: 8bit
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"
Content-Transfer-Encoding: 8bit
<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 an open 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.
If it is specified, the non-MIME (other than Content-xxxxx) part header fields are not copied.
Example:
The Client stores a note in the "Notes" Mailbox, 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>
<Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<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"/>
</MIME>
</EMail>
</messageAppend>
S:<response id="A001"/>
You can attach files stored in the Personal File Storage.
Specify the full file name in the MIME elements by using the fileName attribute.
You must explicitly specify type, subtype, and (for text files) charset attributes.
You should specify the disposition-filename attribute, as the fileName attribute is not used to form the attachment name.
Example:
The Client stores a note in the "Notes" Mailbox, appending the file private/MyFile.jpg as the photo.jpg attachment:
C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
<EMail>
<From realName="Sender Name">fromName@domain</From>
<Subject>Vacation Pictures</Subject>
<Date localTime="20060621T215124" timeShift="-25200">20070830T045124Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME type="multipart" subtype="mixed">
<MIME type="text" subtype="plain">Attached please find the images I have stored as files.</MIME>
<MIME type="image" subtype="jpeg" fileName="private/MyFile.jpg" disposition-filename="photo.jpg" />
</MIME>
</EMail>
</messageAppend>
S:<response id="A001"/>
Note: if a <MIME /> element has the disposition attribute value none,
the Content-Disposition: header field is not created, and the Content-Type field is stored without the name parameter.
Note: the text MIME parts should use a single LineFeed (0x0A, decimal 10) symbol as the line separator.
You can ask the Server to use the "flowed" format for text MIME parts.
Example:
C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
<EMail>
<Subject>Test text</Subject>
<MIME type="text" subtype="plain" format="flowed">This is a very long long long long long long long long long long superlong long long long long long long line, followed with a shorter line:
This is a shorter line.</MIME>
</EMail>
</messageAppend>
S:<response id="A001"/>
This operation adds the following message to the Mailbox:
Subject: Test text
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; format="flowed"; charset="utf-8"
This is a very long long long long long long long long long long superlong
long long long long long long line, followed with a shorter line:
This is a shorter line.
(there is a trailing space after the "superlong" word)
To create a signed message, make sure that S/MIME Private key is unlocked,
and specify the sign attribute in the topmost EMail element.
C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" >
<EMail sign="yes">
<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,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</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
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg="SHA1"; boundary="_===signed==2610002====my.server.domain===_"
This is a signed S/MIME message
--_===signed==2610002====my.server.domain===_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
Dear Susan,
I will come to your place tomorrow, thank you for the invitation!
Mary.
--_===signed==2610002====my.server.domain===_
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
MIIE6wYJKoZIhvcNAQcCoIIE3DCCBNgCAQExCzAJBgUrDgMCGgUAMAsGCSqGSIb3DQEHAaCC
ArkwggK1MIICX6ADAgECAgcAk9RF+n/7MA0GCSqGSIb3DQEBBAUAMIG6MQswCQYDVQQGEwJV
UzELMAkGA1UECBMCQ0ExFDASBgNVBAcTC01pbGwgVmFsbGV5MSIwIAYDVQQKExlDb21tdW5p
.............
gIbXNT64QJ+gEYkI9mnePiS1TUOOzGYfXaLy1pqm6jmzBUt7/3UY8ZNHVIwM0Fzj7NwzqM1U
Esbkyi3WHNxTZ4HSCs8J2enGQEZjNWHOuX96xQojYGLV0m5Z/FatV9GQ8jNVBmQ9xYGKxmlY
jT9ze/oHyKuj7KR8QrgQSYiJVnn7
--_===signed==2610002====my.server.domain===_--
- 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 exists, and its value is yes, 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, then the composed message is appended to the specified Mailbox. These attributes
have the same meaning as for the messageAppend operation.
- dataset
- if the optional attribute is specified, it specifies the name of an Account dataset.
All message target addresses (see below) are stored in the specified dataset, removing existing duplicates.
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 addresses specified in
the To, Cc, and Bcc elements inside the EMail element.
If the EMail element contains the uploadID attribute, the RFC message body is built from the contents of the respective file in the session "uploaded file set".
When the message MIME text is generated, all addresses from the Bcc elements are skipped.
If the XML presentation does not include the Message-ID, Date, MIME-Version fields, the server creates these
message fields itself.
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,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</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 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</Cc>
<MIME type="text" subtype="plain">Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</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,

Attached please find the message I received this morning...
Mary.
</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>
MIME-Version: 1.0
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.
- partID
- this optional attribute specifies the message part to read. If it is not specified, the entire message is redirected.
If specified, it should specify a message part that is an E-mail message: a sub-part of the message/rfc822 part,
a digest part, etc.
- mirror
- if this optional attribute is yes, then the message is "mirrored": it is sent
to the specified addresses, but the message header To and Cc fields are left unchanged.
- markRedirected
- if this attribute is yes, then the "Redirected" flag is added to the message.
If this attribute is not specified, the yes value is assumed if the partID is not specified,
otherwise the no value is assumed.
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, but the mirror attribute is not supported.
- messageConfirm
- This operation tells the Server to compose an MDN (Message Disposition 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 requested 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 requested to send a confirmation).
- messageAttrRead
- This operation reads the Mailbox message attributes.
- Attributes:
- folder
- the Folder name.
- UID
- the message UID.
Body:
- a set of field XML elements. Each element should have a text body containing the name of an attribute to retrieve.
If no field element is specified, all attributes are retrieved.
The Server returns a messageAttrData message.
- messageAttrWrite
- This operation modifies Mailbox message attributes.
- Attributes:
- folder
- the Folder name.
- UID
- the message UID.
Body:
- XML presentation of a dictionary with new attribute values.
To remove an attribute specify the null-object (<null/>) value.
The Server sends the following data messages:
- folderMessage
- This synchronous data message is sent when the Server processes the folderRead request.
- Attributes:
- folder, UID, partID, mode
- copies of the folderRead request attributes.
Body:
- The XML presentation of the Message or its part.
- messageAdded
- These synchronous data messages are sent when the Server processes the messageAppend,
contactAppend, and messageCopy requests with the report attributes set.
- Attributes:
- folder or targetMailbox
- the target Folder or Mailbox name, copied from the request attribute.
- UID
- the newly added message UID.
Note: even if this data message is sent for a Folder, the Server will still send asynchronous folderReport data message notifying the client about a new message added to the Folder.
The client SHOULD use the folderSync operation to synchronize its internal view with the Server view, otherwise the newly added message will not be "seen" in the Folder.
- messageAttrData
- These synchronous data messages are sent when the Server processes the messageAttrRead requests.
- Attributes:
- folder, UID
- copied from the request.
Body:
- The XML presentation of the attribute set dictionary.
A client can use the following set of operations to manage Account ACLs.
- accountRightsGet
- This operation makes the Server send an accountRights data message (see below) with the user access rights for the current or specified Account.
- Attributes:
- userName
- an optional account specifying the target Account name. If this attribute is absent, the current Account is used.
- accountACLList
- This operation makes the Server send an accountACL data message (see below) with the Mailbox Access Control List data.
- Attributes:
- userName
- an optional account specifying the target Account name. If this attribute is absent, the current Account is used.
- accountACLUpdate
- This operation modifies the Account Access Control List.
- Attributes:
- userName
- an optional account specifying the target Account name. If this attribute is absent, the current Account is used.
Body:
- A set of aclElem XML elements. These elements are the same as those used with the mailboxACLUpdate operation,
but their body strings use symbols that specify Account Access Rights.
- verifyIdentity
- This operation verifies that provided Real Name and e-mail address can be used by the account for the From address in outgoing mails.
If the Account's settings prohibit the us of the specified Real Name and e-mail address, the server returns an error string.
- Attributes:
- name
- an optional Real Name string for use in the From e-mail header. If this attribute is absent, the current Account's Real Name is used.
Body:
- the e-mail address to be used in the From e-mail header.
The Server sends the following data messages:
- accountRights
- This message is sent when the Server processes the accountRightsGet request.
- Attributes:
- userName
- the Account name (if specified in the request).
Body:
- a string; each symbol specifies an effective Account Access Right granted to the current user.
- accountACL
- This message is sent when the Server processes the accountACLList request.
- Attributes:
- userName
- the Account name (if specified in the request).
Body:
- A set of aclElem XML elements, one element for each Account Access Control List element, same
as used in the mailboxACL data messages, but the element body strings contain symbols representing
Account Access Rights.
A client can use the following set of operations to use the Server S/MIME features.
- 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 unlocked Private Key is added to the current session data only,
and it is not stored anywhere.
If a different session is opened for the same Account, it should unlock the Private Key by itself.
- Attributes:
- password
- the unlocking string (password).
- duration
- optional attribute - the time (in seconds) to keep the Private Key unlocked;
the Private Key is automatically locked after this period of time.
- SMIMELock
- This operation locks the Account Private Key stored on the Server
(it removes the unlocked Private Key from the current session data).
It is recommended to use this operation after a certain period of user inactivity.
- 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).
- SMIMEGet
- This operation retrieves S/MIME-related information stored on the Server.
- Attributes:
- type
- type of information retrieved.
If the value of the type attribute is certificate, then
the Server sends a certificate data message with the Account Public Certificate.
- SMIMESet
- This operation modifies S/MIME-related information stored on the Server.
- Attributes:
- mode
- operation: add, new, update, delete.
- password
- the S/MIME unlocking password (required for the add and new operations).
- filePassword
- the password used to decrypt the imported data (required for the add and delete operations).
- duration
- when a new S/MIME key and certificate are set, they remain unlock. If this attribute is set, it specifies the number of seconds the S/MIME data remains unlock.
- PFX
- this attribute is used only if the body does not contain a PFX XML element.
This attribute identifies a file in the "uploaded file set". The file should contain PKCS12 data containing a Private Key and a Certificate.
Body:
- an optional PFX element; it should contain a base64 XML element with a textual body that is a Base64-encoded PKCS12 data containing a Private Key and a Certificate.
If the mode value is add, the Server gets the PKCS12 data specified with the PFX body XML element or
with the PFX attribute, decrypts it using the specified filePassword value, and assigns the decrypted Private Key and Certificate to the current Account.
The server encrypts the stored Private Key data using the the specified password value, which becomes the "S/MIME unlocking string".
If the mode value is new, the Server generates a random Private Key and issues an S/MIME Certificate for the current
Account, using the Account Domain "S/MIME Issuer" Certificate.
The server encrypts the stored Private Key data using the the specified password value, which becomes the "S/MIME unlocking string".
If the mode value is update, the Server updates the Account Certificate, if this Certificate was issued
using the Account Domain "S/MIME Issuer" Certificate.
If the mode value is delete, the Server gets the PKCS12 data specified with the PFX body XML element or
with the PFX attribute, decrypts it using the specified filePassword value, and compares the retrieved Private Key with the Private Key of the current Account.
If the Private Keys are the same, the Account Private Key and Certificate are removed.
Note: this operation transfers the storage passwords in clear text.
The client application should use this command only over a secure (TLS) connection.
The Server sends the following data messages:
- certificate
- This message is sent when the Server processes the SMIMEGet request.
- Body:
- an XML presentation of the Account S/MIME Public Certificate.
The Server detects all signed message parts and tries to verify that the part body has not been altered
since the time it was signed, and that the signature certificates are valid (i.e. issued by known authorities).
The MIME element body for a signed message part contain 2 XML sub-elements: the first element is the signed data (an EMail or MIME element),
the second part is the SMIMESignature XML element.
If the Server failed to decode or decrypt the signature data, the MIME element body for a signed message part contains the decryptionError attribute with the error code text.
The SMIMESignature element body contains Certificate sub-elements for all signatures that match the part data. If the Server failed to verify the Certificate, its element contains the validationError attribute with the error code text.
If no signature matches the the part data, the SMIMESignature element is empty.
Example:
The Client retrieves a signed message:
C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
<EMail>
<Return-Path>fromName@domain</Return-Path>
<From realName="Sender Name">fromName@domain</From>
<Subject>Re: I'll be there!</Subject>
<To realName="Recipient Name">a1@domain</To>
<X-Mailer>SuperClient v7.77</X-Mailer>
<Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME digesterName="SHA1" estimatedSize="5171" subtype="signed" type="multipart"
Type-micalg="SHA1" Type-protocol="application/x-pkcs7-signature" />
<MIME estimatedSize="3032" partID="01" subtype="mixed" type="multipart">
<MIME charset="utf-8" estimatedSize="86" partID="01-01" subtype="plain" type="text">Dear Susan,

Attached please find a file I received this morning...
Mary.

</MIME>
<MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="01-02" subtype="gif" type="image" />
</MIME>
<SMIMESignature>
<x509 subject="fromName@domain" validationError="presented certificate is issued by an unknown authority" version="2">
<subject><cn>Sender Name</cn><contact>fromName@domain</contact></subject>
<issuer><c>US</c><cn>issuer.dom</cn><contact>postmaster@issuer.dom</contact><l>Moscow</l>
<o>Issuer Company, Inc.</o><ou>Issuer Department</ou><st>CA</st></issuer>
<validFrom>20040924T231857Z</validFrom>
<validTill>20170923T231857Z</validTill>
</x509>
</SMIMESignature>
</MIME>
</EMail>
</folderMessage>
S:<response id="A001"/>
When the Account Private Key is unlocked, the Server tries to decrypt all encrypted message parts.
- If decrypting fails, the encrypted part element contains an additional attribute:
- decryptionError
- the decrypting error message text.
If decrypting fails, the encrypted part is shown as the MIME or EMail XML sub-element of the
encrypted part element.
If decrypting succeeds, the encrypted part element body contains a MIME or EMail XML sub-element with the decrypted data.
- The encrypted part element contains additional attributes:
- cipherName
- the name of cryptographic cipher used to encrypt the decrypted part.
- keyLength
- the length of cryptographic cipher key (in bits) used to encrypt the decrypted part.
Example:
The Client retrieves an encrypted message, then unlocks the Account Private Key and then retrieves the same message again:
C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
<EMail>
<Return-Path>fromName@domain</Return-Path>
<From realName="Sender Name">fromName@domain</From>
<Subject>Re: I'll be there!</Subject>
<To realName="Recipient Name">a1@domain</To>
<X-Mailer>SuperClient v7.77</X-Mailer>
<Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536"
subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" />
</EMail>
</folderMessage>
S:<response id="A001"/>
C:<SMIMEUnlock id="A002" password="smime-password" />
S:<response id="A002"/>
C:<folderRead id="A003" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A003" folder="INBOX" UID="55">
<EMail>
<Return-Path>fromName@domain</Return-Path>
<From realName="Sender Name">fromName@domain</From>
<Subject>Re: I'll be there!</Subject>
<To realName="Recipient Name">a1@domain</To>
<X-Mailer>SuperClient v7.77</X-Mailer>
<Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME cipherName="RC2" disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536" keyLength="40"
subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" >
<EMail partID="E">
<From realName="Sender Name">fromName@domain</From>
<Subject>Re: I'll be there!</Subject>
<To realName="Recipient Name">a1@domain</To>
<X-Mailer>SuperClient v7.77</X-Mailer>
<Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
<Message-ID>web-40721383@domain.dom</Message-ID>
<MIME estimatedSize="3275" partID="E" subtype="mixed" type="multipart">
<MIME charset="utf-8" estimatedSize="329" partID="E-01" subtype="plain" type="text" Type-format="flowed">
This is an encrypted E-mail with an attachment.
On Thu, 30 Aug 2007 20:40:49 -0800
"Sender Name" <fromName@domain> wrote:
> Dear Susan,
>
> I will come to your place tomorrow, thank you for the invitation!
> Mary.
</MIME>
<MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="E-02"
subtype="gif" type="image" />
</MIME>
</EMail>
</MIME>
</EMail>
</folderMessage>
S:<response id="A003"/>
When the Account Private Key is unlocked, a client can submit a signed E-mail.
- The EMail element should contain an additional attribute:
- sign
- if this optional attribute exists, and its value is yes, the message body is signed.
Example:
The Client submits a signed text message to the toName@domain address.
C:<messageSubmit id="A001">
<EMail sign="yes">
<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,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</MIME>
</EMail>
</messageSubmit>
S:<response id="A001"/>
When the Account Private Key is unlocked, a client can submit an encrypted E-mail if there is an Address Book containg records for all E-mail recipients, and each of those records contains a recipient PKI Certificate.
- The topmost EMail element should contain additional attributes:
- encrypt
- if this optional attribute exists, and its value is yes, the message body is encrypted.
- addressBook
- the name of the Address Book to look the recipient certificates in.
- addressBook1, addressBook2
- optional: names of the additional Address Books. If no recipient certificate is found in the Address Book with the name stated in the addressBook attribute, these Address Books are checked.
The topmost EMail element should contain the single "inner" EMail element - the content of that element
will be encrypted. The inner EMail element header fields can be the same as in the topmost EMail element, or
they can be different. For example, the "inner" EMail element Subject element can be different.
Note: you cannot specify both the sign and encrypt attributes for the topmost EMail element.
To send an encrypted and signed message, add the sign attribute to the inner EMail element.
Example:
The Client submits an encrypted and signed text message to the toName@domain address. Note unmatching subjects.
The Client requests delivery notification.
C:<messageSubmit id="A001" useDSN="yes" >
<EMail encrypt="yes" addressBook="Contacts" >
<From realName="Sender Name">fromName@domain</From>
<Subject>A message regarding your request</Subject>
<To realName="Recipient Name">toName@domain</To>
<EMail sign="yes">
<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,

I will come to your place tomorrow, thank you for the invitation!
Mary.
</MIME>
</EMail>
</EMail>
</messageSubmit>
S:<response id="A001"/>
Contacts (vCard and vCardGroup) 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.
MIME parts with the text type and
x-vgroup subtype contain one vCardGroup element.
To include vCard data into a message (using the messageAppend, messageSubmit operations)
include a MIME element with type="text" and subtype="directory" attributes.
The element body should contain one or more vCard elements.
To include vCardGroup data into a message (using the messageAppend, messageSubmit operations)
include a MIME element with type="text" and subtype="x-vgroup" attributes.
The element body should contain one vCardGroup element.
The Contact-class Mailboxes are used to store special messages ("items") containing only vCard or vCardGroup data.
In a properly composed vCard item:
- the Subject field contains the vCard FN property.
- the To field contains the vCard EMAIL properties.
- the X-Telnum field contains the vCard TEL properties.
- the X-Has-Certificate field exists and contains the true value if the vCard contains a KEY property.
In a properly composed vCardGroup item:
- the Subject field contains the vCardGroup NAME property.
Use the following operations to compose, store, and retrieve these special messages:
- contactAppend
- This operation composes a special E-mail message containing the vCard or vCardGroup data as its body, forms
all necessary E-mail message header fields and stores the resulting message in the specified Folder or Mailbox.
- Attributes:
- folder
- the target Folder name. If specified, the targetMailbox attribute is ignored.
- targetMailbox
- the target Mailbox name. It must be specified if the folder attribute is absent.
if the target Mailbox does not exist, it is created.
- flags, replacesUID, replaceMode, report
- these optional attributes have the same meaning as the same messageAppend attributes.
If the flags attribute is not specified, its value assumed to be Seen.
Body:
- exactly one vCard or vCardGroup 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:<contactAppend 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>
</contactAppend>
S:<response id="A011"/>
- contactsImport
- This operation parses an uploaded file, which should contain vCard items. The resulting items are copied into the specified Folder.
- Attributes:
- folder
- the Folder name.
- uploadID
- a string identifying a file in the "uploaded file set".
- contactFind
- This operation searches the open Folder for vCard items (messages) with an E-mail or Telephone number matching the specified address.
When a "fuzzy" search is requested, the operation searches for vCard items containing
E-mail addresses or "File as" names that include the specified address as a substring.
Only the E-mail message header fields (To and X-Telnum) are checked, not the actual vCard data.
- Attributes:
- folder
- the Folder name.
- totalSizeLimit
- same as for the folderRead operation. If set to zero, no vCard message body is returned.
- peer
- the address to search for.
- limit
- the optional parameter limiting the number of items to find. The operation finishes when it finds the specified number of
matching items or when all folder items are checked.
- mode
- if this optional attribute is specified and it has the sub value, "fuzzy search" is requested.
The found vCard message content is sent to the client as the folderMessage data message, with the additional attributes:
- Attributes:
- folder, peer
- the same values as in the request.
- UID
- the found vCard message UID (numeric).
- foundAddress
- optional; the To or X-Telnum address element that matches the peer value.
- peerName
- optional; the "File as" name of found vCard.
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. Alternatively, a Calendar can represent an iCalendar document (a set of iCalendar events) retrieved
via the HTTP/HTTPS protocol using the specified URL.
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.
- url
- if specified, the URL of a remote iCalendar object. The object is retrieved, parsed, and all its VEVENT
elements are used as the Calendar object data. No Server Mailbox is read in this case.
- mailbox
- the Mailbox name. This attribute is used only if the url attribute is not specified.
If this attribute is not specified, the calendar name is used.
A session can use several open Calendars at the same time.
- calendarClose
- This operation closes an open Calendar.
- Attributes:
- calendar
- the Calendar name.
- 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).
- byAlarm
- if this optional attribute exists, and its value is yes, the operation looks not for the Events in the specified
time interval, but for the Events that have an Alert element set within the specified time interval.
- 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 one events data message for each 24-hour day (in the selected time zone) included into the specified time interval.
- findTasks
- This operation retrieves the VTODO objects from the specified Calendar. Only the Tasks that fall into the specified time interval are retrieved.
- Attributes:
- calendar, timeFrom, timeTill, byAlarm, limit, skip
- these attributes have the same meanings as the findEvents operation attributes.
The Server sends one tasks data message for each 24-hour day (in the selected time zone) included into the specified time interval.
- calendarRead
- This operation tells the Server to retrieve a Message or its part. It is sent to the client as a calendarMessage data message.
This operation is the same as the folderRead operation, but instead of the folder attribute it
uses the calendar to specify the open Calendar name.
Note: this operation cannot be applied to a Calendar object built using a remote (URL-specified) iCalendar object.
Use the calendarReadItem operation instead.
- calendarReadItem
- This operation tells the Server to retrieve a calendar item. It is sent to the client as a calendarItem data message.
- Attributes:
- calendar
- the Calendar name.
- UID
- the item message UID (a number).
- 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.
Otherwise, 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.
A meeting or task request is sent to all participants, or, if this attribute value is new, to all newly added participants.
- copyExceptions
- if this optional attribute value is not no and the item does not contain the recurrenceID element,
and the Calendar already contains an item with the same UID, all recurrence exceptions from the existing item are copied
into the newly published item.
Body:
- An iCalendar element to place into the selected Calendar,
and optional MIME and/or copyMIME elements
to add (the same as elements used with the messageAppend operation).
If no MIME or copyMIME element is present, and there is an existing Calendar item
with the same UID, the attachments are copied from that item. To prevent this, include an empty noMIME element.
The iCalendar element may contain optional vtimezone elements, and it
should contain exactly one calendaring item element.
It is not required to include a vtimezone element for a time zone
used in a calendaring item element if this time zone is one of the standard time zones known to the Server.
It is allowed to omit a time zone name in the properties containing date values without the Z suffix.
In this case the time zone selected as the current user Preference TimeZone value is used.
If the item does not contain an UID element, the Server generates a unique UID and adds it to the item.
To create or update a recurrence exception item, include the recurrenceID element into the vevent element.
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 without 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
- optional; the message UID (numeric).
- itemUID
- optional; the Event item (iCalendar) UID string.
- recurrenceId
- optional; the recurrence ID timestamp.
- sendRequests
- if this optional attribute is no, cancel request messages are not sent to the item attendees.
Body:
- an optional iCalendar element to cancel.
If this element is not specified, the item with the specified iCalendar Event UID or the specified message UID is taken from the Calendar.
Then all items with the same Event item (iCalendar) UID are removed.
- optional requestComment element containing a text body - a comment to include into the cancel request message.
To cancel only one recurrence of a recurrent event either specify an iCalendar element with the
recurrenceId sub-element, or, if the iCalendar element is not specified, use the recurrenceId attribute.
- calendarUpdate
- This operation updates a calendaring item in a Calendar using a reply-type iCalendar object.
This item specifies if a particular attendee has accepted or rejected the invitation.
- Attributes:
- calendar
- the Calendar name.
Body:
- The iCalendar reply-type item.
- calendarForward
- This operation tells the Server to compose a copy of an Event stored in a Calendar, and to submit it to the Queue for delivery as a Meeting request.
- Attributes:
- calendar
- the Calendar name.
- UID
- the Event UID.
Body:
- A set of one or more To elements specifying the recipient address(es).
- calendarAccept
- This operation places a calendaring item into a Calendar and sends a positive reply the item organizer.
The existing items(s) with the same UID are replaced.
- Attributes:
- calendar
- the Calendar name.
- PARTSTAT
- the acceptance status: ACCEPTED, TENTATIVE, IN-PROCESS (Tasks only), COMPLETED (Tasks only).
- sendReply
- if this optional attribute is no, no reply message is sent to the item organizer.
- folder
- the optional Folder name from which the invitation calendar element was read. This attribute is used to find the Folder owner and direct Calendar operations to the owner's default Calendar.
- proposedTimeStart
- an optional attribute with the new time for the event to start; if the attribute is set the COUNTER calendar response is sent to the event organizer.
Body:
- The iCalendar element to place into the selected Calendar;
- optional MIME and/or copyMIME elements to add (the same as elements used with the messageAppend operation);
- optional replyComment element containing a text body - a comment to include into the reply message.
If the item is placed successfully, the iCalendar reply message is sent to the item organizer.
Replies are not sent for Event items specifying the current user as an attendee with RSVP=FALSE parameter,
or if the request sendReply attribute is set to no.
- calendarDecline
- This operation rejects a calendaring item and sends a negative reply the item organizer.
- Attributes:
- calendar
- the Calendar name. This parameter is optional.
If specified, the items with the same UID are removed from this Calendar.
If the item has the recurrenceId element, then only this exception is removed from the Calendar.
- sendReply
- if this optional attribute is no, no reply message is sent to the item organizer.
- folder
- the optional Folder name from which the invitation calendar element was read. This attribute is used to find the Folder owner and direct Calendar operations to the owner's default Calendar.
- proposedTimeStart
- an optional attribute with the new time for the event to start; if the attribute is set the COUNTER calendar response is sent to the event organizer.
Body:
- The iCalendar element to decline.
- optional replyComment element containing a text body - a comment to include into the reply message.
Use this operation when a user decides not to attend a meeting stored as a published item in a Calendar.
(if the current user is the meeting organizer, use the calendarCancel operation instead).
Specify the published item itself and the calendar attribute to remove the item from the Calendar.
The operation sends a negative reply message to the item organizer (unless the sendReply attribute is set to no).
Use this operation when a user opens a request item (in an incoming E-mail) and decides to decline that request.
Specify the request item, and do not specify any calendar attribute.
The operation sends a negative reply message to the item organizer (unless the sendReply attribute is set to no).
Use this operation when a user opens a cancellation request item (in an incoming E-mail),
and decides to remove the canceled item from the Calendar.
Specify the cancellation request item and the calendar attribute (usually - the Main Calendar name),
to remove the corresponding item(s) from that calendar.
The operation does not send any reply message.
If the specified item is a request, the operation sends a negative reply message to the item organizer.
If the specified item is a cancel request item, the operation does not send a reply message to the item organizer; specify the calendar attribute to remove the corresponding item from the calendar.
- calendarImport
- This operation parses an uploaded file, which should contain iCalendar/vCalendar items. The resulting items are copied into a Calendar. The existing items(s) with the same UID are removed.
- Attributes:
- calendar
- the Calendar name.
- uploadID
- a string identifying a file in the "uploaded file set".
- freeBusyRead
- This operation retrieves the FreeBusy information for the specified Account.
- Attributes:
- userName
- the target Account name. If this attribute is not specified, the current Account FreeBusy information is retrieved.
- timeFrom, timeTill
- the beginning and the end of the time interval (time values should be specified for the selected time zone).
The Server sends a freeBusyData data message.
The Server sends the following data messages:
- events
- This synchronous data message is sent when the Server processes the findEvents request.
- Attributes:
- calendar, timeFrom, timeTill, skip
- the same as in the findEvents request.
- items
- the total number of Events found.
Body:
- a set of event elements for each Event found.
- Attributes:
- UID
- the Event message UID (a number).
- itemUID
- the Event item (iCalendar) UID string.
- timeFrom
- the time when this Event starts (in the selected time zone). This attribute is not included for "all-day" Events when the byAlarm mode is not set.
- dateFrom
- the date when this Event starts (in the selected time zone). This attribute is included for "all-day" Events only, and only when the byAlarm mode is not set.
- duration
- the Event duration (in seconds).
- alarmTime
- this attribute is included only if the request contained the byAlarm attribute. The attribute value specifies the time (in the selected time zone) when the Event Alarm should take place.
- busyStatus
- the Event busy status (BUSY, TENTATIVE, UNAVAILABLE, FREE).
- organizer
- this attribute is present and it has the yes value if the current user is the organizer of the Event.
- recurrence
- this attribute is present and it has the yes value if the Event is a recurrent one.
- recurrenceId
- this attribute is present if the found Event is an exception of its main Event. The attribute value is a time stamp identifying this exception.
- attendees
- this attribute is present if the Event has attendees. The attribute value is the number of attendees.
- location
- this attribute is present if the Event has the Location element. The attribute value is the Location element value, optionally shortened.
- priority
- this attribute is present if the Event has its priority set.
Body:
- Event fields: summary
- tasks
- This synchronous data message is sent when the Server processes the findTasks request.
- Attributes:
- calendar, timeFrom, timeTill, skip
- the same as in the findTasks request.
- items
- the total number of tasks found.
Body:
- a set of task elements for each Task found.
- Attributes:
- UID
- the Task message UID (a number).
- itemUID
- the Task item (iCalendar) UID string.
- timeFrom
- the time when this Task starts (in the selected time zone).
- due
- the time this Task is due (in the selected time zone).
- percent-complete
- the Task completion stage; a number, usually in the 0..100 range.
- alarmTime
- this attribute is included only if the request contained the byAlarm attribute. The attribute value specifies the time (in the selected time zone) when the Task Alarm should take place.
- organizer
- this attribute is present and it has the yes value if the current user is the organizer of the Task.
- recurrence
- this attribute is present and it has the yes value if the Task is a recurrent one.
- recurrenceId
- this attribute is present if the found Task is an exception of its main Task. The attribute value is a time stamp identifying this exception.
- attendees
- this attribute is present if the Task has assignees. The attribute value is the number of assignees.
- location
- this attribute is present if the Task has the Location element. The attribute value is the Location element value, optionally shortened.
- priority
- this attribute is present if the Task has its priority set.
Body:
- Task fields: summary
- calendarReport
- These asynchronous data messages are sent when the Calendar data is modified.
- Attributes:
- calendar
- the Calendar name.
- mode
- this optional attribute specifies the type of notification.
- If the attribute value is notify some calendar messages have been added, modified, or deleted.
The client is expected to re-send the findEvents request for this Calendar.
After the Server sends a "notify-mode" calendarReport message to the Client,
the Server may choose not to send further "notify-mode" messages for this Calendar until the client
performs the findEvents operation on this Calendar.
- calendarMessage
- This synchronous data message is sent when the Server processes the calendarRead request.
This message is the same as folderMessage, but instead of the folder attribute
it contains the calendar attribute with the Calendar name.
- calendarItem
- This synchronous data message is sent when the Server processes the calendarReadItem request.
- Attributes:
- calendar, UID
- the copy of the calendarReadItem request attributes.
Body:
- the xml presentation of the calendar item (vevent, vtodo).
- freeBusyData
- This synchronous data message is sent when the Server processes the freeBusyRead request.
Attributes:
- userName
- the copy of the same freeBusyRead request attribute.
Body:
- the vfreebusy object containing a set of freebusy elements.
All time values returned are specified as the local time in the Time Zone selected for the current user.
After the Server sends a "notify-mode" calendarReport message to the Client,
the Server may choose not to send further "notify-mode" messages for this Calendar until the client
performs the findEvents operation on this Calendar.
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. The callLeg attribute is present in all call-related operation requests
and in all Server data messages related to that call. Each call is independent.
For each call, a Client should be able to create one or several "media objects", which implement actual media (audio, video, etc.) communications.
The media descrptor element ("SDP elements") are data elements (text or XML) that a Client retrieves from and sends to "media objects".
As a minimum, it should be possible to perform the following operations on each media object:
- retrieve an "offer" SDP from the media object, and then send it an "answer" SDP that describes the media object of the communication peer; or
- send an "offer" SDP describing a communication peer to the media object, and then retrieve an "answer" SDP from that media object.
If it is not possible to re-send an "offer" SDP to an already active media object, a new media object should be created, and the new "offer" SDP is sent to.
If the "answer" SDP is successfully retrieved from the new media object, the old media object should be disposed of.
If it is not possible to re-retreive an "offer" SDP from an already active media object, a new media object should be created, and an "offer" SDP is retreieved from it.
When the "answer" SDP received and sent to the new media object, the old media object should be disposed of.
A media object supports "forking" if it is possible to retrieve a single "offer" SDP from that media object, and then send several "answer" SDP elements to that media object, establishing several concurrent media communication channels.
Many messages and operation requests described in this section may contain an "SDP descriptor" as the XML body.
The SDP descriptor may be specified using the XML presentation, or as
an sdpText XML element with the SDP descriptor in the native SDP text format.
The signalBind operation request specifies the format that the Server will be using in its messages (see below).
- signalBind
- This operation allows the current XIMSS session to receive signals directed to the authenticated user.
- Attributes:
- clientID
- an optional parameter specifying a name for this session. If not specified, the Server generates a unique one.
- mode
- if this attribute exists, and its value is fixed, the Server rejects the operation
if the Account already has an open session using the same name;
if this attribute exists, and its value is kill, the Server closes the currently
opened Account session with the same name (if any).
if this attribute does not exist or it has some other value, the Server generates a unique name for this session
if the Account already has an open session that uses the specified name;
- presence
- if this optional attribute exists, and its value is yes, the client starts to receive Roster and Presence notifications.
- readIM
- if this optional attribute exists, and its value is 1, the readIM messages use the "extended" format.
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).
An sdpText XML element can be used instead of the SDP element.
The sdpText XML element body should be text containing SDP data in the SDP native format.
If the sdpText is used, then SDP information in callIncoming, callProvisioned, callConnected, and callUpdated Server messages
is also presented using the sdpText XML element.
- 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 release all associated resources.
If the call was in the 'calling' state, the outgoing call is canceled.
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.
Outgoing calls are initiated by the Client using the callStart operation request.
The Client should generate a unique callLeg attribute value for the callStart request. All other requests and messages related to this call will have the same callLeg attribute value.
When an outgoing call is started, the Server may send:
Each of these messages contains a tag attribute, identifying an "early dialog" (a "ringing" device) .
When an outgoing call is started, the Client may send:
An outgoing call becomes an "established" call when the Server sends a callConnected message.
An outgoing call fails if the Server sends a callDisconnected message.
The Client can cancel a pending outgoing call using the callKill operation.
Incoming calls are initiated by the Server sending to the Client a callIncoming message.
The Server generates a unique callLeg value for the callIncoming message. All other requests and messages related to this call will have the same callLeg attribute value.
The Server-generated callLeg value for incoming calls use the inp prefix, so the Client should not use this prefix for the callLeg values it generates for outgoing calls.
When an incoming call is received, the Server may send:
When an incoming call is received, the Client may send:
An incoming call fails (it is cancelled) if the Server sends a callDisconnected message.
The Client can end processing an incoming call by rejecting the call with the callReject operation,
or by redirecting the call with the callRedirect operation.
The Client can accept an incoming call with the callAccept operation, making it an "established" call.
When an outgoing call connects or when an incoming call is accepted, the call becomes an "established" one.
Media in an established call flows in both directions (unless one party decides to put the call "on hold").
When a call is established, the Server may send:
When a call is established, the Client may send:
An established call ends if the Server sends a callDisconnected message.
The Client can end an established call using the callKill operation.
- 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.
- peerName
- an optional string - the real name of the callee.
Body (optional):
- An SDP descriptor.
If the callStart request succeeds, the new call object is created and an outgoing call is initiated.
Note: the client should be ready to process call-related Server messages even before the client receives the positive response for this callStart request.
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.
Media Handling
Call with SDP: the Client creates a media object (called "untagged" object).
The Client should configure the created media object to operate in the "receiving-only" mode.
The Client retrieves an "offer SDP" from that untagged media object, and sends that SDP with the 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 with the client.
Call without SDP: the Client does not create any media object. The Cleint sends the callStart request without an SDP body element.
Optionally, the Client should be prepared to create additional media objects and to build an "association mapping", where each created media object is accociated with a string - a value of
the tag attribute of the receieved callProvisioned and/or callUpdateRequest messages.
- callProvision
- Use this operation to provision an incoming call (the call object is created when the callIncoming message is received from the Server).
Call provisioning informes the caller that the callee is being alerted (the callee's "phone rings").
- Attributes:
- callLeg
- the incoming call identifier.
Body (optional):
- An SDP descriptor.
When the operation completes, the Client will receive the callUpdated message from the Server.
Media Handling
If the Client wishes to send "early media" to the caller, the Client sends a callProvision request with SDP. "Early media" may be played by the caller's device instead of its default "ringback" tones.
To send early media, the Client should create an untagged media object.
The Client should configure the created media object to operate in the "sending-only" mode.
- If the callIncoming message contained an SDP:
- That SDP element is an "offer".
The Client should send this "offer" SDP to the untagged media object.
Then the Client should retrieve the "answer" SDP from that media object and send it to the Server using the callProvision request.
Then the Client can instruct the media object to play the desired "early media".
- If the callIncoming message did not contain an SDP:
- The Client should retrieve an "offer" SDP from the untagged media object and send it to the Server using the callProvision request.
When the Client receives the callUpdated message from the Server, it will contain an error code or an "answer" SDP.
If the "answer" SDP is received, the Client should send it to the untagged media object, and then the Client can instruct the media object to play the desired "early media".
- callRedirect
- Use this operation to redirect an incoming call.
- Attributes:
- callLeg
- the incoming call identifier.
- fork
- if this optional attribute exists, and its value is yes, the call is directed to the specified destinations, but it is still pending
for this session, and it can be accepted or rejected.
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"/>
Media Handling
The Client should dispose of all media objects associated with this call.
- 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 to the Signal 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).
If this parameter is not specified, the 603 code is used.
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"/>
Media Handling
The Client should dispose of all media objects associated with this call.
- callAccept
- Use this operation to accept an incoming call.
- Attributes:
- callLeg
- the incoming call identifier.
Body (optional):
- An SDP descriptor.
When the operation completes, the Client will receive the callUpdated message from the Server.
Media Handling
The Client should create an untagged media object, if it has not been created yet.
- If the Client has already sent a callProvision request with SDP:
- The callAccept request should contain no SDP element, and the callUpdated message will not contain any SDP element.
- If the Client has not sent any callProvision request with SDP, and the callIncoming message contained an SDP:
- That SDP element is an "offer".
The Client should send this "offer" SDP to the untagged media object.
Then the Client should retrieve the "answer" SDP from that media object and send it to the Server using the callAccept request.
When the connection is established, the Client will receive the callUpdated message without an SDP from the Server.
- If the Client has not sent any callProvision request with SDP, and the callIncoming message did not contain an SDP:
- The Client should retrieve an "offer" SDP from the untagged media object and send it to the Server using the callAccept request.
The Client will receive the callUpdated message from the Server, which contains an "answer" SDP.
The Client should send that "answer" SDP to the untagged media object.
The Client should configure the "untagged" media object to stop playing "early media" and to operate in the "sending and receiving" mode.
- callUpdate
- Use this operation to update a call (to modify the call SDP descriptor). The Client may need to use this function if it places a call on hold or resumes it,
when it changes the number and/type of the media streams (for example, adds a vidio stream to an audio call), switches to a different media object, etc.
- Attributes:
- callLeg
- the call identifier.
- tag
- optional: the "to-tag" (dialog/fork ID) of an "early" dialog; should be used when updating an outgoing call.
Body (optional):
- An SDP descriptor.
When the operation completes, the Client will receive a callUpdated message from the Server.
If the operation fails, the callUpdated message contains signalCode and errorText attributes.
If the operation succeeds, the callUpdated message does not contain these attributes.
Media Handling
If the Client does not want to modify the call SDP descriptor, it should send the callUpdate request without an SDP descriptor.
The Server will send back a callUpdatedmessage without an SDP element.
To modify the call SDP descriptor, the Client should retrieve a new "offer" SDP from the untagged media object.
Alternatively, it should create a new media object and retrieve the "offer" SDP from it.
This "offer" SDP should be sent using the callUpdate request.
If the callUpdated message received does not contain an errorText attribute, it contains an "answer" SDP, and the Client should send it to the same media object.
If it is a newly created media object, the old "untagged" media object should be removed, and the new one should become the current "untagged" media object.
If the operation fails, the callUpdated message contains an errorText attribute. In this case, the untagged media object should be reverted to its previous state.
If a new media object has been created to retrieve an "offer" SDP, that new media object should be removed.
- 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 data message is sent to the client).
Additionally, in the case of an "attended transfer", the client receives the callDisconnected message for the "otherLeg" call, too.
If the call transfer operation fails, a callOpFailed data message is sent to the client.
- callUpdateAccept
- Use this operation to accept call SDP modifications.
- Attributes:
- callLeg
- the call identifier.
Body (optional):
- An SDP descriptor.
The Client should send this request in response to callUpdateRequest, callProvisioned, and
callConnected messages. See the description of these messages for the details.
- callUpdateReject
- Use this operation to reject call SDP modifications.
- Attributes:
- callLeg
- the call identifier.
- signalCode
- the numeric code (defined with the SIP standards) to pass to the Signal component as an error code.
If this attribute is absent, the 488 code ("Not Acceptable Here") is used.
Body:
- none.
The Client should send this request instead of the callUpdateAccept request if the Client fails to perform the requested SDP modification.
See callUpdateAccept description for the details.
- callSendDTMF
- Use this operation to send a DTMF signal via the signaling path.
- Attributes:
- callLeg
- the call identifier.
Body:
- a one-symbol string with the DTMF code to send (10 for '*', 11 for '#').
If the operation succeeds, the server sends a callOpCompleted message.
If the operation fails, the server sends a callOpFailed message.
- callSendInfo
- Use this operation to send an INFO signal to the connected peer.
- Attributes:
- callLeg
- the call identifier.
Body:
- a MIME XML element:
- Attributes:
- type
- INFO content Content-Type.
- subtype
- INFO content subtype (optional).
Body:
- a string with INFO content data.
If the operation succeeds, the server sends a callOpCompleted data message.
If the operation fails, the server sends a callOpFailed data message.
- makeCall
- Use this operation to establish a call using any registered device or client. The Server initiates a call
to the authenticated Account ("self-call"), causing all its registered devices and clients to ring.
When any device answers the call, that device is instructed to call the specified address (or telephone number).
- Attributes:
- peer
- an E-mail address or a SIP URI to call.
- callerParams
- an optional attribute containing SIP R-URI (request-URI) parameters for the "self-call".
The operation completes as soon as the CG/PL task implementing this functionality is started.
Asynchronous makeCallReport data messages are sent when the status of this task changes.
When the call attempt completes, an empty makeCallReport data message is sent.
The Server can send the following data messages:
- callDisconnected
- These asynchronous data messages are sent when an outgoing call fails, when an incoming call is canceled,
or when an established call disconnects:
- Attributes:
- callLeg
- the call identifier.
- signalCode
- this optional attribute specifies the numeric signaling error code.
- errorText
- optional: specifies the call disconnect reason.
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.
Media Handling
Dispose of all media objects associated with this call.
- callProvisioned
- These asynchronous data messages are sent when there is an outgoing call in progress, after a callStart request was sent to the Server:
- Attributes:
- callLeg
- the call identifier.
- callId
- the call Call-Id string
- tag
- the "to-tag" (dialog/fork ID) of an outgoing "early" dialog.
Body (optional):
- An SDP descriptor.
In response, the Client should send a callUpdateAccept or a callUpdateReject request to the Server.
Media Handling
- If the callProvisioned message does not contain an SDP element:
- if there is a media object or a ringback player associated with the tag attribute value, the Client should ignore this message.
Otherwise, the Client should create a ringback player (which plays a "ringback" sound, informing the user that the callee is being alterted), and associate this player with the tag attribute value.
- If the callProvisioned message contains an SDP element, and there is a media object associated with the tag attribute value:
- The SDP element is an "offer".
The Client should use this "offer" SDP to update the associated media object.
Then the Client should retrieve the "answer" SDP from that media object and send it to the Server using the callUpdateAccept request.
- If the callProvisioned message contains an SDP element, there is no media object associated with the tag attribute value, and the callStart request contained an "offer" SDP:
- The SDP element is an "answer".
The Client should remember this "answer" SDP associated with the tag attribute value, replacing any older SDP associated with this tag attribute value.
If the "untagged" media object supports forking, the Client should send this "answer" SDP to that media object; the Client should also remove any ringback object associated with the tag attribute value.
If the "untagged" media object does not support "forking", the Client should create a ringback player and associate it with the tag attribute value, if a ringback player associate with this value does not already exist.
- If the callProvisioned message contains an SDP element, there is no media object associated with the tag attribute value, and the callStart request did not contain an SDP:
- The SDP element is an "offer".
The Client should create a new media object and associate it with the tag attribute value. If there is a ringback object associated with the tag attribute value, the Client should remove it.
The Client should send this "offer" SDP to the newly created media object, retrieve the "answer" SDP from the media object, and send this "answer" SDP to the Server using the callUpdateAccept request.
If the Client cannot process the callProvisioned message, it should send the callUpdateReject request to the Server.
- callConnected
- These asynchronous data messages are sent when an outgoing call (initiated with a callStart request) succeeds,
and the call is established:
- Attributes:
- callLeg
- the call identifier.
- callId
- the call Call-Id string
- peer
- the address of the peer which has accepted this call.
- tag
- the "to-tag" (dialog/fork ID) of the established dialog.
Body (optional):
- An SDP descriptor.
In response, the Client should send a callUpdateAccept or a callUpdateReject request to the Server.
Media Handling
- If there is a media object associated with the tag attribute value, and the callConnected message does not contain an SDP element:
- The Client should remove all other media objects and all ringback players. The selected media object becomes the "untagged" media object.
- If there is a media object associated with the tag attribute value, and the callConnected message contains an SDP element:
- The SDP element is an "offer".
The Client should send this "offer" SDP to the selected media object. Then the Client should retrieve the "answer" SDP from that media object and send it to the Server using the callUpdateAccept request.
The Client should remove all other media objects and all ringback players. The selected media object becomes the "untagged" media object.
- If there is no a media object associated with the tag attribute value, the callStart request contained an "offer" SDP, and the callConnected message contains an SDP element:
- The SDP element is an "answer".
The Client should send this "answer" SDP to the "untagged" media object. If the media object supports "forking" and some "answer" SDP have been sent to it, the Client should instruct the media object so stop these other media communications.
The Client should remove all tagged media objects and ringback players.
- If there is no a media object associated with the tag attribute value, the callStart request contained an "offer" SDP, and the callConnected message does not contain an SDP element:
- The SDP element is an "answer".
If the media object supports "forking", then some "answer" SDP associated with the tag attribute value has been already sent to it. The Client should instruct the media object to stop all other media communications.
If the media object does not support "forking", then some "answer" SDP received with a callProvisioned message and associated with the tag attribute value should be "remembered".
The Client should send this remembered "answer" SDP to the untagged media object.
The Client should remove all tagged media objects and ringback players.
- If there is no a media object associated with the tag attribute value, the callStart request did not contain an "offer" SDP:
- The callConnected message must contain an SDP element, and that SDP element is an "offer".
The Client should create a new media object, and to send this "offer" SDP to the new media object. Then the Client should retrieve the "answer" SDP from that media object and send it to the Server using the callUpdateAccept request.
The Client should remove all other media objects and all ringback players. The created media object becomes the "untagged" media object.
The "untagged" media object (the only media object left) should be instructed to use the "sending and receiving" mode.
- callIncoming
- These asynchronous data messages are sent when 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.
- peer
- the remote peer E-mail address.
- peerName
- optional; the remote peer real name.
- callId
- the call Call-Id string
- transferredBy
- optional; the E-mail address of the person who has transferred this call.
Body (optional):
- An SDP descriptor.
Media Handling
The Client may create an "untagged" media object immediately, or it may create it when the Client sends callProvision or callAccept requests.
- If the callIncoming message contains an SDP element:
- The SDP element is an "offer".
The Client should pass this SDP to the "untagged" media object when it is created.
- callUpdateRequest
- These asynchronous data messages are sent when the communication peer wants to update the call parameters (such as SDP).
- Attributes:
- callLeg
- the call identifier.
- tag
- optional: the "to-tag" (dialog/fork ID) of an "early" dialog.
Body (optional):
- An SDP descriptor.
The client should answer by sending the callUpdateAccept or callUpdateReject request to the Server.
Media Handling
- If the callUpdateRequest message does not contain an SDP element, the Client can ignore it.
- If the callUpdateRequest message contains an SDP element:
- This element is an "offer" SDP.
If the call is still outgoing, the Client should remove any "ringback player" associated with this tag.
The Client should find the media object associated with the tag attribute (or create a new media object if none is found).
If no tag attribute is specified, the "untagged" media object should be used.
The "offer" SDP from the callUpdateRequest message should be used to update the selected media object.
The client should retrieve the "answer" SDP from the selected media object, and send it to the Server using the callUpdateAccept request.
If the client does not want to or cannot accept the new "offer" SDP, it should inform the Server using the callUpdateReject request.
- callUpdated
- These asynchronous data messages are sent when an existing call is updated (placed on hold, switched to a different remote peer, etc.).
- Attributes:
- callLeg
- the call identifier.
- peer
- optional; the remote peer E-mail address. It is sent when a call has been transferred.
- peerName
- optional; the remote peer real name.
- signalCode
- this optional attribute specifies the numeric signaling error code.
- errorText
- optional; the error message.
Body (optional):
- An SDP descriptor.
This message is received in response to the callUpdate,
callProvision, callAccept requests. See the description of those requests for the details.
If the operation fails, the signalCode and errorText attributes are present.
If the operation succeeds, the signalCode and errorText attributes are absent, and an SDP descriptor may be present.
- callUpdateSolicited
- These asynchronous data messages are sent when the communication peer wants to update the call SDP descriptor, but it wants this Client to provide an SDP offer.
- Attributes:
- callLeg
- the call identifier.
- tag
- optional: the "to-tag" (dialog/fork ID) of an "early" dialog.
Body (optional):
- An SDP descriptor.
The Server sends these messages only when a call is established or when an outgoing call is pending.
Media Handling
The Client should execute the callUpdate operation with a new "offer" SDP.
If the Client cannot initiate a callUpdate operation (for example, it cannot create a new media object), it should
send the callUpdateReject request to the Server.
For a pending outgoing call, the Client should create a "tagged" media object, from which it should retrieve the "offer" SDP for the callUpdate request.
- callOpCompleted
- These asynchronous data messages are sent when in-call operations (such as callUpdate, callSendDTMF, callSendInfo) are completed.
- Attributes:
- callLeg
- the call identifier.
- callOpFailed
- These asynchronous data messages are sent when in-call operations (such as callUpdate, callSendDTMF, callSendInfo) fail.
- Attributes:
- callLeg
- the call identifier.
- signalCode
- the numeric signaling error code.
- errorText
- the error message.
- callDTMF
- These asynchronous data messages are sent when a DTMF signal is received via the signaling path.
- Attributes:
- callLeg
- the call identifier.
Body:
- A string with the numeric DTMF code received.
- callTransferred
- These asynchronous data messages are sent when the remote peer has transferred the call to a different peer.
- Attributes:
- callLeg
- the call identifier.
- peer
- the new peer address.
- peerName
- optional; the new peer real name.
- callId
- the call Call-Id string; call transfer usually results in a Call-Id change.
- mode
- a hint on transfer scenario.
- tag
- a dialog fork identifier.
Body:
- Empty.
- callInfo
- These asynchronous data messages are sent when an INFO signal is received:
- Attributes:
- callLeg
- the call identifier.
Body:
- the same as in the callSendInfo request.
- makeCallReport
- These asynchronous data messages are sent after the makeCall operation is initiated.
- Body:
- A string containing the current operation status. A message contains an empty body if the calling process completes.
Example Incoming-01. Incoming call session with an initial SDP. The Client does not send any custom "ringback" media to the caller.
The Client receives a callIncoming message with a Server-generated callLeg attribute.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>
The Client starts to alert the user (the Client starts "ringing").
The Client notifiers the caller that the user is being alerted:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>
The user instructs the Client to accept this incoming call.
The Client creates an "untagged" media object A, and sends the received SDP:X(offer) (an "offer" SDP) to that media object A.
The Client retrieves an "answer" SDP from the media object A, and sends it to the Server, accepting the call:
C:<callAccept id="A002" callLeg="inp01">SDP:A(answer)</callAccept>
S:<response id="A002"/>
The Server sends back the callUpdated message:
S:<callUpdated callLeg="inp01"/>
Note: the callUpdated may arrive before arrival of the response message for the callAccept request.
The Client stops "ringing".
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
S:<callDisconnected callLeg="inp01" />
The call ends, the Client removes the "untagged" media object A.
The Client releases the Server resources associated with this call:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>
Example Incoming-02. Incoming call session without an initial SDP. The Client does not send any custom "ringback" media to the caller.
The Client receives a callIncoming message with a Server-generated callLeg attribute.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" />
The Client starts to alert the user (the Client starts "ringing").
The Client notifiers the caller that the user is being alerted:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>
The user instructs the Client to accept this incoming call.
The Client creates an "untagged" media object A, and retrieves an "offer" SDP from this media object: SDP:A(offer).
The Client sends this SDP to the Server, accepting the call:
C:<callAccept id="A002" callLeg="inp01">SDP:A(offer)</callAccept>
S:<response id="A002"/>
The Server sends back the callUpdated message with an "answer" SDP:
S:<callUpdated callLeg="inp01">SDP:X(answer)</callUpdated>
Note: the callUpdated may arrive before arrival of the response message for the callAccept request.
The Client stops "ringing".
The Client sends the received "answer" SDP to the media object A.
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
S:<callDisconnected callLeg="inp01" />
The call ends, the Client removes the "untagged" media object A.
The Client releases the Server resources associated with this call:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>
Example Incoming-03. Incoming call session with an initial SDP. The Client does not send any custom "ringback" media to the caller.
The call has been cancelled by the caller (or some other client or device has answered this call).
The Client receives a callIncoming message with a Server-generated callLeg attribute.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>
The Client starts to alert the user (the Client starts "ringing").
The Client notifiers the caller that the user is being alerted:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>
The incoming call is cancelled:
S:<callDisconnected callLeg="inp01" />
The call ends (it is a "missed" call for this Client), the Client stops "ringing".
The Client releases the Server resources associated with this call:
C:<callKill id="A002" callLeg="inp01"/>
S:<response id="A002"/>
Example Incoming-04. Incoming call session with an initial SDP. The Client does not send any custom "ringback" media to the caller.
The call has been declined by the user.
The Client receives a callIncoming message with a Server-generated callLeg attribute.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>
The Client starts to alert the user (the Client starts "ringing").
The Client notifiers the caller that the user is being alerted:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>
The incoming call is declined:
S:<callReject id="A002" callLeg="inp01" signalCode="603" />
S:<response id="A002"/>
The call ends, the Client stops "ringing".
The Client releases the Server resources associated with this call:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>
Example Incoming-05. Incoming call session with an initial SDP. The Client does not send any custom "ringback" media to the caller.
The user has redirected the call to the voicemail application.
The Client receives a callIncoming message with a Server-generated callLeg attribute.
S:<callIncoming id="A001" callLeg="inp01" peer="user@domain" >SDP:X(offer)</callIncoming>
The Client starts to alert the user (the Client starts "ringing").
The Client notifiers the caller that the user is being alerted:
C:<callProvision id="A001" callLeg="inp01"/>
S:<response id="A001"/>
The incoming call is redirected:
S:<callRedirect id="A002" callLeg="inp01"><To>#voicemail</To></callRedirect>
S:<response id="A002"/>
The call ends, the Client stops "ringing".
The Client releases the Server resources associated with this call:
C:<callKill id="A003" callLeg="inp01"/>
S:<response id="A003"/>
Example Outgoing-01. Outgoing call session with an initial SDP.
The Client creates a media object A and makes it the "untagged" media object for the new call.
The Client retrieves the "offer" SDP from that object: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client already has a "ringback player" for this device (tag), so it does not do any additional media operation.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callConnected callLeg="c1" tag="device1">SDP:X(answer)</callConnected>
The Client removes the "ringback player", and passes the received SDP:X(answer) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>
S:<callDisconnected callLeg="c1" />
The call ends, the Client removes the "untagged" media object A.
The Client releases the Server resources associated with this call:
C:<callKill id="A005" callLeg="c1"/>
S:<response id="A005"/>
Example Outgoing-02. Outgoing call session with an initial SDP, multiple callee devices. Media objects do not support "forking".
The Client does not support advanced outgoing call messages.
The Client creates a media object A and makes it the "untagged" media object for the new call.
The Client retrieves the "offer" SDP from that object: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device2"/>
The Client creates one more "ringback player", so the user knows that the communication peer is being alerted. Both players are playing.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
The Client stores the SDP:X(answer1) received, associated with the tag "device1". No changes to the media, both players are playing.
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
The Client stores the SDP:X(answer2) received, associated with the tag "device1". It replaces the SDP:X(answer1) received for this tag earlier. No changes to the media, both players are playing.
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>
S:<callUpdateRequest callLeg="c1" tag="device3">SDP:Y(offer)</callUpdateRequest>
C:<callUpdateReject id="A006" callLeg="c1" errorText="not implemented" />
S:<response id="A006"/>
S:<callUpdateSolicited callLeg="c1" tag="device4" />
C:<callUpdateReject id="A006" callLeg="c1" errorText="not implemented" />
S:<response id="A006"/>
S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
The Client removes all "ringback players", and passes the received SDP:X(answer3) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
Alternatively, the <callConnected/> message could come without any SDP in it:
S:<callConnected callLeg="c1" tag="device1"/>
The Client removes all "ringback players", and retrieves the SDP:X(answer2) media descriptor, as it was the last one it stored for the "device1" tag.
The Client passes the received SDP:X(answer2) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A006" callLeg="c1"/>
S:<response id="A006"/>
The user instructs the Client to end this call, the Client ends this call and releases the Server resources associated with this call:
S:<callKill id="A007" callLeg="c1" />
S:<response id="A007"/>
The call ends, the Client removes the "untagged" media object A.
Example Outgoing-03. Outgoing call session with an initial SDP, multiple callee devices. Media objects do not support "forking", additional messages from the called devices.
The Client creates a media object A and makes it the "untagged" media object for the new call.
The Client retrieves the "offer" SDP from that object: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device2"/>
The Client creates one more "ringback player", so the user knows that the communication peer is being alerted. Both players are playing.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
The Client stores the SDP:X(answer1) received, associated with the tag "device1". No changes to the media, both players are playing.
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
The Client stores the SDP:X(answer2) received, associated with the tag "device1". It replaces the SDP:X(answer1) received for this tag earlier. No changes to the media, both players are playing.
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>
S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer)</callUpdateRequest>
The Client removes the "ringback player" associated with the "device2" tag.
The Client creates a new "tagged" media object B, and associates it with the "device2" tag. The media object B is configured to work in the "receiving only" mode.
The Client passes the received SDP:Y(offer) as an "offer" SDP to this media object B.
The Client retrieves the "answer" SDP from that media object: SDP:B(answer), and passes it to the Server:
C:<callUpdateAccept id="A006" callLeg="c1">SDP:B(answer)</callUpdateAccept>
S:<response id="A006"/>
S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
The Client removes all "ringback players", removes the "tagged" media object B, and passes the received SDP:X(answer3) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
Alternatively, the <callConnected/> message could come without any SDP in it:
S:<callConnected callLeg="c1" tag="device1"/>
The Client removes all "ringback players", removes the "tagged" media object B, and retrieves the SDP:X(answer2) media descriptor, as it was the last one it stored for the "device1" tag.
The Client passes the received SDP:X(answer2) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
Alternatively, the <callConnected/> message could come without any SDP in it, and with a different tag:
S:<callConnected callLeg="c1" tag="device2"/>
The Client removes all "ringback players", removes the "untagged" media object A, and makes the "tagged" media object B (associated with the "device2" tag) the new "untagged" media object.
The call has connected, the "untagged" media object (be it A or B) is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A007" callLeg="c1"/>
S:<response id="A007"/>
The user instructs the Client to end this call, the Client ends this call and releases the Server resources associated with this call:
S:<callKill id="A008" callLeg="c1" />
S:<response id="A008"/>
The call ends, the Client removes the "untagged" media object A.
Example Outgoing-04. Outgoing call session with an initial SDP, multiple callee devices. Media objects do not support "forking", additional messages from the called devices.
The Client creates a media object A and makes it the "untagged" media object for the new call.
The Client retrieves the "offer" SDP from that object: SDP:A(offer)
C:<callStart id="A001" callLeg="c1" peer="user@domain">SDP:A(offer)</callStart>
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device2"/>
The Client creates one more "ringback player", so the user knows that the communication peer is being alerted. Both players are playing.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer1)</callProvisioned>
The Client stores the SDP:X(answer1) received, associated with the "device1" tag. No changes to the media, both players are playing.
C:<callUpdateAccept id="A004" callLeg="c1"/>
S:<response id="A004"/>
S:<callProvisioned callLeg="c1" tag="device1">SDP:X(answer2)</callProvisioned>
The Client stores the SDP:X(answer2) received, associated with the "device1" tag. It replaces the SDP:X(answer1) received for this tag earlier. No changes to the media, both players are playing.
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>
S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer1)</callUpdateRequest>
The Client removes the "ringback player" associated with the "device2" tag.
The Client creates a new media object B, and associates it with the "device2" tag. The media object B is configured to work in the "receiving only" mode.
The Client passes the received SDP:Y(offer1) as an "offer" SDP to this media object B.
The Client retrieves the "answer" SDP from that media object: SDP:B(answer), and passes it to the Server:
C:<callUpdateAccept id="A006" callLeg="c1">SDP:B(answer)</callUpdateAccept>
S:<response id="A006"/>
S:<callUpdateRequest callLeg="c1" tag="device2">SDP:Y(offer2)</callUpdateRequest>
The Client uses the received SDP to update the existing media object B associated with the "device2" tag.
If this is not possible, the Client creates a new media object C, sends it the received SDP:Y(offer2) as an "offer" SDP, and retrieves from that media object
the "answer" SDP:C(answer). If it succeeds, it removes the media object B and makes the newly created media object C a "tagged" media object associated with the "device2" tag.
The new media object C is configured to work in the "receiving only" mode.
The Client and passes the retrieved "answer" SDP to the Server:
C:<callUpdateAccept id="A007" callLeg="c1">SDP:C(answer)</callUpdateAccept>
S:<response id="A007"/>
S:<callUpdateSolicited callLeg="c1" tag="device3"/>
The Client creates a new media object D, and associates it with the "device3" tag.
The new media object D is configured to work in the "receiving only" mode.
The Client retrieves the "offer" SDP - SDP:D(offer) - from this media object, and passes it to the Server, using the callUpdate operation.
C:<callUpdate id="A008" callLeg="c1">SDP:D(offer)</callUpdate>
S:<response id="A008"/>
The Server then sends the callUpdated message:
S:<callUpdated callLeg="c1" tag="device3">SDP:Z(answer)</callUpdated>
The Client should pass the received SDP to the media object D as an "answer" SDP.
S:<callConnected callLeg="c1" tag="device1">SDP:X(answer3)</callConnected>
The Client removes all "ringback players", removes all "tagged" media object (C and D), and passes the received SDP:X-3 media descriptor (it's an "answer" SDP) to its "untagged" media object A.
Alternatively, the <callConnected/> message could come without any SDP in it:
S:<callConnected callLeg="c1" tag="device1"/>
The Client removes all "ringback players", removes all "tagged" media object (C and D), and retrieves the SDP:X(answer2) media descriptor, as it was the last one it stored for the tag="device1".
The Client passes the received SDP:X(answer2) media descriptor (it's an "answer" SDP) to its "untagged" media object A.
Alternatively, the <callConnected/> message could come without any SDP in it, and with a different tag:
S:<callConnected callLeg="c1" tag="device2"/>
The Client removes all "ringback players", removes the "untagged" media object A and the tagged media object D, and makes the "tagged" media object C (associated with the "device2" tag) the new "untagged" media object.
Alternatively, the <callConnected/> message could come without any SDP in it, and with a different tag:
S:<callConnected callLeg="c1" tag="device3"/>
The Client removes all "ringback players", removes the "untagged" media object A and the tagged media object C, and makes the "tagged" media object D (associated with the "device3" tag) the new "untagged" media object.
The call has connected, the "untagged" media object (be it A, C, or D) is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A007" callLeg="c1"/>
S:<response id="A007"/>
The user instructs the Client to end this call, the Client ends this call and releases the Server resources associated with this call:
S:<callKill id="A008" callLeg="c1" />
S:<response id="A008"/>
The call ends, the Client removes the "untagged" media object A.
Example Outgoing-11. Outgoing call session without an initial SDP.
The Client does not create any media object before a call.
C:<callStart id="A001" callLeg="c1" peer="user@domain" />
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client already has a "ringback player" for this device (tag), so it does not do any additional media operation.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callConnected callLeg="c1" tag="device1">SDP:X-1</callConnected>
The Client removes the "ringback player", creates an "untagged" media object A, and passes the received SDP:X-1 media descriptor (it's an "offer" SDP) to its "untagged" media object A.
The Client retrieves the "answer" SDP (SDP:A-1) from the media object A, and sends it to the Server:
C:<callUpdateAccept id="A004" callLeg="c1">SDP:A-1</callUpdateAccept>
S:<response id="A004"/>
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
S:<callDisconnected callLeg="c1" />
The call ends, the Client removes the "untagged" media object A.
The Client releases the Server resources associated with this call:
C:<callKill id="A005" callLeg="c1"/>
S:<response id="A005"/>
Example Outgoing-12. Outgoing call session without an initial SDP, multiple callee devices.
The Client does not create any media object before a call.
C:<callStart id="A001" callLeg="c1" peer="user@domain" />
S:<response id="A001"/>
S:<callProvisioned callLeg="c1" tag="device1"/>
The Client creates a "ringback player" so the user knows that the communication peer is being alerted.
C:<callUpdateAccept id="A002" callLeg="c1"/>
S:<response id="A002"/>
S:<callProvisioned callLeg="c1" tag="device2"/>
The Client creates one more "ringback player", so the user knows that the communication peer is being alerted. Both players are playing.
C:<callUpdateAccept id="A003" callLeg="c1"/>
S:<response id="A003"/>
S:<callProvisioned callLeg="c1" tag="device2">SDP:X-1</callProvisioned>
The Client removes the "ringback player" associated with the "device2" tag.
The Client creates a media object A, makeing it a "tagged" object associated with the "device2" tag.
The Client sends the received SDP:X-1 as an "offer" SDP to the media object A.
The Client retrieves an "answer" SDP from the media object A (SDP:A-1) and sends it to the Server.
C:<callUpdateAccept id="A004" callLeg="c1">SDP:A-1</callUpdateAccept>
S:<response id="A004"/>
S:<callConnected callLeg="c1" tag="device1">SDP:Y-1</callConnected>
The Client removes the "ringback player", and the media object A (tagged with the "device2" tag).
The Client creates a media object B, making it the "untagged" media object, and sends the received SDP:Y-1 media descriptor (it's an "offer" SDP) to this "untagged" media object B.
The Client retrieves an "answer" SDP from the media object B (SDP:B-1) and sends it to the Server.
The call has connected, the media object B is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A005" callLeg="c1">SDP:B-1</callUpdateAccept>
S:<response id="A005"/>
Alternatively, the <callConnected/> message could come without any SDP in it and with a different device tag:
S:<callConnected callLeg="c1" tag="device2"/>
The Client removes all "ringback players", and makes the media object A (associated with the "device2" tag) the "untagged" media object.
The call has connected, the media object A is instructed to work in the "send and receive" mode, communications started.
C:<callUpdateAccept id="A005" callLeg="c1"/>
S:<response id="A005"/>
The user instructs the Client to end this call, the Client ends this call and releases the Server resources associated with this call:
S:<callKill id="A006" callLeg="c1" />
S:<response id="A006"/>
The call ends, the Client removes the "untagged" media object A.
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.
- clientID
- optional; the name or ID of the peer device to send this message to.
- type
- optional; the message XMPP-style type - chat, groupchat, etc.
- iqid
- optional; the message identifier string.
Body:
- the Instant Message text (in the UTF-8 encoding) or
- the body XML element, with the Instant Message text as its body, and, optionally, other XML message elements. Or
- the composing XML element (this element should be sent when the user is preparing the message but has not sent it yet). Or
- the paused XML element (this element should be sent when the user has stopped preparing the message before sending it). Or
- the gone XML element (this element should be sent when the user has finished the conversation).
- the subject XML element; its text body is the message subject string.
- 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
- These asynchronous data messages are sent when the Server receives an Instant Message for the client user.
- Attributes:
- peer
- the sender E-mail address.
- peerName
- optional; the sender real name.
- clientID
- optional; the name or ID of the peer device this message was sent from.
- subject
- optional; the message subject string (if the basic format is used).
- iqid
- optional; the message identifier string.
- gmtTime
- optional; the time stamp when the message was received.
Body:
- the composing XML element; this element is sent when the remote peer is preparing (typing) the message but has not sent it yet. Or
- the paused XML element; this element is sent when the remote peer has stopped preparing the message. Or
- the gone XML element; this element is sent when the remote peer has finished the conversation. Or
- the message content in the basic or extended format, as requested with the last signalBind operation:
- simple format:
- the Instant Message text (in the UTF-8 encoding)
- extended format:
- the body XML element with the body containing the Instant Message text, and optional additional XML message elements.
- the subject XML element; its text body is the message subject string.
There is no explicit Instant Message session opening operation. If the client has no open
conversation window for the specified user, it should open a new one.
- errorIM
- These asynchronous data messages are sent when the Server fails to deliver an Instant Message.
- Attributes:
- peer
- the recipient E-mail address.
- errorText
- the error message text.
- signalCode
- the numeric signaling error code.
- sendid
- the id attribute of the sendIM operation that sent the failed Instant Message.
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:
- accountName
- if this optional attribute is specified, the operation reads the Roster items from the specified Account.
The Server sends rosterItem data messages for all currently active Roster "contacts".
- rosterSet
- This operation modifies a Roster "contact".
- Attributes:
- accountName
- if this optional attribute is specified, the operation updates the Roster in the specified Account.
- peer
- the contact E-mail address.
- subscription
- an optional attribute:
- update or no attribute: update the contact information.
- 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.
- subBoth: confirm the contact request to monitor the user's presence information, and send a request to monitor the contact's presence information.
- unsubscribe: stop monitoring the contact's presence 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.
- rosterGroupSet
- This operation manages Roster "contact groups".
- Attributes:
- accountName
- if this optional attribute is specified, the operation updates the Roster in the specified Account.
- group
- the group name.
- mode
- add: create a new contact group with the specified name.
- delete: remove the exiting contact group with the specified name from the Roster.
- rename: rename the exiting contact group.
- newName
- the new contact group name (used only with the mode attribute set to rename).
- 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 XMPP-style user presence status:
- dnd - do not disturb, busy, on-the-phone.
- away - will be right back, in a meeting, out-to-lunch.
- xa - away ("extended away").
Alternatively, you can use a presence XML element instead of the show XML element.
The presence XML element text body specifies the more detailed user presence status:
- offline - "virtually offline".
- online - online.
- on-phone - user is engaged into a real-time conversation.
- in-meeting - user is in a middle of a meeting.
- busy - generic form "cannot chat right now".
- be-back - user will be right back
- out-lunch - user is out for a break/meal.
- away - extended away.
The XML body can also contact an optional status XML element; its text body sets the custom status message.
To remove a previously set custom status message, specify an empty status XML element.
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).
This operation can also be used to send presence information to a specific target (for example, to join an XMPP conference room).
To send presence information rather than to set it, use additional attributes:
- Attributes:
- peer
- the E-mail address of the user or a conference room to send the presence information to.
- clientID
- optional; the name or ID of the peer device to send the presence information to.
The Server sends the following data messages:
- rosterItem
- These data messages are sent synchronously when the Server processes the rosterList request. One message
is sent for each Roster item ("Contact").
These data messages can also be sent sent asynchronously (see below).
- 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
- These asynchronous data messages are sent when a presence state of some Roster "contact" (item) is changed, and Presence notifications are enabled.
- 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:- a presence XML element; its text body specifies the detailed contact presence status (see above);
an optional show XML element; its text body specifies the XMPP-style contact presence status (see above).
These asynchronous data messages are also sent when a remote entity sends its presence information to this particular
XIMSS session (for example, a remote conference room informs this session about users joining and leaving the room). In this case,
the data message contains additional attributes.
- Attributes:
- clientID
- the name or ID of the peer device the presence information was sent from.
A client can send and receive XMPP-style "iq" requests.
- iqSend
- This operation sends an XMPP-style "iq" request to the specified user.
The Server sends a XIMSS response without waiting for the request to be actually delivered and processed.
- Attributes:
- peer
- the E-mail address of the user to send the iq request to.
- clientID
- optional; the name or ID of the peer device to send the iq request to.
- type
- the XMPP iq request type (get, set, result, or error).
- iqid
- this attribute value is used as the id attribute of the XMPP iq request.
Body:
- the XMPP iq request body.
The Server sends the following data messages:
- iqRead
- These asynchronous data messages are sent when the Server receives an XMPP-style iq request for the client user.
- Attributes:
- peer
- the sender E-mail address.
- clientID
- optional; the name or ID of the peer device this message was sent from.
- type
- the XMPP iq request type (get, set, result, or error).
- iqid
- the id attribute of the received XMPP iq request.
Body:
- the XMPP iq request body.
A client can retrieve and update the authenticated user Preferences and Public Info data.
- prefsRead
- This operation retrieves authenticated user Preferences or Public Info data.
- 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 specified value is publicInfo, the Account Public Info settings are retrieved.
If the attribute is not specified, the effective Account Preferences are retrieved.
- Body:
- Zero or more XML name elements. These elements body specify the names of elements to retrieve;
If no name element is specified, all Preference or Public Info elements are retrieved.
The Server returns one prefs data message.
- prefsStore
- This operation updates authenticated user Preferences or Public Info data.
- Attributes:
- type
- this is an optional parameter.
If the specified value is publicInfo, the Account Public Info settings are updated.
If the attribute is not specified, the custom Account Preferences are updated.
- Body:
- XML elements with the names equal to the Preference element names.
An element body contains the new Preference element value. If the value is the default string,
the Public Info or custom Preference value is removed, and the default value becomes the effective element value.
If the value is an array, it should be presented using the array XML presentation.
If the value is a dictionary, it should be presented using the dictionary XML presentation.
If the body contains the UserFromAddr element, the Server uses this element and an optional UserFromName
element to compose the UserFrom element with an E-mail address value
(in the "UserFromName_value" <UserFromAddr_value> format).
- prefsReload
- The Server implements some operations (such as message removal) based on the Preference values read when the session
is started. When some other session modifies the Preferences, the client may use this operation to tell the Server to update these "cached" values.
- Attributes:
- none
The Server sends the following data messages:
- prefs
- This synchronous data message is sent when the Server processes the prefsRead request.
- Attributes:
- type
- an optional attribute, the same as the request attribute.
Body:
- XML elements, with the names equal to Preference or Public Info element names.
An element body contains the 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.
If the prefs data contains the UserFrom string, the Server tries to parse that E-mail address.
If the address is parsed, the UserFromAddr element (with the pure userName@domainName address) and,
optionally, UserFromName element (with the address comment) are added to the data message body.
- prefsModified
- These asynchronous data messages are sent when the Account Preferences are modified (by this session, some other session,
or some other CommuniGate Pro Server component).
It it recommended that the client re-reads the Account Preferences in response to this message.
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 files in a File Storage directory, and the information about these files.
- Attributes:
- directory
- an optional attribute with the File Storage subdirectory name.
If absent and the fileName attribute is also absent, the content of the Account top File Storage directory is returned.
- fileName
- an optional attribute, specified only when the directory attribute is absent. If specified
only the information about this File Storage entry is returned, even if it is a directory.
- gmtTime
- an optional attribute, when specified with any value the time stamps in the result are in GMT instead of the local time.
The Server returns one fileInfo data message for each file or directory in the specified File Storage directory.
- fileDirInfo
- This operation provides information about all Account files or all files in the specified directory.
- Attributes:
- directory
- an optional attribute with the File Storage subdirectory name.
If absent, the information about all Account File Storage files is returned.
The Server returns one fileDirInfo data message.
- fileDirList
- This operation provides a list of all File Storage folders.
The Server returns one fileDirName data message for each 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 new, this operation first checks that the specified file does not exist, and then creates the file and stores the data in it.
If this attribute value is a number, the file must exist, and the operation rewrites the file from the byte position specified with this number.
- type
- If this optional attribute exists and its value is binary, the request body is base64 XML element, its body is base64-decoded before being written to the file.
If this optional attribute exists and its value is object, the request body is an XML representation of a data Object;
the text representation of this Object is written to the file. If this value is used, the position attribute must not be specified.
If this optional attribute exists and its value is xml, the request body must be a single XML element.
Its text representation is written to the file. If this value is used, the position attribute must not be specified.
If this optional attribute exists and its value is vcard, the request body must be a single XML element representing a vCard object.
The vCard text representation is written to the file. If this value is used, the position attribute must not be specified.
Body:
- Either a text with file data, or a base64 XML element, or an XML representation of an object, or an XML element to write to the file.
- fileStore
- This operation stores an uploaded file or a message MIME part as a File Storage file.
- Attributes:
- fileName
- the name of file to be created.
- uploadID
- a string identifying a file in the "uploaded file set".
- folder, UID, partID
- these attributes have the same meaning as for the fileRead operation. They identify a message MIME part to retrieve, decode, and store as a file.
- calendar
- use this attribute instead of the folder attribute to copy a MIME part from an open Calendar, rather than a E-mail folder.
- position
- this optional attribute has the same meaning as for the fileWrite operation.
Either a uploadID attribute should be specified, or the folder is specified, or the calendar attribute should be specified.
No two of these attributes should be specified together in the same fileStore operation.
- 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 maximum size of the file data portion to read. If specified, it should not exceed 3MB. If not specified, the 3MB limit is used.
- type
- If this optional attribute exists and its value is binary, the file data is returned base64-encoded, as the base64 XML element body.
If this optional attribute exists and its value is object, the file data is parsed as a text presentation of an Object, and
the Object XML representation is returned. If this value is used, the position and limit attributes must not be specified,
and the file size should not exceed 3MB.
If this optional attribute exists and its value is xml, the file data is parsed as an XML document, and its XML content
is returned. If this value is used, the position and limit attributes must not be specified,
and the file size should not exceed 3MB.
If this optional attribute exists and its value is vcard, the file data is parsed as vCard document, and its XML representation
is returned. If this value is used, the position and limit attributes must not be specified,
and the file size should not exceed 3MB.
The Server returns a fileData data message.
- fileRename
- This operation renames a file in the File Storage.
- Attributes:
- fileName
- the name of file to rename.
- newName
- the new name for the file.
- fileRemove
- This operation removes a file from the File Storage.
- Attributes:
- fileName
- the name of file to remove.
- fileCopy
- This operation copies file or message contents into a File Storage file.
- Attributes:
- newName
- the name of file to create (copy target). If file with this name already exists, it is removed.
- fileName
- optional: the name of File Storage file to copy.
Body:
- one optional copyMIME element. It specified a message part to decode and copy into the specified file.
The operation must contain either a fileName attribute or one copyMIME body element.
- fileDirCreate
- This operation creates a file directory in the File Storage.
- Attributes:
- fileName
- the name of file directory to create.
- fileDirRename
- This operation renames a file directory in the File Storage.
- Attributes:
- fileName
- the name of file directory to rename.
- newName
- the new name for the file directory.
- fileDirRemove
- This operation removes a file directory from the File Storage.
- Attributes:
- fileName
- the name of file directory to remove. Only empty directories can be removed.
- fileAttrRead
- This operation reads file or directory attributes.
- Attributes:
- fileName
- the name of file or file directory.
Body:
- a set of field XML elements. Each element should have a text body containing the name of an attribute to retrieve.
If no field element is specified, all attributes are retrieved.
The Server returns a fileAttrData data message.
- fileAttrWrite
- This operation modifies file or directory attributes.
- Attributes:
- fileName
- the name of file or file directory.
Body:
- a set of file attribute XML elements.
If a body XML element has the mode attribute with the delete value, then all attributes with the
same name as the name of this body XML element are removed, and the body XML element is not added.
If a body XML element has the mode attribute with the add value, the body XML element is added to the file attributes.
If a body XML element has the mode attribute with any other value or does not have the mode attribute,
then all attributes with the same name as the name of this body XML element are removed, and then the body XML element is added to the file attributes.
Before a body XML element is added to the attribute set, its mode attribute (if any) is removed.
- fileLock
- This operation manages file or directory "locks".
- Attributes:
- fileName
- the name of file or file directory.
- mode
- the requested operation: lock (locking and lock refreshing), unlock (unlocking), testlock (noop, reading the lock list).
- scope
- this attribute is required for the locking operation, it specifies the lock scope: exclusive or shared.
- type
- this attribute is required for the locking operation, it specifies the lock type (read, write, etc.)
- token
- this attribute is required for the lock refreshing and unlocking operations, it specifies the lock token previously received by this client application.
The lock belonging to this owner with the specified token is refreshed or unlocked (removed).
- timeTill
- this attribute is required for the locking and lock refreshing operation, it specifies the lock expiration time
(specified for the selected time zone). If not specified, the default expiration time is used.
- create
- if this attribute is present and set to the yes string, the locking operation does not fail if the
specified file or directory does not exist, but it tries to create it first.
Body:
- for the locking operations, the owner XML element containing the information about the lock owner.
If this operation succeeds, the Server sends a fileLockData data message.
- fileRights
- This operation can be used to get the actual rights on a file.
- Attributes:
- fileName
- the name of file or file directory.
If this operation succeeds, the Server sends a rights data message with the access rights string.
If the file or directory is locked the server sends the additional <lock/> message.
- fileSubList
- This operation makes the Server send a fileSubscription data message for each element in the Account file subscription set.
Note that files in this set may or may not exist.
- fileSubUpdate
- This operation modifies Account file subscription set.
- Body:
- a set of fileSubscription elements.
- Attributes:
- fileName
- a file name in the UTF-8 character set.
- mode
- if this attribute value is add the fileName name is added to the file subscription set (unless the set already contains this name).
otherwise, the fileName name is removed from the file subscription set.
The Server sends the following data messages:
- fileInfo
- This synchronous data 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 (local time, unless the gmtTime attribute was specified in the request).
- timeAttrModified
- an optional attribute with the file attribute set modification date and time (local time, unless the gmtTime attribute was specified in the request).
If the fileName attribute was specified in the fileList request, or if the
name specified in the directory request attribute belongs to a regular file, and not to a file directory,
the directory attribute is not included into the fileInfo message, and the fileName
attribute contains the full name of the target file or directory.
- fileDirInfo
- This synchronous data message is sent when the Server processes the fileDirInfo request.
Note: all attributes are optional, they do not exist, if the system does not maintain the requested values (for example, when the operation is applied to a virtual $DomainPBXApp$ directory).
- Attributes:
- directory
- an optional attribute, the same as the directory attribute in the fileDirInfo request.
- files
- the total number of files in the Account or in the specified subdirectory (and all nested directories).
- size
- the total size of all files (in bytes).
- filesLimit
- the storage file limit setting of the directory owner Account.
- sizeLimit
- the file storage limit setting of the directory owner Account.
- fileDirName
- This synchronous data message is sent when the Server processes the fileDirList request.
- Attributes:
- directory
- the File Storage directory name.
- fileData
- This synchronous data 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 (local time).
- type
- a copy of the request type attribute.
Body:
- Either a text with file data, or the base64 (its body is base64-encoded file data), or an XML representation of the file content Object.
Examples:
C:<fileRead id="A001" fileName="test.txt" />
S:<fileData id="A001" 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 id="A002" 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 id="A003" 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 id="A004" 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" />
- fileAttrData
- This data message is sent when the Server processes the fileAttrRead request.
- Attributes:
- fileName
- the name of file or file directory.
- Body:
- a set of file attribute XML elements.
- fileLockData
- These data messages are sent when the Server processes the fileLock request.
- Attributes:
- fileName
- the file name in the UTF-8 character set.
- token
- the token string for the newly created or refreshed lock.
- expires
- the newly created or refreshed lock expiration time.
- create
- this attribute exists if an empty file has been created as a result of this fileLock request.
- Body:
- a set of fileLockData XML elements for all existing file locks.
Each element contains the expires, scope, type attributes described above.
The element body contains the owner XML element with the lock owner information.
- fileSubscription
- These data messages are sent when the Server processes the fileSubList request.
- Attributes:
- fileName
- the file name in the UTF-8 character set.
A client can manage the Account Automated Rules.
Each rule is presented as a rule XML element.
Rules sets are addressed using the type parameter. The following parameter values are supported:
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 elements:
- 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!</comment>
</rule>
- ruleList
- This operation tells the Server to send one rule data message for each Account Rule of the specified type.
These messages do not have a body.
- Attributes:
- type
- the Rule set.
- ruleRead
- This operation tells the Server to send one rule data message for the specified Rule. This message
body contains XML elements with the Rule condition(s), action(s), and an 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 XML elements as used in the rule message:
zero or more condition elements, zero or more action elements, and zero or one comment element.
- 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 to be modified.
- 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 to be renamed.
- 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 to be removed.
- Attributes:
- type
- the Rule set.
- name
- the existing Rule name.
The Server sends the following data messages:
- rule
- This synchronous data message is sent when the Server processes the ruleList request or the ruleRead request.
See above for the rule message format.
RPOP records are presented using the rpopRecord XML elements:
- Attributes:
- name
- the record name
Body:
- the XML represntation of an RPOP Record dictionary.
A client can manage the Account RPOP records.
- rpopList
- This operation tells the Server to send one rpopRecord data message for each Account RPOP record.
- Attributes:
- none
- This operation updates the Account RPOP record set.
The user should have a right to modify the Account RPOP records.
- Attributes:
- none
Body:
- one or more rpopRecord elements. These elements must have an additional attribute:
- mode
- if this attribute value is delete, the only the name attribute is used.
The specified RPOP record is removed from the Account RPOP record set.
Otherwise, the RPOP record specified using the rpopRecord element body is added to the Account RPOP record set;
if a record with the same name existed in the set, it is removed.
RIMAP records are presented using the rimapRecord XML elements:
- Attributes:
- name
- the record name
Body:
- the XML represntation of an RIMAP Record dictionary.
A client can manage the Account RIMAP records.
- rimapList
- This operation tells the Server to send one rimapRecord data message for each Account RIMAP record.
- Attributes:
- none
- rimapUpdate
- This operation updates the Account RIMAP record set.
The user should have a right to modify the Account RIMAP records.
- Attributes:
- none
Body:
- one or more rimapRecord elements. These elements must have an additional attribute:
- mode
- if this attribute value is delete, the only the name attribute is used.
The specified RIMAP record is removed from the Account RIMAP record set.
Otherwise, the RIMAP record specified using the rimapRecord element body is added to the Account RIMAP record set;
if a record with the same name existed in the set, it is removed.
RSIP records are presented using the rsipRecord XML elements:
- Attributes:
- name
- the record name
Body:
- the XML represntation of an RSIP Record dictionary.
A client can manage the Account RSIP records.
- rsipList
- This operation tells the Server to send one rsipRecord data message for each Account RSIP record.
- Attributes:
- none
- rsipUpdate
- This operation updates the Account RSIP record set.
The user should have a right to modify the Account RSIP records.
- Attributes:
- none
Body:
- one or more rsipRecord elements. These elements must have an additional attribute:
- mode
- if this attribute value is delete, the only the name attribute is used.
The RSIP record with the same name attribute is removed from the Account RSIP record set.
Otherwise, the RSIP record specified using the rsipRecord element body is added to the Account RSIP record set;
if a record with the same name existed in the set, it is removed.
The Server sends the following data messages:
- rpopRecord
- This synchronous data message is sent when the Server processes the rpopList request.
See above for the rpopRecord message format.
The optional timeCompleted attribute indicates the time (in the selected time zone) when the last connection attempt was made.
If the last attempt to poll the RPOP account failed, the record has an additional errorText attribute
containing the failed attempt error code string.
- rimapRecord
- This synchronous data message is sent when the Server processes the rimapList request.
See above for the rimapRecord message format.
The optional timeCompleted attribute indicates the time (in the selected time zone) when the last connection attempt was made.
If the last attempt to poll the RIMAP account failed, the record has an additional errorText attribute
containing the failed attempt error code string.
- rsipRecord
- This synchronous data message is sent when the Server processes the rsipList request.
See above for the rsipRecord message format.
The optional timeCompleted attribute indicates the time (in the selected time zone) when the last connection attempt was made.
If the last attempt to poll the RSIP account failed, the record has an additional errorText attribute
containing the failed attempt error code string.
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 data 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:
- optional text or an XML presentation of a data object to be sent as the Event parameter.
- taskStart
- This operation starts a Real-Time Application Task.
If this operation succeeds, the server sends a taskCreated data message.
- Attributes:
- programName
- the application name.
- entryName
- this optional attribute specified the program entry name; if not specified, the main entry is started.
Body:
- a set of param XML elements. These element text bodies are placed into the Task startParameter array.
- 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 synchronous data 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.
- taskCreated
- This synchronous data message is sent when the Server processes the taskStart request.
- Attributes:
- taskRef
- the internal taskID of the created Task.
- taskEvent
- This asynchronous data 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.
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 specifies 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.
- sortField
- (optional) the comma-separated list of field names to use for records sorting. Note: attributes listed closer to the list end have higher sorting weight.
- sortOrder
- if this optional attribute is specified and it has the desc value, the sorting order is reversed.
- cookie
- this optional attribute specifies the "paging cookie". It should be an empty string to retrieve the first set of records. It should be set to the value of the cookie attribute of the last returned directoryData data message to retrieve the next set of records.
Body (optional):
- a set of field XML elements. Each element should have a text body containing the name of an attribute to retrieve.
If no field element 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 data message for each record found.
- modifyDirectory
- This operation modifies the data in the Directory.
- Attributes:
- name
- the Directory record DN to modify. The $ symbol is replaced with a string with the value of the Directory subtree containing records for the current Account Domain.
- newName
- if this optional attribute is specified then the record DN is renamed to the new name.
Body (optional):
- The XML presentation of the Directory record attributes.
If the Body is empty and there is no newName attribute then the existing record with the given DN is deleted.
Example:
C:<modifyDirectory id="A001" name="mail=user@example.dom,$">
C: <subKey key="mail">user@example.dom</subKey>
C: <subKey key="cn">User J. Smith</subKey>
C: <subKey key="sn"></subKey>
C: <subKey key="objectclass">
C: <subValue>top</subValue>
C: <subValue>person</subValue>
C: <subValue>organizationalPerson</subValue>
C: <subValue>inetOrgPerson</subValue>
C: </subKey>
C:</modifyDirectory>
S:<response id="A001"/>
The Server sends the following data messages:
- directoryData
- This synchronous data message is sent for each Directory record retrieved with the listDirectory command.
- Attributes:
- name
- the record DN.
- cookie
- exists only in the last returned record, only if the command contained this attribute, and if the retrieved records are not the last records. Use the value of this
attribute in the repeated listDirectory command to retrieve more records.
Body:
- The XML presentation of the Record attributes.
A client can manage the Account Datasets (such as the RepliedAddresses Dataset).
To access Datasets in other Accounts, the dataset name should be specified as ~accountName/datasetName or
~accountName@domainName/datasetName
- datasetCreate
- This operation creates an Account dataset.
- Attributes:
- dataset
- the name of the dataset to create.
- datasetRemove
- This operation removes an Account dataset.
- Attributes:
- dataset
- the name of the dataset to remove.
- ifExists
- if this optional attribute exists, and its value is yes, no error is generated when the specified dataset does not exist.
- datasetAddAddress
- This operation adds an address to an Account dataset.
- Attributes:
- dataset
- the name of the dataset to add an E-mail address to.
- realName
- this optional attribute specified the E-mail "real name".
Body:
- The E-mail address string.
- datasetList
- This operation retrieves entries from an Account dataset.
- Attributes:
- dataset
- the dataset name.
- filterField, filter
- these optional attributes specify an entry attribute name and value.
If specified, the operation returns only the entries that have the specified attribute with the specified value.
- mode
- this optional attribute can be specified only if the filterField attribute is specified.
If the mode attribute is absent, or if its value is eq, then an entry is listed if its entry attribute value is equal to the specified value.
If the mode attribute value is beg, then an entry is listed if its entry attribute value starts with the specified value.
If the mode attribute value is end, then an entry is listed if its entry attribute value ends with the specified value.
If the mode attribute value is contains, then an entry is listed if its entry attribute value contains the specified value as its substring.
The Server sends a datasetData data message for each record found.
- datasetListSubsets
- This operation lists all subsets of the specified Account dataset.
- Attributes:
- dataset
- the dataset name. specify an empty string to list the top-level Account datasets.
The Server sends a datasetSubset data message for each dataset found.
- datasetSet
- This operation modifies entries in an Account dataset.
- Attributes:
- dataset
- the name of the dataset to modify.
Body:
- The datasetData element. Its name attribute specifies the name of the dataset entry to modify or create.
If not specified, a random name is selected for a new entry.
The element body should be an XML presentation of the entry attributes to modify.
- datasetDelete
- This operation removes an entry from an Account dataset.
- Attributes:
- dataset
- the name of the dataset to modify.
- name
- the name of the dataset entry to remove.
The Server sends the following data messages:
- datasetData
- This synchronous data message is sent for each dataset entry retrieved with the datasetList request.
- Attributes:
- name
- the dataset entry name.
Body:
- The XML presentation of the dataset entry attributes.
- datasetSubset
- This synchronous data message is sent for each dataset subset retrieved with the datasetListSubsets request.
- Attributes:
- dataset
- the subset entry name.
Body:
- none
A client can manage the Account Balances.
- balance
- This operation performs a Billing operation.
- Attributes:
- accountName
- the target account name (optional). If not specified, the operation is applied to the session owner Account.
- localTime
- if this attribute does not exist or its value is not no, then all timestamp-type values in the operation parameters should
be specified as local times in the Time Zone selected for the current user,
and all timestamp-type values in the operation result are converted into the local time in that Time Zone.
If this attribute value is no, then all timestamp-type values in the operation parameters and result
are GMT times.
Body:
- The XML presentation of a dictionary. The dictionary contains the Billing operation (the op element) and the operation parameters.
If the operation produces any result, the Server sends a balanceData data message.
The Server sends the following data messages:
- balanceData
- This synchronous data message is sent when a balance operation produces a result.
- Attributes:
- accountName
- the target account name (optional, the same as specified with the balance operation request).
Body:
- The XML presentation presentation of the result dictionary.
A client can call External Application Helpers.
- callHelper
- This operation calls an External Application Helper. If the operation produces any result, the Server sends a helperReply data message.
- Attributes:
- name
- the name of the Application Helper to call.
- mode
- the optional string to specify cluster member with the helper application.
Body:
- (optional) the XML presentation of the request sent to the Helper.
The Server sends the following data messages:
- helperReply
- This synchronous data message is sent when a callHelper operation produces a result.
- Attributes:
- name
- the same value as in the callHelper operation.
Body:
- (optional) the XML presentation of the response data received from the Helper.
A client can employ an External Banner System.
- bannerRead
- This operation retrieves banner info. If the operation produces any result, the Server sends a banner data message.
- Attributes:
- type
- the banner type to retrieve (application-specific, such as samowareEmailTop, myClientLeftBanner).
Body:
- (optional) the XML presentation of the External Banner System parameter object.
The Server sends the following data messages:
- banner
- This synchronous data message is sent when a bannerRead operation produces a result.
- Attributes:
- type
- the same value as in the bannerRead operation.
Body:
- (optional) the XML presentation of the External Banner System resulting object.
A client can employ an Synchronous Scripts that are available on the server.
- runScript
- This operation executes a synchronous script. In response the Server sends a scriptResult data message.
- Attributes:
- fileName
- the file name of the synchronous script file (the suffix .scgp is optional).
- name
- (optional) the name of the script entry point.
Body:
- (optional) the XML presentation of the parameter object.
The Server sends the following data messages:
- scriptResult
- This synchronous data message is sent when a runScript operation produces a result.
- Attributes:
Body:
- (optional) the XML presentation of the synchronous script resulting object.
Data elements are presented in the XML format using the following conventions.
This XML element represents an E-mail message or its message/rfc822 MIME subpart.
- Body:
- a set of XML elements containing E-mail message header fields, such as From, Date, etc.,
and not including MIME content-related fields (such as Content-Type),
and (optionally) a MIME element with the message body.
The type of each XML element is the field name:
- <Subject>Hello, world!</Subject>
Field categories:
- Addresses: From, To, Cc, Bcc, Return-Path,
Sender, Reply-To, Disposition-Notification-To,
Recent-From, Recent-To,
Return-Receipt-To, Errors-To
- The element body is the E-mail address, in the userName@domainName format, or a more generic
userName[%domainA[%domainB]]@domainName format.
These elements can contain the realName attribute - a MIME-decoded address name-part or comment.
If a field contains several addresses, then several XML elements are created, so each element
contains exactly one address.
- Timestamps: Date, Resent-Date
- These elements contain:
the timeShift attribute - the time difference (in seconds)
between the local time specified in the field and the corresponding GMT time
the localTime attribute - the field time value (in the iCalendar format) in the Time Zone selected for the current user.
The element body is the field global (GMT) time value in the iCalendar format.
- Pty
- These elements body are High or Low strings. These values are converted to and from numeric X-Priority header field values.
- Phones: X-Telnum
- The element body is a phone number.
These elements can contain the type attribute (WORK, CELL, HOME, AGENT, etc.) specifying the type of the phone number/address.
If a field contains several phone numbers, then several XML elements are created, so each element
contains exactly one phone number.
- Unstructured
- All fields not listed in previous categories belong to this category.
The element body contains the MIME-decoded field value.
Example:
From: "Mr. Sender." <user1@example.com>
To: user2@example.com (My Friend),
=?iso-8859-1?Q?=4Eot=20A=20Friend?= <user2@example.com>
Date: Mon, 10 Apr 2006 13:15:48 -0700
Subject: It's 1:15PM now, the meeting has started!
<EMail>
<From realName="Mr. Sender.">user1@example.com</From>
<To realName="My Friend">user2@example.com</To>
<To realName="Not A Friend">user3@example.com</To>
<Bcc>user1@example.com</Bcc>
<Date timeShift="-25200" localTime="20060410T151548">20060410T201548Z</Date>
<Subject>It's 1:15PM now, the meeting has started!</Subject>
</EMail>
This XML element represents a message body or its part (referred to as "part" in the rest of this section).
- Attributes:
- partID
- this string provides the MIME part location within the message. It can be used to retrieve this message part.
- estimatedSize
- the estimated size (in bytes) of the part data, after the part data is decoded.
- type
- the part Content-Type type, without the subtype information.
- subtype
- the part Content-Type subtype, if present.
- charset
- the part character set (assume UTF-8 if the attribute is absent).
- contentID
- the Content-ID string (without the enclosing angle brackets).
- disposition
- the Content-Disposition string (without parameters).
- description
- the Content-Description string.
- location
- the Content-Location string.
- class
- the Content-Class string, after removing the urn: and content-classes: prefixes.
- Type-name
- any Content-Type field name parameter with its value, excluding the boundary, charset, and format parameters.
- Disposition-name
- any Content-Disposition field name parameter with its value.
Body:
- The element body is optional. When present, it contains the part body data.
If the Server fails to read the element body part data, the readError attribute is added to the element. The attribute value contains the reading error code.
If the Server fails to parse the element body part data, the parserError attribute is added to the element. The attribute value contains the parsing error code.
The element format depends on the part Content-Type (the "*" symbol below means any Content-Type or subtype):
- multipart/*
- Zero or more MIME XML elements containing message subparts.
- message/rfc822
- A EMail XML element for the enclosed message.
- text/rfc822-headers
- An EMail XML element (not containing any MIME body element).
- text/directory, text/x-vcard
- Zero or more vCard XML elements.
- text/x-vgroup
- One vCardGroup XML element.
- text/calendar
- an iCalendar XML element.
- message/disposition-notification, message/delivery-status
- a MIMEReport XML element.
- */xml, */*+xml
- The XML data of the body element.
- text/*
- The decoded message text, with all EOL symbols replaced with the Line Feed (0x0A) symbol.
Note: When a message is being retrieved with the folderRead operation, a MIME element body is included only if:
- its Content-Type is one of the supported types listed above
- its Content-Disposition is not attachment
- its size plus the size of the parts already included into the response XML does not exceed the totalSizeLimit operation attribute.
Example:
From: <user1@example.com>
To: user2@example.com
MIME-Version: 1.0
Content-Type: multipart/alternative;boundary="abcd"
Content-Description: Test Message
--abcd
Content-Type: text/plain; charset="iso-8859-1";
format=flowed; paramX="valueX"
Content-Transfer-Encoding: quoted-printable
=46rom where I stay, I can see & hear a lot!
--abcd
Content-Type: text/html; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<html><body bgcolor=3D"yellow">
<I>From where I stay</I>, I can see & hear a lot!
</body></html>
--abcd--
<EMail>
<From>user1@example.com</From>
<To>user2@example.com</To>
<MIME Type="multipart" subtype="alternative" Description="Test Message">
<MIME type="text" subtype="plain" charset="iso-8859-1" type-paramX="valueX">
From where I stay, I can see & hear a lot!
</MIME>
<MIME type="text" subtype="html" charset="iso-8859-1" type-paramX="valueX">
<html><body bgcolor="yellow">
<I>From where I stay</I>, I can see &amp; hear a lot!
</body></html>
</MIME>
</MIME>
</EMail>
This XML element represents a message report, such as Disposition Notification or a Delivery report.
- Attributes:
- none
Body:
- a set of XML elements containing report header fields, such as Reporting-MTA, Final-Recipient, etc.
and (optionally) MIMEReport elements for the report body.
Example:
Subject: Delivery report: TEST - disposition and delivery
From: <MAILER-DAEMON@remote.example.com>
To: <sender@local.example.com>
Date: Wed, 02 May 2007 00:33:13 -0700
Message-ID: <receipt-39457791@remote.example.com>
X-MAPI-Message-Class: REPORT.IPM.Note.DR
MIME-Version: 1.0
Content-Type: multipart/report; report-type="delivery-status"; boundary="_===39457791====remote.example.com===_"
--_===39457791====remote.example.com===_
Content-Type: text/plain; charset="utf-8"
Message delivered to '<recepient@remote.example.com>'
LOCAL module(account recepient) reports:
Delivered to the user mailbox
--_===39457791====remote.example.com===_
Content-Type: message/delivery-status
Reporting-MTA: dns; remote.example.com
Original-Recipient: rfc822;<recepient@remote.example.com>
Final-Recipient: LOCAL;<recepient>
Action: delivered
Status: 2.0.0
--_===39457791====remote.example.com===_
Content-Type: text/rfc822-headers
From: "Sender Name" <sender@local.example.com>
Subject: TEST - disposition and delivery
To: recepient@remote.example.com
X-Mailer: CommuniGate Pro WebUser v5.1.9
Date: Wed, 02 May 2007 00:35:51 -0700
Message-ID: <web-3990004@local.example.com>
MIME-Version: 1.0
Disposition-Notification-To: <sender@local.example.com>
Content-Type: text/plain;charset="utf-8";format="flowed"
Content-Transfer-Encoding: 8bit
--_===39457791====remote.example.com===_--
<EMail>
<Subject>Delivery report: TEST - disposition and delivery</Subject>
<From>MAILER-DAEMON@communigate.ru</From>
<To>sender@local.example.com</To>
<Date localTime="20070502T003313" timeShift="-25200">20070502T073313Z</Date>
<Message-ID><receipt-39457791@remote.example.com></Message-ID>
<X-MAPI-Message-Class>REPORT.IPM.Note.DR</X-MAPI-Message-Class>
<MIME estimatedSize="1433" subtype="report" type="multipart" Type-report-type="delivery-status">
<MIME charset="utf-8" estimatedSize="120" partID="01" subtype="plain" type="text">Message delivered to '<recepient@remote.example.com>'
LOCAL module(account recepient) reports:
Delivered to the user mailbox
</MIME>
<MIME estimatedSize="158" partID="02" subtype="delivery-status" type="message">
<MIMEReport>
<Reporting-MTA>dns; remote.example.com</Reporting-MTA>
<MIMEReport>
<Original-Recipient>rfc822;<recepient@remote.example.com></Original-Recipient>
<Final-Recipient>LOCAL;<recepient></Final-Recipient>
<Action>delivered</Action>
<Status>2.0.0</Status>
</MIMEReport>
</MIMEReport>
</MIME>
<MIME estimatedSize="787" partID="03" subtype="rfc822-headers" type="text">
<EMail>
<From realName="Sender Name">sender@local.example.com</From>
<Subject>TEST - disposition and delivery</Subject>
<To>recepient@remote.example.com</To>
<X-Mailer>CommuniGate Pro WebUser v5.1.9</X-Mailer>
<Date localTime="20070502T003551" timeShift="-25200">20070502T073551Z</Date>
<Message-ID><web-3990004@local.example.com></Message-ID>
<Disposition-Notification-To>sender@local.example.com</Disposition-Notification-To>
</EMail>
</MIME>
</MIME>
</EMail>
Some clients may be unable to implement all operations via the XIMSS protocol.
When a XIMSS session is created, its ID is reported back to the client using the session
data message. The Server provides access to that session via the HTTP protocol.
The following URL can be used to retrieve any part of a message visible in any currently opened Folder:
- /Session/sessionID/MIME/folder/UID-partID-suffix[/filename]
where
- sessionID
- the current XIMSS session ID, sent with the session data message
- folder
- the target Folder name or the target Calendar name
- UID
- the target message UID in the target Folder or Calendar
- partID
- the id of the requested message MIME part. This is the string reported in the MIME
XML element when the message was retrieved using the folderRead operation. If the entire
message is to be retrieved, the partID string and the following - symbol should be
omitted.
- suffix
- the retrieval mode:
- P.txt - the entire undecoded part (including the headers and the body) is retrieved.
- H.txt - the part headers are retrieved.
- B.extension - the decoded part body is retrieved. You can use any appropriate file name extension.
The HTTP response gets the Content-Type of the retrieved MIME part.
- R/cid - the cid string should be URI-encoded. Its decoded value specifies a MIME-part Content-ID.
The Server searches all MIME parts "related" to the current one, and retrieves the body of the part with the matching Content-ID.
This feature is used to convert cid:-type URLs in HTML-formatted messages.
- filename
- an optional file name. It is ignored by the Server, but it can help the user browser to store the file under the proper name.
Examples:
C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-01-B.gif HTTP/1.1
C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-02-01-B.gif/Logo.gif HTTP/1.1
It is possible to retrieve only a portion of a message part,using the HTTP Range header field.
Alternatively (when HTTP request fields cannot be specified), the URL parameters can be used:
- OffsetFrom
- part data byte-position to start with (0 means to start from the beginning).
- OffsetTill
- (optional) part data byte-position following the last byte to send.
Example:
C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-01-B.gif?OffsetFrom=100&OffsetTill=200 HTTP/1.1
This request retrieves 100 bytes (bytes 100..199 inclusive) from the GIF file encoded in the specified MIME part.
The following URL can be used to retrieve the Profile vCard or any of its properties:
- /Session/sessionID/PROFILE/[propertyname[/index][/filename]]
where
- sessionID
- the current XIMSS session ID, sent with the session data message
- propertyname
- the vCard property name, such as PHOTO. If the property name is not specified, the entire vCard is retrieved.
- index
- if the vCard contains several values for the specified property name, the index of the value to retrieve (zero-based).
If not specified, the index value of 0 is assumed.
- filename
- any properly encoded URL-string.
Example:
C:GET /Session/1-2xklkdld8-djdkjk/PROFILE/PHOTO/0/avatar HTTP/1.1
This request retrieves the first value of the "PHOTO" property of the Profile vCard.
The following URL can be used to upload a file to the session "uploaded file set".
- /Session/sessionID/UPLOAD/uploadID
where
- sessionID
- the current XIMSS session ID, sent with the session data message.
- uploadID
- a string identifying this file in the "uploaded file set".
The HTTP request should be:
- a POST request, with the multipart/form-data content, and the file (raw binary data) should be sent as the fileData form element, or
- a PUT request, and the file (raw binary data) should be sent as the request body.
When the file is uploaded and added to the "uploaded file set", the Server returns the 200 response code. If uploading
failed, the Server returns the 500 response code.
The uploaded file is stored together with its Content-Type value.
If the "uploaded file set" already contains a file with the specified uploadID value, the old file is removed.
The following URL can be used to download a file from the session Account File Storage.
- /Session/sessionID/DOWNLOAD/fileName
where
- sessionID
- the current XIMSS session ID, sent with the session data message.
- fileName
- the file name in the session Account File Storage.
Note: to download a file from the "uploaded file set", specify the fileName
as $UPLOAD$/uploadId, where uploadId is the "uploaded file set" file identifier.
The following URL can be used to export data from a folder or a calendar:
- /Session/sessionID/Export/folderName/fileName[?oldStyle=1]
If the folderName is a name of an open Calendar object, the request retrieves
an iCalendar text that includes all object VEVENT and VTODO items, and all VTIMEZONE objects referenced.
If the folderName is a name of an open folder object, the request retrieves a vCard text that includes
all VCard items stored in that folder. If the oldStyle parameter is specified, the vCard items are exported using the
vCard 2.1 format and the UTF-8 character set, otherwise the vCard 3.0 format and the Unicode character set is used.
The following URL can be used to export the Account Private Key and Certificate as a PKCS12 ("PFX") file:
- /Session/sessionID/CertAndKey.pfx?PFXPassword=password[&PFXPassword1=password1]
If the PFXPassword1 is specified, its value must be the same as the PFXPassword value.
The session must have its S/MIME unlocked.
The Account Private Key and Certificate are placed into PKCS12-formated data encrypted using the PFXPassword value.
The following URL can be used to close the session without doing any "logout cleanup" procedures:
- /Session/sessionID/KILL
|