xcapclient

= XCAPClient (version 1.4.0)

• http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
• http://rubyforge.org/projects/xcapclient/

== Description

XCAP ({RFC 4825}[http://tools.ietf.org/html/rfc4825]) 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:

• Fetch, create/replace and delete a XML document.
• Fetch, create/replace and delete a XML node.
• Fetch, create/replace and delete a XML node attribute.
• Fetch node namespace bindings as they are used in the server ({RFC 4825 Section 7.10}[http://tools.ietf.org/html/rfc4825#section-7.10]).
• Full configurable parameters allowing customized fields for each XCAP application, such auid, XML namespace, MIME-Type, scope (:user or :global) and default document name ("index" if not set).
• Custom identity header (as "X-XCAP-Preferred-Identity") required in some XCAP/XDM environments.
• Manage of multiple documents per XCAP application.
• Fetch the XCAP server auids, extensions and namespaces ("xcap-caps" application).
• SSL.
• Digest and Basic HTTP authentication.
• Raise custom Ruby exception for each HTTP error response.

Ruby XCAPClient works in Ruby 1.8 and 1.9.

== Support

The XCAPClient mailing list is available here:

• http://rubyforge.org/mailman/listinfo/xcapclient-devel

The bug tracker is available here:

• http://dev.sipdoc.net/projects/ruby-xcapclient/issues

== API

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

• XCAPClient::Client
• XCAPClient::Application
• XCAPClient::Document
• ERRORS.rdoc

== Synopsis

require 'rubygems' require 'xcapclient'

==== Create a client

xcap_conf = { :xcap_root => "https://xcap.myserver.org", :user => "sip:[e-mail]", :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 = " ..."

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 = " ..."

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

or:

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

==== Fetch a node (with "uri" = "sip:[e-mail]")

xcapclient.get_node("resource-lists", "index", 'rl:resource-lists/rl:list[@name="mybuddies"]/rl:entry[@uri="sip:[e-mail]"]', {"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:[e-mail]"]')

==== Add a new node (a new buddy)

xcapclient.put_node("resource-lists", "index", 'resource-lists/list[@name="mybuddies"]/entry[@uri="sip:[e-mail]"]', ''

==== Fetch a node attribute (the "uri" attribute of "sip:[e-mail]")

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

It would return "sip:[e-mail]" 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:[e-mail]")

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

• Parse 409 error response ("application/xcap-error+xml") as it contains the explanation of the conflict ({RFC 4825 section 11}[http://tools.ietf.org/html/rfc4825#section-11]).

== Requeriments

• Ruby 1.8 or 1.9
• HTTPClient[http://dev.ctor.org/http-access2]
• Nokogiri[http://wiki.github.com/tenderlove/nokogiri] (optional, it provides some non vital features)

== 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

• mailto:[e-mail]
• http://dev.sipdoc.net