xcapclient-1.4.0 Documentation

Description

XCAP (RFC 4825) is a protocol on top of HTTP allowing a client (usually built within a SIP user agent) to manipulate the content of XML documents stored in a server. These documents represent per user buddy list, presence authorization policy, media content (i.e. user avatar) and other kind of features.

Ruby XCAPClient library implements the XCAP protocol in client side, allowing the application to get, store, modify and delete XML documents (totally or partially) in the server.

Features

The library implements the following features:

Ruby XCAPClient works in Ruby 1.8 and 1.9.

Support

The XCAPClient mailing list is available here:

The bug tracker is available here:

API

A developer interested in this library should study the following documents:

Synopsis

  require 'rubygems'
  require 'xcapclient'

Create a client

  xcap_conf = {
    :xcap_root => "https://xcap.myserver.org",
    :user => "sip:me@mydomain.org",
    :password => "xxxxxx",
    :ssl_verify_cert => true
  }

  xcap_apps = {
    "resource-lists" => {
      :xmlns       => "urn:ietf:params:xml:ns:resource-lists",
      :mime_type   => "application/resource-lists+xml"
    }
  }

  xcapclient = Client.new(xcap_conf, xcap_apps)

Create a XCAPClient::Document with name “index” for “resource-lists” application.

  xcapclient.application("resource-lists").add_document("index")

It’s the same as doing:

  xcapclient.application("resource-lists").add_document("index", scope=nil, xui=nil)

As scope is nil it’s set to :users. As xui is nil it’s a document owned by our user.

Fetch the “index” document (auid “resource-lists”) from the server

This works because the document we are interested in is the first one, so it’s fetched:

  xcapclient.get("resource-lists")

It’s the same as doing:

  xcapclient.get("resource-lists", "index")

We can also use a XCAPClient::Document object rather than a String (required when fetching 3rd party documents):

  doc = xcapclient.application("resource-lists").document("index")
  xcapclient.get("resource-lists", doc)

Fetch again the “resource-lists” document (now including the stored ETag)

By default, the methods accesing the XCAP server include the ETag if it’s available. Since it was already got on the previous request, it’s included in the new request. If the document has not been modified in the server by other client, the server replies “304 Not Modified” and the method generates a XCAPClient::XCAPClientError::HTTPDocumentNotModified exception.

  begin
    xcapclient.get("resource-lists")
  rescue XCAPClientError::HTTPDocumentNotModified
    puts "The document has not been modified in the server."
  end

Replace the local document and upload it to the server

  xcapclient.application("resource-lists").document.reset
  xcapclient.application("resource-lists").document.plain = "<?xml version='1.0' encoding='UTF-8'?> ..."

  xcapclient.put("resource-lists")

or:

  xcapclient.put("resource-lists", "index")

or:

  doc = xcapclient.application("resource-lists").document("index")
  xcapclient.put("resource-lists", doc)

Delete the document in the server

  xcapclient.delete("resource-lists")

Create a new document and upload it (a new “friends” document for “resource-lists” application)

  friends_doc = xcapclient.application("resource-lists").add_document("friends")
  friends_doc.plain = "<?xml version='1.0' encoding='UTF-8'?> ..."

  xcapclient.put("resource-lists", friends_doc)

or:

  xcapclient.put("resource-lists", "friends")

Fetch a node (with “uri” = “sip:alice@example.org“)

  xcapclient.get_node("resource-lists", "index",
    'rl:resource-lists/rl:list[@name="mybuddies"]/rl:entry[@uri="sip:alice@example.org"]',
    {"rl" => "urn:ietf:params:xml:ns:resource-lists"})

or using the application default namespace:

  xcapclient.get_node("resource-lists", "index",
    'resource-lists/list[@name="mybuddies"]/entry[@uri="sip:alice@example.org"]')

Add a new node (a new buddy)

  xcapclient.put_node("resource-lists", "index",
    'resource-lists/list[@name="mybuddies"]/entry[@uri="sip:bob@example.org"]',
    '<entry uri="sip:bob@example.org"/>'

Fetch a node attribute (the “uri” attribute of “sip:alice@example.org“)

  xcapclient.get_attribute("resource-lists", "index",
    'resource-lists/list[@name="mybuddies"]/entry[@uri="sip:alice@example.org"]',
    "uri")

It would return “sip:alice@example.org“ as obvious.

Get a 3rd party document owned by a different user (different “xui”) within the same XCAP server.

This is useful to implement shared contact lists or when fetching a OMA icon (avatar) of a different user (OMA icon is a XCAP document rather than a pure image).

  shared_contact_list_doc = xcapclient.application("resource-lists").add_document("shared_contact_list", :users, "sip:bob@example.org")

In this case it’s required to in indicate the document by a XCAPClient::Document object rather than a String:

  xcapclient.get("resource-lists", shared_contact_list_doc)

TODO

Requeriments

Install

  gem install xcapclient

Test Unit

The GEM includes a Test Unit script located in “test” directory name “test_unit_01.rb“. It performs various XCAP queries against a XCAP server using the test/PRES_RULES_EXAMPLE.xml document.

NOTE: You must edit the settings with your own values (edit the top lines of the script).

License

GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007

(see LICENSE.txt)

Author

IƱaki Baz Castillo

Files

Classes/Modules

Methods

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.