Seagull - XCAP protocol

Home	Project	Documentation	Download	Screenshots/videos

Section

Seagull - XCAP protocol

XCAP protocol details
Getting started with XCAP
- First try
- First try explained
Miscellaneous considerations

XCAP protocol details

The implementation of XCAP in Seagull conforms to draft-ietf-simple-xcap-11.txt (see also http://www.jdrosen.net/simple_acap.html). XCAP being a text payload (transported by HTTP), Seagull does not really describe the XCAP protocol in its dictionary. Instead, XCAP messages and parameters are described using "CDATA" XML tags which gives a great flexibility to add messages and parameters in the scenarios.

Getting started with XCAP

First try

So that you can get familiar with Seagull in the context of XCAP, here is an example that will launch one XCAP server (a server expects a message as the first scenario command) and one XCAP client (a client sends a message as the first scenario command). The client and the server will talk to each other using the loopback interface (127.0.0.1). The scenario is the following:

          PUT     
     |------------>|
     | 201 Created |
     |<------------|
     |   DELETE    |
     |------------>|
     |   200 OK    |
     |<------------|

Here is the XML source of the client scenario.

First try explained

Here is the commented version of the XCAP client:

Scenario

Comments

<?xml version="1.0" encoding="ISO-8859-1" ?>
<scenario>

<traffic>
  <send channel="xcap-channel">
    <action>
      <open args="mode=client;dest=127.0.0.1:8090"></open>
    </action>
    <message>
      <!-- header -->
      <![CDATA[PUT /xcap/test-auid1/users/sip:user@hp.com/doc.xml HTTP/1.1
        Content-type: application/note+xml;charset=UTF-8
        X-XCAP-Asserted-Identity: "sip:user@hp.com"
        User-Agent: Seagull-gull.sourceforge.net
        Host: clever5:8090
        Accept: text/html, image/gif, *; q=.2, */*; q=.2
        Connection: keep-alive] ]>
      <!-- Body -->
      <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
      <note xmlns:dog="the:namespace:for:dog">
        <dog:to>Jani</dog:to>
        <from>Tove</from>
        <heading>Re: Reminder</heading>
        <body>I will not forget you this week end!</body>
      </note>] ]>
    </message>
  </send>

  <receive channel="xcap-channel">
    <message>
    <!-- header -->
    <![CDATA[HTTP/1.1 201 Created
      Server: Apache-Coyote/1.1
      Pragma: No-cache
      Cache-Control: no-cache
      Expires: Wed, 31 Dec 1969 18:00:00 CST
      X-Powered-By: Servlet 2.4; JBoss-4.0.4.GA
      ETag: 1
      Content-Length: 0
      Date: Mon, 07 Aug 2006 21:14:46 GMT] ]>
    </message>
  </receive>

  <send channel="xcap-channel">
    <message>
      <!-- header -->
      <![CDATA[DELETE /xcap/test-auid1/users/sip:user@hp.com/doc.xml HTTP/1.1
        X-XCAP-Asserted-Identity: "sip:user@hp.com"
        User-Agent: Seagull-gull.sourceforge.net
        Host: clever5:8090
        Accept: text/html, image/gif, *; q=.2, */*; q=.2
        Connection: keep-alive
        Content-type: application/x-www-form-urlencoded
      ] ]>
    </message>
  </send>
  
  <receive channel="xcap-channel">
    <message>
    <!-- header -->
    <![CDATA[HTTP/1.1 200 OK
      Server: Apache-Coyote/1.1
      Pragma: No-cache
      Cache-Control: no-cache
      Expires: Wed, 31 Dec 1969 18:00:00 CST
      X-Powered-By: Servlet 2.4; JBoss-4.0.4.GA
      ETag: 1
      Content-Length: 0
      Date: Mon, 07 Aug 2006 21:14:46 GMT] ]>
    </message>
    <action>
      <close></close>
    </action>
  </receive>

  </traffic>
</scenario>

XML header




An XCAP call is identified by the channel on which protocol exchanges occur.
This action is to open a TCP socket for each new XCAP call. This socket is
closed at the end of the call (see below).

An XCAP message as an Header (mandatory) and a body (optional).
Here, Seagull just sends the header as indicated in the CDATA







When the message is sent, the body is separated by the header with
an empty line (\r\n).
An XCAP body must be correctly formated: the top most xml tag (<note>
in this case must be properly closed </note). 
Seagull parses the body to find out where the message ends (this is
needed because content-length header is optional).




The 201 Created message is received on the channel that was opened 
at the beginning of the call.








































The transport channel (TCP socket in this case) is closed at the
end of the call with the <close/ action.

Miscellaneous considerations

Generating the XCAP traffic is quite easy with Seagull. Users must be aware that some limitations apply with respect to HTTP, on which XCAP relies:

HTTP Digest authentication is not yet supported (but planned)
HTTP chunked mode might work but has not been tested
HTTPs is not supported