xcapclient 1.1 → 1.2

data/ERRORS.rdoc

@@ -1,4 +1,3 @@
-
 == Errors
 
 The XCAPClient library includes custom Ruby exceptions. All these exceptions inherit from XCAPClient::XCAPClientError exception.
@@ -18,6 +17,7 @@ The XCAPClient library includes custom Ruby exceptions. All these exceptions inh
       * HTTPNoMatchingETag
       * HTTPConflictError
       * HTTPDocumentNotModified
+      * HTTPForbidden
       * HTTPDocumentNotFound
       * HTTPWrongContentType
       * HTTPBadRequest
@@ -80,6 +80,11 @@ Example:
 The server replied "409 Conflict". It occurs when the request couldn't be performed in the server.
 
 
+==== HTTPForbidden < HTTPError
+
+The server rejects the request with "403 Forbidden".
+
+
 ==== HTTPDocumentNotModified < HTTPError
 
 The server replied "304 Not Modified". It occurs when using ETag in "If-None-Match" header for a GET request. It means that the document has not been modified in the server so it's not fetched again (as the client already has it in a local cache).

data/README.rdoc

@@ -1,4 +1,4 @@
-= XCAPClient (version 1.1.X)
+= XCAPClient (version 1.2)
 
 * http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
 * http://rubyforge.org/projects/xcapclient/
@@ -18,8 +18,9 @@ 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).
-* Fetch the namespaces and prefixes of a document/node node as they are used in the server.
+* 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.
@@ -108,7 +109,7 @@ By default, the methods accesing the XCAP server include the ETag if it's availa
 
 ==== 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 = @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
@@ -118,21 +119,21 @@ By default, the methods accesing the XCAP server include the ETag if it's availa
 ==== Fetch a node (with "id" = "sip:alice@example.org")
 
   @xcapclient.get_node("pres-rules", nil,
-    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+    '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 node (a new allowed user in "pres-rules" document)
 
   @xcapclient.put_node("pres-rules", nil,
-    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+    '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"})
 
 ==== Fetch a node attribute (node "name" from node with "id" = "sip:alice@example.org")
 
   @xcapclient.get_attribute("pres-rules", nil,
-    '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+    'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
     "name",
     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 

data/lib/xcapclient.rb

@@ -1,6 +1,6 @@
 module XCAPClient
 	
-	VERSION = "1.1"
+	VERSION = "1.2"
 	
 	RUBY_VERSION_CORE = case RUBY_VERSION
 		when /^1\.9\./

data/lib/xcapclient/client.rb

@@ -40,23 +40,25 @@ module XCAPClient
 		USER_AGENT = "Ruby-XCAPClient"
 		COMMON_HEADERS = {
 			"User-Agent" => "#{USER_AGENT}/#{VERSION}",
-			"Connection" => "open"
+			"Connection" => "close"
 		}
 		GLOBAL_XUI = "global"
 		XCAP_CAPS_XMLNS = "urn:ietf:params:xml:ns:xcap-caps"
 		HTTP_TIMEOUT = 6
-		CONF_PARAMETERS = [:xcap_root, :user, :auth_user, :password, :ssl_verify_cert]
+		CONF_PARAMETERS = [:xcap_root, :user, :auth_user, :password, :identity_header, :identity_user, :ssl_verify_cert]
 		
 		
-		attr_reader :xcap_root, :user, :auth_user, :password, :ssl_verify_cert
+		attr_reader :xcap_root, :user, :auth_user, :password, :identity_header, :identity_user, :ssl_verify_cert
 		
 		
 		# Create a new XCAP client. It requires two parameters:
 		#
 		# * _conf_: A hash containing settings related to the server:
 		#   * _xcap_root_: The URL where the documents hold.
-		#   * _user_: The client username. Depending on the server it could look like "sip:alice@domain.org", "alice@domain.org" or "alice".
-		#   * _auth_user_: Username for authentication (if required).
+		#   * _user_: The client username. Depending on the server it could look like "sip:alice@domain.org", "alice@domain.org", "alice", "tel:+12345678"...
+		#   * _auth_user_: Username, SIP URI or TEL URI for HTTP Digest authentication (if required). If not set it takes the value of _user_ field.
+		#   * _identity_header_: Header required in some XCAP networks containing the user identity (i.e. "X-XCAP-Preferred-Identity").
+		#   * _identity_user_: Value for the _identity_header_. It could be a SIP or TEL URI. If not set it takes teh value of _user_ field.
 		#   * _ssl_verify_cert_: If true and the server uses SSL, the certificate is inspected (expiration time, signature...).
 		#
 		# * _applications_: A hash of hashes containing each XCAP application available for the client. Each application is an entry of the hash containing a key whose value is the "auid" of the application and whose value is a hast with the following fields:
@@ -91,6 +93,16 @@ module XCAPClient
 		#
 		#   @client = Client.new(xcap_conf, xcap_apps)
 		#
+		# Example:
+		#   xcap_conf = {
+		#     :xcap_root => "https://xcap.domain.net",
+		#     :user => "tel:+12345678",
+		#     :auth_user => "tel:+12345678",
+		#     :password => "1234",
+		#     :identity_header => "X-XCAP-Preferred-Identity",
+		#     :ssl_verify_cert => true
+		#   }
+		#
 		# A XCAP application called "xcap-caps" is automatically added to the list of applications of the new client. This application is defined in the {RFC 4825}[http://tools.ietf.org/html/rfc4825].
 		#
 		def initialize(conf={}, applications={})
@@ -104,7 +116,7 @@ module XCAPClient
 			end
 			
 			# Check xcap_root parameter.
-			@xcap_root = URI.parse(conf[:xcap_root].to_s)
+			@xcap_root = ( conf[:xcap_root] =~ /\/$/ ) ? URI.parse(conf[:xcap_root][0..-2]) : URI.parse(conf[:xcap_root])
 			raise ConfigError, "`xcap_root' must be http or https URI" unless [URI::HTTP, URI::HTTPS].include?(@xcap_root.class)
 			
 			# Check user.
@@ -114,6 +126,10 @@ module XCAPClient
 			@auth_user = conf[:auth_user].freeze || @user
 			@password = conf[:password].freeze
 			
+			@identity_header = conf[:identity_header].freeze
+			@identity_user = ( conf[:identity_user].freeze || @user )  if @identity_header
+			COMMON_HEADERS[@identity_header] = @identity_user  if @identity_header
+			
 			# Initialize the HTTP client.
 			@http_client = HTTPClient.new
 			@http_client.set_auth(@xcap_root, @auth_user, @password)
@@ -252,7 +268,7 @@ module XCAPClient
 		# Example, fetching the node with "id" = "sip:alice@example.org":
 		#
 		#   @xcapclient.get_node("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     '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"})
 		#
 		# If success:
@@ -275,7 +291,7 @@ module XCAPClient
 		# Example, creating/replacing the node with "id" = "sip:alice@example.org":
 		#
 		#   @xcapclient.put_node("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+		#     '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"})
 		#
@@ -302,7 +318,7 @@ module XCAPClient
 		# Example, deleting the node with "id" = "sip:alice@example.org":
 		#
 		#   @xcapclient.delete_node("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     '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"})
 		#
 		# If success:
@@ -329,7 +345,7 @@ module XCAPClient
 		# "id" = "sip:alice@example.org":
 		#
 		#   @xcapclient.get_attribute("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 		#     "name",
 		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 		#
@@ -355,7 +371,7 @@ module XCAPClient
 		# "id" = "sip:alice@example.org" with new value "Alice Yeah":
 		#
 		#   @xcapclient.put_attribute("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 		#     "name",
 		#     "Alice Yeah",
 		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
@@ -384,7 +400,7 @@ module XCAPClient
 		# "id" = "sip:alice@example.org":
 		#
 		#   @xcapclient.delete_attribute("pres-rules", nil,
-		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 		#     "name",
 		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
 		#
@@ -418,7 +434,7 @@ module XCAPClient
 		# Example:
 		#
 		#   @xcapclient.get_node_namespaces("pres-rules", nil,
-		#     '/ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]',
+		#     'ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]',
 		#     { "ccpp" => "urn:ietf:params:xml:ns:common-policy" })
 		#
 		# Assuming the server uses "cp" for that namespace, it would reply:
@@ -541,7 +557,7 @@ module XCAPClient
 		#
 		def get_xmlns_query(xml_namespaces)
 			
-			return "" unless xml_namespaces
+			return "" if ( ! xml_namespaces || xml_namespaces.empty? )
 			
 			xmlns_query="?"
 			xml_namespaces.each do |prefix, uri|
@@ -578,8 +594,8 @@ module XCAPClient
 			end
 			
 			# URI.
-			uri = "#{@xcap_root}/#{application.auid}/#{xui}/#{document.name}"
-			uri += "/~~#{percent_encode(selector)}" if selector
+			uri = "#{@xcap_root}/#{application.auid}/#{xui}/#{percent_encode(document.name)}"
+			uri += "/~~/#{percent_encode(selector)}" if selector
 			uri +=  get_xmlns_query(xml_namespaces) if xml_namespaces
 			
 			# Body (just in case of PUT).
@@ -606,6 +622,9 @@ module XCAPClient
 			when "400"
 				raise HTTPBadRequest
 				
+			when "403"
+				raise HTTPForbidden
+				
 			when "404"
 				raise HTTPDocumentNotFound
 				

data/lib/xcapclient/errors.rb

@@ -8,6 +8,7 @@ module XCAPClient
 		class DocumentError < XCAPClientError ; end
 		class HTTPError < XCAPClientError ; end
 			class HTTPAuthenticationError < HTTPError ; end
+			class HTTPForbidden < HTTPError ; end
 			class HTTPNoMatchingETag < HTTPError ; end
 			class HTTPConflictError < HTTPError ; end
 			class HTTPDocumentNotModified < HTTPError ; end

data/test/test_unit_01.rb

@@ -153,7 +153,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_10_get_element
 		show "Fetching a node (no ETag) => 200"
 		assert @client.get_element("pres-rules", nil,
-			'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+			'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
 			NS,
 			check_etag=false)
 	end
@@ -163,7 +163,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		show "Fetching a node (correct ETag) => 304"
 		begin
 			@client.get_element("pres-rules", nil,
-				'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+				'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 				NS,
 				check_etag=true)
 		rescue => e
@@ -179,7 +179,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_12_get_element
 		show "Fetching an attribute (no ETag) => 200 (fails in OpenXCAP, bug http://openxcap.org/ticket/122)"
 		assert @client.get_element("pres-rules", nil,
-			'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]/@id',
+			'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]/@id',
 			NS,
 			check_etag=false)
 	end
@@ -188,7 +188,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_13_put_element
 		show "Creating a node (no ETag) => 201"
 		assert @client.put_element("pres-rules", nil,
-			'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:new-1@new.net"]',
+			'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:new-1@new.net"]',
 			'<cp:one id="sip:new-1@new.net"/>',
 			NS,
 			check_etag=false)
@@ -200,7 +200,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		begin
 			@doc.etag = "wrongETag"
 			@client.put_element("pres-rules", nil,
-				'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:condition/cp:identity/cp:one[@id="sip:new-2@new.net"]',
+				'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:condition/cp:identity/cp:one[@id="sip:new-2@new.net"]',
 				'<cp:one id="sip:new-2@new.net"/>',
 				NS,
 				check_etag=true)
@@ -216,7 +216,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		show "Creating a node in wrong position => 409"
 		begin
 			@client.put_element("pres-rules", nil,
-				'/cp:ruleset/cp:rule[@id="non_existing"]/cp:condition/cp:identity/cp:one[@id="sip:new-3@new.net"]',
+				'cp:ruleset/cp:rule[@id="non_existing"]/cp:condition/cp:identity/cp:one[@id="sip:new-3@new.net"]',
 				'<cp:one id="sip:new-3@new.net"/>',
 				NS,
 				check_etag=false)
@@ -232,7 +232,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		show "Creating a node using different NS prefixes than the used in the server document (no ETag) => 409/500"
 		begin
 			@client.put_element("pres-rules", nil,
-				'/ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]/ccpp:conditions/ccpp:identity/ccpp:one[@id="sip:new-4@new.net"]',
+				'ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]/ccpp:conditions/ccpp:identity/ccpp:one[@id="sip:new-4@new.net"]',
 				'<ccpp:one id="sip:new-4@new.net"/>',
 				{"pprr"=>"urn:ietf:params:xml:ns:pres-rules", "ccpp"=>"urn:ietf:params:xml:ns:common-policy"},
 				check_etag=false)
@@ -250,7 +250,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		show "Creating a node using using a non unique selector (no ETag) => 409 (fails in OpenXCAP, bug http://openxcap.org/ticket/123)"
 		begin
 			@client.put_element("pres-rules", nil,
-				'/cp:ruleset/cp:rule/cp:conditions/cp:identity/cp:one[@id="sip:new-5@new.net"]',
+				'cp:ruleset/cp:rule/cp:conditions/cp:identity/cp:one[@id="sip:new-5@new.net"]',
 				'<cp:one id="sip:new-5@new.net"/>',
 				NS,
 				check_etag=false)
@@ -265,7 +265,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_18_delete_element
 		show "Deleting an element (no ETag) => 200"
 		assert @client.delete_element("pres-rules", nil,
-			'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+			'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
 			NS,
 			check_etag=false)
 	end
@@ -276,7 +276,7 @@ class TestXCAPClient < Test::Unit::TestCase
 		begin
 			@doc.etag = "wrongETag"
 			@client.delete_element("pres-rules", nil,
-				'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:condition/cp:identity/cp:one[@id="sip:bob@example.org"]',
+				'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:condition/cp:identity/cp:one[@id="sip:bob@example.org"]',
 				NS,
 				check_etag=true)
 		rescue => e
@@ -290,7 +290,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_20_delete_element
 		show "Deleting a no existing element (correct ETag) => 404"
 		@client.delete_element("pres-rules", nil,
-			'/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+			'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
 			NS)
 		begin
 			@client.delete_element("pres-rules", nil,
@@ -309,7 +309,7 @@ class TestXCAPClient < Test::Unit::TestCase
 	def test_21_get_element_namespaces
 		show "Fetching the namespaces associated to a document node => 200 (fails in OpenXCAP, bug http://openxcap.org/ticket/124)"
 		assert @client.get_element_namespaces("pres-rules", nil,
-				'/ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]/ccpp:conditions/ccpp:identity',
+				'ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]/ccpp:conditions/ccpp:identity',
 				{"ccpp"=>"urn:ietf:params:xml:ns:common-policy"},
 				check_etag=false)
 		assert_equal( @client.application("pres-rules").document.last_response.header["Content-Type"], "application/xcap-ns+xml" )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: xcapclient
 version: !ruby/object:Gem::Version 
-  version: "1.1"
+  version: "1.2"
 platform: ruby
 authors: 
 - "I\xC3\xB1aki Baz Castillo"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-09 00:00:00 +01:00
+date: 2009-11-23 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,7 +22,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: XCAP (RFC 4825) is a protocol on top of HTTP which allows a client (usually a VoIP/SIP device) to manipulate the contents of Presence Information Data Format (PIDF) based presence documents. These documents are stored in a server in XML format.  Ruby xcapclient library implements the XCAP protocol in client side, allowing the applications to get, store, modify and delete XML documents in the server.'
+description: "\t\tXCAP (RFC 4825) is a protocol on top of HTTP which allows a client (usually a VoIP/SIP device) to manipulate the contents of Presence Information Data Format (PIDF) based presence documents. These documents are stored in a server in XML format.\n\
+  \t\t\n\
+  \t\tRuby xcapclient library implements the XCAP protocol in client side, allowing the applications to get, store, modify and delete XML documents in the server.'\n"
 email: ibc@aliax.net
 executables: []
 
@@ -45,6 +47,8 @@ files:
 - ERRORS.rdoc
 has_rdoc: true
 homepage: http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --main
@@ -68,9 +72,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: xcapclient
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: XCAP client library
 test_files: 
 - test/test_unit_01.rb