Version 5.4
Access |
|---|
| |||||||||||
|
|
Version 5.4 |
||||||||||||||||||||||||||||||||||
|
|
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:When all users initiate XIMSS connections via other Module ports, you can disable the XIMSS Listener by settings 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.
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 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.
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.
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: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.
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 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 getSeq parameter into each empty request, increasing its value after a successful transaction.
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):|
C:GET /Session/562-kAI2lxNBR4ApmHg4wiW9/get?ackSeq=0&getSeq=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&getSeq=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:XIMSS activity can be monitored with the CommuniGate Pro Statistic Elements.