xcapclient 1.0

data/README.rdoc

@@ -0,0 +1,172 @@
+= XCAPClient
+
+* 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 which allows a client to manipulate the contents of Presence Information Data Format (PIDF) based presence documents. These documents are stored in a server in XML format and are fetched, modified, replaced or deleted by the client. The protocol allows multiple clients to manipulate the data, provided that they are authorized to do so.  XCAP is already used in SIMPLE-based presence systems for manipulation of presence lists and presence authorization policies.
+
+XCAPClient library implements the XCAP protocol in client side, allowing the applications to get, store, modify and delete XML documents in the server.
+
+
+== Features
+
+The library implements the following features:
+
+* Fetch, create/replace and delete a document.
+* Fetch, create/replace and delete a document element (XML node).
+* Fetch, create/replace and delete an element attribute.
+* 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).
+* Fetch the namespaces and prefixes of a document node as they are used in the server.
+* 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/xcap-root",
+    :user => "sip:me@mydomain.org",
+    :auth_user => "me",
+    :password => "xxxxxx",
+    :ssl_verify_cert => true
+  }
+  
+  xcap_apps = {
+    "pres-rules" => {
+      :xmlns => "urn:ietf:params:xml:ns:pres-rules",
+      :mime_type => "application/auth-policy+xml",
+      :scope => :user,
+      :document_name => "index"
+    }
+  }
+  
+  @xcapclient = Client.new(xcap_conf, xcap_apps)
+
+
+==== Fetch the "pres-rules" document from the server
+
+  @xcapclient.get("pres-rules")
+  
+
+==== Fetch again the "pres-rules" 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("pres-rules")
+  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("pres-rules").document.reset
+  @xcapclient.application("pres-rules").document.plain = "<?xml version='1.0' encoding='UTF-8'?> ..."
+  @xcapclient.put("pres-rules")
+
+
+==== Delete the document in the server
+
+  @xcapclient.delete("pres-rules")
+
+
+==== Create a new document and upload it (a new "vacation-rules" document for "pres-rules" application)
+
+  my_pres_rules_2 = @xcapclient.application("pres-rules).add_document("vacation-rules")
+  my_pres_rules_2.plain = "<?xml version='1.0' encoding='UTF-8'?> ..."
+  @xcapclient.put("pres-rules", my_pres_rules_2)
+    # or
+  @xcapclient.put("pres-rules", "vacation-rules")
+
+
+==== Fetch an element
+
+  @xcapclient.get_element("pres-rules", nil,
+    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+    {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+  
+
+==== Add a new element (a new allowed user in "pres-rules" document)
+
+  @xcapclient.put_element("pres-rules", nil,
+    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+    '<cp:one id="sip:bob@example.org"/>',
+    {"cp"=>"urn:ietf:params:xml:ns:common-policy"})
+
+
+== 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:ibc@aliax.net
+* http://dev.sipdoc.net
+
+

data/lib/xcapclient/application.rb

@@ -0,0 +1,62 @@
+module XCAPClient
+	
+	class Application
+		
+		attr_reader :auid, :xmlns, :mime_type, :document_name, :scope
+		
+		def initialize(auid, data={})  #:nodoc:
+			
+			@auid = auid
+			
+			# Check application data.
+			raise ConfigError, "Application `data' must be a hash ('#{@auid}')" unless (Hash === data)
+			
+			@xmlns = data[:xmlns].freeze
+			@mime_type = data[:mime_type].freeze
+			@document_name = data[:document_name] || "index"
+			@scope = data[:scope] || :user
+			@scope.freeze
+			
+			# Check auid.
+			raise ConfigError, "Application `auid' must be a non empty string ('#{@auid}')" unless String === @auid && ! @auid.empty?
+				
+			# Check xmlns.
+			raise ConfigError, "Application `xmlns' must be a non empty string ('#{@auid}')" unless String === @xmlns && ! @xmlns.empty?
+			
+			# Check mime-type.
+			raise ConfigError, "Application `mime_type' must be a non empty string ('#{@auid}')" unless String === @mime_type && ! @mime_type.empty?
+			
+			# Check document_name
+			raise ConfigError, "Application `document_name' must be a non empty string ('#{@auid}')" unless String === @document_name && ! @document_name.empty?
+			
+			# Check scope.
+			raise ConfigError, "Application `scope' must be :user or :global ('#{@auid}')" unless [:user, :global].include?(@scope)
+			
+			# Create first document.
+			@documents = {}
+			@documents[@document_name] = Document.new(@document_name)
+			
+		end
+		
+		# Get the XCAPClient::Document with name _document_name_ within this application. If the parameter is not set, the default document is got.
+		#
+		def document(document_name=nil)
+			@documents[document_name || @document_name]
+		end
+		
+		# Get an Array containing all the documents created for this application.
+		def documents
+			@documents
+		end
+		
+		# Creates a new XCAPClient::Document for this application with name _document_name_.
+		def add_document(document_name)
+			raise DocumentError, "document '#{document_name}' already exists" if @documents[document_name]
+			@documents[document_name] = Document.new(document_name)
+			
+			return @documents[document_name]
+		end
+		
+	end
+	
+end