xcapclient 1.3.1 → 1.4.0

data/README.rdoc

@@ -1,4 +1,4 @@
-= XCAPClient (version 1.3.1)
+= XCAPClient (version 1.4.0)
 
 * http://dev.sipdoc.net/projects/ruby-xcapclient/wiki/
 * http://rubyforge.org/projects/xcapclient/
@@ -6,9 +6,9 @@
 
 == 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.
+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.
 
-XCAPClient library implements the XCAP protocol in client side, allowing the applications to get, store, modify and delete XML documents in the server.
+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
@@ -60,36 +60,55 @@ A developer interested in this library should study the following documents:
 ==== Create a client
 
   xcap_conf = {
-    :xcap_root => "https://xcap.myserver.org/xcap-root",
+    :xcap_root => "https://xcap.myserver.org",
     :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"
+    "resource-lists" => {
+      :xmlns       => "urn:ietf:params:xml:ns:resource-lists",
+      :mime_type   => "application/resource-lists+xml"
     }
   }
 
-  @xcapclient = Client.new(xcap_conf, xcap_apps)
+  xcapclient = Client.new(xcap_conf, xcap_apps)
 
 
-==== Fetch the "pres-rules" document from the server
+==== Create a XCAPClient::Document with name "index" for "resource-lists" application.
 
-  @xcapclient.get("pres-rules")
+  xcapclient.application("resource-lists").add_document("index")
 
+It's the same as doing:
 
-==== Fetch again the "pres-rules" document (now including the stored ETag)
+  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("pres-rules")
+    xcapclient.get("resource-lists")
   rescue XCAPClientError::HTTPDocumentNotModified
     puts "The document has not been modified in the server."
   end
@@ -97,48 +116,78 @@ By default, the methods accesing the XCAP server include the ETag if it's availa
 
 ==== 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")
+  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("pres-rules")
+  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"/>'
 
-==== 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 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")
 
-==== Fetch a node (with "id" = "sip:alice@example.org")
+It would return "sip:alice@example.org" as obvious.
 
-  @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" => "urn:ietf:params:xml:ns:common-policy"})
 
+==== Get a 3rd party document owned by a different user (different "xui") within the same XCAP server.
 
-==== Add a new node (a new allowed user in "pres-rules" document)
+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).
 
-  @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:one id="sip:bob@example.org"/>',
-    {"cp"=>"urn:ietf:params:xml:ns:common-policy"})
+  shared_contact_list_doc = xcapclient.application("resource-lists").add_document("shared_contact_list", :users, "sip:bob@example.org")
 
-==== Fetch a node attribute (node "name" from node with "id" = "sip:alice@example.org")
+In this case it's required to in indicate the document by a XCAPClient::Document object rather than a String:
 
-  @xcapclient.get_attribute("pres-rules", nil,
-    '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"})
+  xcapclient.get("resource-lists", shared_contact_list_doc)
 
 
-== ToDo
+== 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]).
 

data/lib/xcapclient/application.rb

@@ -9,39 +9,35 @@ module XCAPClient
       @auid = auid
 
       # Check application data.
-      raise ConfigError, "Application `data' must be a hash ('#{@auid}')" unless (Hash === 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?
+      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?
+      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?
+      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)
+      # Create the _documents_ Array.
+      @documents = []
 
     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]
+    # Get the XCAPClient::Document with name _name_, scope _scope_ (:users or :global) belonging to user _xui_.
+    # If _name_ is nil then the first available document is fetched (careful).
+    # If _scope_ is not set then it's :users by default. If _xui_ is nil then it's a document owned by us.
+    def document(name=nil, scope=nil, xui=nil)
+      scope = :users  unless scope
+      if name
+        @documents.find { |doc| doc.name == name and doc.scope == scope and doc.xui == xui }
+      else
+        @documents.first
+      end
     end
 
     # Get an Array containing all the documents created for this application.
@@ -49,12 +45,14 @@ module XCAPClient
       @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)
+    # Creates a new XCAPClient::Document for this application with name _document_name_, scope _scope_ and xui _xui_.
+    # _scope_ can be :users (default) or :global Symbol. If _xui_ is nil then the documents belongs to our user.
+    def add_document(name, scope=nil, xui=nil)
+      scope = :users  unless scope
+      raise DocumentError, "document '#{name}' with scope '#{scope} and xui '#{xui}' already exists"  if document(name, scope, xui)
+      @documents << document = Document.new(name, scope, xui)
 
-      return @documents[document_name]
+      return document
     end
 
   end

data/lib/xcapclient/client.rb

@@ -42,7 +42,6 @@ module XCAPClient
       "User-Agent" => "#{USER_AGENT}/#{VERSION}",
       "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, :identity_header, :identity_user, :ssl_verify_cert]
@@ -63,10 +62,6 @@ module XCAPClient
     #
     # * _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:
     #   * _xmlns_: The XML namespace uri of the application.
-    #   * _document_name_: The name of the default document for this application ("index" if not set).
-    #   * _scope_: Can be :user or :global (:user if not set).
-    #     * _:user_: Each user has his own document(s) for this application.
-    #     * _:global_: The document(s) is shared for all the users.
     #
     # Example:
     #   xcap_conf = {
@@ -79,15 +74,11 @@ module XCAPClient
     #   xcap_apps = {
     #     "pres-rules" => {
     #       :xmlns => "urn:ietf:params:xml:ns:pres-rules",
-    #       :mime_type => "application/auth-policy+xml",
-    #       :document_name => "index",
-    #       :scope => :user
+    #       :mime_type => "application/auth-policy+xml"
     #     },
     #     "rls-services" => {
     #       :xmlns => "urn:ietf:params:xml:ns:rls-services",
-    #       :mime_type => "application/rls-services+xml",
-    #       :document_name => "index",
-    #       :scope => :user
+    #       :mime_type => "application/rls-services+xml"
     #     }
     #   }
     #
@@ -103,7 +94,8 @@ module XCAPClient
     #     :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].
+    # 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={})
 
@@ -150,13 +142,12 @@ module XCAPClient
       # Generate applications.
       @applications = {}
 
-      # Add the "xcap-caps" application.
+      # Add the "xcap-caps" application with a document "index".
       @applications["xcap-caps"] = Application.new("xcap-caps", {
         :xmlns => "urn:ietf:params:xml:ns:xcap-caps",
-        :mime_type => "application/xcap-caps+xml",
-        :scope => :global,
-        :document_name => "index"
+        :mime_type => "application/xcap-caps+xml"
       })
+      @applications["xcap-caps"].add_document("index", :global)
 
       # Add custom applications.
       applications.each do |auid, data|
@@ -556,6 +547,9 @@ module XCAPClient
       raise WrongAUID, "There is no application with auid '#{auid}'" unless application
 
       # Get the document.
+      # NOTE: If _document_ is a String then it's supposed to be a document owned by our user with scope :users.
+      # NOTE: If _document_ is a Document then it can be whatever document.
+      # NOTE: If _document_ is nil then the first document is used (careful).
       case document
       when Document
       when String
@@ -563,11 +557,13 @@ module XCAPClient
         document = application.document(document_name)
         raise DocumentError, "document '#{document_name}' doesn't exist in application '#{auid}'" unless document
       when NilClass
-        document = application.document  # Default document.
+        document = application.documents.first
       else
         raise ArgumentError, "`document' must be Document, String or nil"
       end
 
+      raise ArgumentError, "no document provided"  unless document
+
       return [application, document]
 
     end
@@ -609,15 +605,23 @@ module XCAPClient
       extra_headers["Content-Type"] = content_type if content_type
 
       # XUI.
-      xui = case application.scope
-      when :user
-        "users/#{user_encode(@user)}"
+      xui = document.xui ? document.xui : @user
+
+      # scope/XUI.
+      scope_xui = case document.scope
+      when :users
+        "users/#{xui}"
       when :global
-        GLOBAL_XUI
+        "global"
       end
 
       # URI.
-      uri = "#{@xcap_root}/#{application.auid}/#{xui}/#{percent_encode(document.name)}"
+      uri = case document.scope
+      when :users
+        "#{@xcap_root}/#{application.auid}/users/#{xui}/#{percent_encode(document.name)}"
+      when :global
+        "#{@xcap_root}/#{application.auid}/global/#{percent_encode(document.name)}"
+      end
       uri += "/~~/#{percent_encode(selector)}" if selector
       uri +=  get_xmlns_query(xml_namespaces) if xml_namespaces
 

data/lib/xcapclient/document.rb

@@ -5,6 +5,12 @@ module XCAPClient
     # The name of the document as it exists in the server.
     attr_reader :name
 
+    # The scope of this document (:users or :global).
+    attr_reader :scope
+
+    # The XUI this document belongs to. This allow fetching a document owner by other user (for example a icon).
+    attr_reader :xui
+
     # Contains the plain document fetched from the server or manually set.
     attr_accessor :plain
 
@@ -17,15 +23,31 @@ module XCAPClient
     # The last response received from the server. It's a HTTP::Message[http://dev.ctor.org/doc/httpclient/] object.
     attr_accessor :last_response
 
-    # Create a new instance. _name_, _plain_ and _etag_ are String.
-    def initialize(name, plain=nil, etag=nil, parsed=nil)
+    # Convenient field to indicate that the document has been modified locally but it hasn't been commited
+    # yet to the server (true then).
+    # This field must be set manually by the application if it wants to use it (for example after giving a new
+    # value to @plain or after modifyng @parsed).
+    attr_accessor :local_modified
+
+    # Convenient field to indicate that the document has been modified in the server but it hasn't been fetched
+    # so the local copy isn't up-to-date (true then).
+    # This field must be set manually by the application if it wants to use it (for example after the SIP UA receives
+    # a NOTIFY indicating that this document has been modified in the server).
+    attr_accessor :server_modified
+
+    # Create a new instance. _name_ and _xui_ are String. _scope_ can be :users (default) or :group Symbol. _xui_ is the user
+    # owning the document, if it's nil then is a document owned by our user.
+    def initialize(name, scope=nil, xui=nil)
+      scope = :users  unless scope
       @name = name
-      @plain = plain
-      @parsed = parsed
-      @etag = etag
+      @scope = scope
+      @xui = xui
 
       # Check name.
-      raise ConfigError, "Document `name' must be a non empty string" unless String === @name && ! @name.empty?
+      raise ConfigError, "document `name' must be a non empty string" unless String === @name && ! @name.empty?
+
+      # Check scope.
+      raise ConfigError, "document `scope' must be :users or _global" unless @scope == :users or @scope == :global
     end
 
     # Delete the local plain and parsed document and the ETag.
@@ -39,7 +61,7 @@ module XCAPClient
       # Parse the plain XML document using Nokogiri and store it into @parsed attribute.
       # NOTE: This method is just available if Nokogiri is installed.
       def parse
-        raise DocumentError, "Cannot parse the document as the plain document doesn't exist"
+        raise DocumentError, "cannot parse the document as the plain document doesn't exist"  unless @plain
         begin
           @parsed = ::Nokogiri::XML::Document.parse(@plain, nil, "UTF-8", PARSE_OPTIONS)
         rescue ::Nokogiri::SyntaxError => e
@@ -50,4 +72,4 @@ module XCAPClient
 
   end
 
-end
+end

data/lib/xcapclient/version.rb

@@ -1,8 +1,8 @@
 module XCAPClient
 
   MAJOR = 1
-  MINOR = 3
-  TINY  = 1
+  MINOR = 4
+  TINY  = 0
 
   VERSION = [MAJOR, MINOR, TINY].join('.')
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: xcapclient
 version: !ruby/object:Gem::Version 
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors: 
 - "I\xC3\xB1aki Baz Castillo"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-05 00:00:00 +01:00
+date: 2010-02-12 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,7 +22,7 @@ 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.\n\n    Ruby xcapclient library implements the XCAP protocol in client side, allowing the applications to get, store, modify and delete XML documents in the server.'\n"
+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.
 email: ibc@aliax.net
 executables: []