XIMSS Module

Use the WebAdmin Interface to configure the XIMSS module. Open the Access page in the Settings realm:

Processing
Log Level:	Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info	Channels:	off135102550100250500100030001000030000other	Listener

Use the Log setting to specify the type of information the XIMSS module should put in the Server Log. Usually you should use the Major (message transfer reports) or Problems (message transfer and non-fatal errors) levels. But when you experience problems with the XIMSS module, you may want to set the Log Level setting to Low-Level or All Info: in this case protocol-level or link-level details will be recorded in the System Log as well. When the problem is solved, set the Log Level setting to its regular value, otherwise your System Log files will grow in size very quickly.

The XIMSS module records in the System Log are marked with the XIMSSI tag.

When you specify a non-zero value for the Maximum Number of Channels setting, the XIMSS module creates a Listener. The module starts to accept all XIMSS connections that clients establish in order to communicate with your Server. The setting is used to limit the number of simultaneous connections the XIMSS module can accept. If there are too many incoming connections open, the module will reject new connections, and the client should retry later.

By default, the XIMSS module Listener accepts clear text connections on the TCP port 11024. Follow the Listener link to tune the XIMSS Listener.

XIMSS connections can be made to TCP ports served with other CommuniGate Pro modules. If the first symbol received on a connection made to the HTTP module is the < symbol, the HTTP module passes the connection to the XIMSS module.

When a connection is passed:

• the logical job of the passing module completes.
• the logical job of the XIMSS module is created, in the same way when an XIMSS connection is received on a port served with the XIMSS module.
• the XIMSS module restrictions for the total number of XIMSS channels and for the number of channels opened from the same IP address are applied.

When all users initiate XIMSS connections via other Module ports, you can disable the XIMSS Listener by setting all its ports to zero.

When a Flash client connects to an XMLSocket server (such as the CommuniGate Pro XIMSS module), it can send a special policy-file-request request. The XIMSS module replies with an XML document allowing the client to access any port on the Server.

When a user is authenticated, the XIMSS module creates a XIMSS session. The current XIMSS module TCP connection can be used to communicate with that session.

A XIMSS session can be created without the XIMSS module, using special requests sent to the HTTP User module. See the XIMSS Protocol section for more details.

The XIMSS session records in the System Log are marked with the XIMSS tag.

A client application can access the XIMSS interface via HTTP connections.

A client application should start by sending an HTTP Login request to create a new XIMSS session.

When a XIMSS session is created, the client application can send XIMSS protocol requests to it and receive XIMSS protocol responses from the session using HTTP requests.

Client applications can use GET and POST HTTP requests.
If a request contains a body, it is assumed to be an XML text, unrelated to the actual value of the Content-Type header field. The XML text must be a <XIMSS/> element.
If a request produces a non-empty response body, the body is always an XML text containing one <XIMSS/> element, and the response Content-Type header field is text/xml.

Open the HTTP User Module settings, and find the Sub-Protocols panel:

Sub-Protocols
	Access
XIMSS:	nobodyclientseverybody

The Access setting specifies who can create XIMSS sessions using HTTP Binding.

HTTP Login

To start a XIMSS session, a client application should send an HTTP request to the CommuniGate Pro HTTPU module using the following URLs:

http://domainName[:port]/ximsslogin/
or
https://domainName[:port]/ximsslogin/

If the request contains the userName parameter, the Server tries to authenticate the specified user (Account):

• If the password parameter is present, the regular clear-text method is used.
• If the nonce parameter is present, the CRAM-MD5 method is used. The "nonce" parameter value should be a value received as part of a features response (see below), it should be a valid "authentication nonce". The request must contain the authData parameter containing the base64-encoded CRAM-MD5 "challenge response".
• If the sessionid parameter is present, the SessionID method is used.
• If the errorAsXML parameter is present and the login operation fails, the error condition is returned not as an HTTP result code with an HTML error page, but as an <response/> element with errorNum and errorText attributes, enclosed into a <XIMSS/> element.
• If the version parameter is present, its value specifies the protocol version the client implements (see the Login operation parameters).

If the userName parameter is absent, the Server tries to authenticate the request using the TLS Client Certificate (if specified), or using the HTTP authentication methods.
This functionality is the same as the WebUser Interface Automatic Login and Single Sign-on functionality, but the /ximsslogin/ URL is used.

A request to the /ximsslogin/ URL can contain a text/xml body. In this case, no login operation is performed.
The XML body should contain one <XIMSS> element containing zero, one, or several XIMSS Pre-Login operations. The Server sends an HTTP response with XML data. The response is a <XIMSS> element containing the requested operations result.

Example:

If the user has been successfully authenticated, and the XIMSS session has been created, the HTTP Login response contains the XIMSS session message with the session ID string. Note that the session message does not contain the id attribute.

Example:

Alternative URLs can be used to start a XIMSS session using the TLS Client Certificate, or using the HTTP authentication methods:

http://domainName[:port]/auth/ximsslogin/
or
https://domainName[:port]/auth/ximsslogin/

This method is useful if an application first retrieves an HTML page or some other document using the /auth/ realm, forcing the browser to ask the user for credentials, and then the application creates a XIMSS session for the same user, as the browser will resend the same credentials when sending a request to the /auth/ximsslogin/ URL.

HTTP Synchronous Communications

A client should send requests to a created XIMSS session use the following Session URL:

http://domainName[:port]/Session/sessionID/sync
or
https://domainName[:port]/Session/sessionID/sync

where sessionID is the session message urlID attribute.

The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests.

The Server returns one <XIMSS /> element in the HTTP response body. This element contains the XIMSS protocol response messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests.

Example:

If a XIMSS client works in an unreliable environment, where it may have to resend HTTP requests, then each non-empty HTTP request should contain a reqSeq parameter. This parameter value should be increased by 1 for each new HTTP request sent.
If the Server receives an HTTP request with the same reqSeq parameter as the previously received and processed HTTP request, then the Server resends the last response (one it has sent to the previous HTTP request wit the same reqSeq).
If the Server receives an HTTP request with the reqSeq parameter not equal to the reqSeq parameter of the previously received request and not equal to the reqSeq parameter of the previously received request increased by 1, then the Server returns an error.

A client application can use an "empty request" (an HTTP request without a body) to read asynchronous XIMSS data messages.

When such an empty request is received, the Server checks if there is any pending asynchronous data messages for the specified session. If there is no pending asynchronous data messages, the request is held until either:

• an asynchronous data message is generated for the session; or
• the waiting time is over; or
• a new "empty request" is received; or
• the session is closed.

An empty request can specify the waiting time as the maxWait parameter (number of seconds).

If no data messages were retrieved, the Server sends a response containing an empty <XIMSS/> element, without any attributes.

If some data messages were retrieved, the Server sends a response (an "asynchronous response") containing one <XIMSS/> element, with the respSeq attribute. This attribute contains the sequence number for this <XIMSS/> response element.

For each session, the Server keeps the last "asynchronous response" composed.

Each empty request should contain a ackSeq parameter. It should contain the respSeq value of the last received asynchronous response.
If the client has not received any asynchronous response yet, this parameter value must be 0.

When the Server receives an empty request with the ackSeq equal to the respSeq value of the kept last composed asynchronous response, it considers that response as "acknowledged", and removes it.

When the Server receives an empty request with the ackSeq equal to the respSeq value of the last composed asynchronous response minus one (respSeq-1), and it still keeps this composed response, the Server resends that response to the client. As a result, if the client encounters any communication error while doing an "empty request" HTTP transaction, it can resend that empty request.

An empty request without an ackSeq parameter acknowledges all "asynchronous responses" composed and kept.

When a server returns an empty <XIMSS/> element, the next empty request can contain either no ackSeq parameter, or the same ackSeq parameter as the previous empty request. Because of this subsequent empty requests may use the same request URL and the same parameters, and the client platform may return the previous cached <XIMSS/> element result immediately, without sending the request to the server.
To avoid this problem, include the reqSeq parameter into each empty request, increasing its value after a successful transaction.

Example:

HTTP Asynchronous Communications

A client can send requests to a created XIMSS session so that all responses (including the response messages and synchronous data messages) are returned only in response to the "empty requests".

http://domainName[:port]/Session/sessionID/async
or
https://domainName[:port]/Session/sessionID/async

where sessionID is the session message urlID attribute.

The HTTP request body should contain one <XIMSS /> element, with zero, one, or more XIMSS protocol requests.

All generated response messages (one for each XIMSS request sent, in the same order), and all synchronous data messages generated with the submitted XIMSS requests are re-submitted to the XIMSS session as asynchronous messages. The Server returns an empty HTTP response.

Example (single connection, polling):

Example (2 connections, waiting):

C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=0&reqSeq=0 HTTP/1.1   Host: myserver.com   Content-Length: 0 ...waiting... S:HTTP/1.1 200 OK   Content-Length: nnn   Connection: keep-alive   Content-Type: text/xml;charset=utf-8   Server: CommuniGatePro/5.3   <XIMSS respSeq="1">     <response id="i1"/>     <currentTime id="i2" gmtTime="20070502T083313"       localTime="20070502T003313"/>     <response id="i2"/>   </XIMSS> C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=1&reqSeq=1 HTTP/1.1   Host: myserver.com   Content-Length: 0 ...waiting...

C:POST /Session/562-kAI2lxNBR4ApmHg4wiW9/async HTTP/1.1   Host: myserver.com   Content-Length: nnn   <XIMSS><noop id="i1" /><readTime id="i2" /></XIMSS> S:HTTP/1.1 200 OK   Content-Length: 0   Connection: keep-alive   Content-Type: text/xml;charset=utf-8   Server: CommuniGatePro/5.3

You can monitor the XIMSS Module activity using the WebAdmin Interface.

Click the Access link in the Monitors realm to open the Access Monitoring page:

3 of 3 selected

ID	IP Address	Account	Connected	Status	Running
9786	[216.200.213.116]	user1@domain2.dom	3min	listing messages	2sec
9794	[216.200.213.115]	user2@domain1.dom	34sec	reading request
9803	[216.200.213.115]		2sec	authenticating

ID

This field contains the XIMSS numeric session ID. In the CommuniGate Pro Log, this session records are marked with the XIMSS-nnnnn flag, where nnnnn is the session ID.

IP Address

This field contains the IP address the client has connected from.

Account

This field contains the name of the client Account (after successful authentication).

Connected

This field contains the connection time (time since the client opened this TCP/IP session).

Status

This field contains either the name of the operation in progress or, if there is not pending operation, the current session status (Authenticating, Selected, etc.).

Running

If there is an XIMSS operation in progress, this field contains the time since operation started.

XIMSS activity can be monitored with the CommuniGate Pro Statistic Elements.