Class: XCAPClient::Client
- Inherits:
-
Object
- Object
- XCAPClient::Client
- Defined in:
- lib/xcapclient/client.rb
Overview
The base class of the library. A program using this library must instantiate it.
Common notes for methods get*
, put*
and delete*
Shared parameters
auid: String, the auid of the application. Example:“pres-rules”.
document: nil by default. It can be:
* String, so the application must contain a document called as it.
* XCAPClient::Document object.
* nil, so the application default document is selected.
check_etag: true by default. If true the client adds the header “If-None-Match” or “If-Match” to the HTTP request containing the last ETag received.
selector: Document/node selector. The path that identifies the XML document or node within the XCAP root URL. It’s automatically converted to ASCII and percent encoded if needed. Example:
'/cp:ruleset/cp:rule/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]'
xml_namespaces: nil by default. It’s a hash containing the prefixes and namespaces used in the query. Example:
{"pr"=>"urn:ietf:params:xml:ns:pres-rules", "cp"=>"urn:ietf:params:xml:ns:common-policy"}
Exceptions
If these methods receive a non HTTP 2XX response they generate an exception. Check ERRORS.rdoc for detailed info.
Access to the full response
In any case, the HTTP response is stored in the document last_response attribute as an :Message object. To get it:
@xcapclient.application("pres-rules").document.last_response
Constant Summary collapse
- USER_AGENT =
"Ruby-XCAPClient"
- COMMON_HEADERS =
{ "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]
Instance Attribute Summary collapse
-
#auth_user ⇒ Object
readonly
Returns the value of attribute auth_user.
-
#identity_header ⇒ Object
readonly
Returns the value of attribute identity_header.
-
#identity_user ⇒ Object
readonly
Returns the value of attribute identity_user.
-
#password ⇒ Object
readonly
Returns the value of attribute password.
-
#ssl_verify_cert ⇒ Object
readonly
Returns the value of attribute ssl_verify_cert.
-
#user ⇒ Object
readonly
Returns the value of attribute user.
-
#xcap_root ⇒ Object
readonly
Returns the value of attribute xcap_root.
Instance Method Summary collapse
-
#application(auid) ⇒ Object
Returns the XCAPClient::Application whose auid mathes the auid parameter.
-
#applications ⇒ Object
Returns an Array with all the applications configured in the client.
-
#delete(auid, document = nil, check_etag = true) ⇒ Object
Delete a document in the server.
-
#delete_attribute(auid, document, selector, attribute_name, xml_namespaces = nil, check_etag = true) ⇒ Object
Delete a node attribute in the document stored in the server.
-
#delete_node(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Delete a node in the document stored in the server.
-
#get(auid, document = nil, check_etag = true) ⇒ Object
Fetch a document from the server.
-
#get_attribute(auid, document, selector, attribute_name, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch a node attribute from the document stored in the server.
-
#get_node(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch a node from the document stored in the server.
-
#get_node_namespaces(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch the namespace prefixes of a node.
-
#get_xcap_auids ⇒ Object
Fetch the XCAP applications (auids) supported by the server.
-
#get_xcap_extensions ⇒ Object
Fetch the XCAP extensions supported by the server.
-
#get_xcap_namespaces ⇒ Object
Fetch the XCAP namespaces supported by the server.
-
#initialize(conf = {}, applications = {}) ⇒ Client
constructor
Create a new XCAP client.
-
#put(auid, document = nil, check_etag = true) ⇒ Object
Create/replace a document in the server.
-
#put_attribute(auid, document, selector, attribute_name, attribute_value, xml_namespaces = nil, check_etag = true) ⇒ Object
Create/replace a node attribute in the document stored in the server.
-
#put_node(auid, document, selector, selector_body, xml_namespaces = nil, check_etag = true) ⇒ Object
Create/replace a node in the document stored in the server.
Constructor Details
#initialize(conf = {}, applications = {}) ⇒ Client
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:[email protected]”, “[email protected]”, “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:
-
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 = {
:xcap_root => "https://xcap.domain.org/xcap-root",
:user => "sip:[email protected]",
:auth_user => "alice",
:password => "1234",
:ssl_verify_cert => false
}
xcap_apps = {
"pres-rules" => {
:xmlns => "urn:ietf:params:xml:ns:pres-rules",
:mime_type => "application/auth-policy+xml",
:document_name => "index",
:scope => :user
},
"rls-services" => {
:xmlns => "urn:ietf:params:xml:ns:rls-services",
:mime_type => "application/rls-services+xml",
:document_name => "index",
:scope => :user
}
}
@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.
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 |
# File 'lib/xcapclient/client.rb', line 108 def initialize(conf={}, applications={}) # Check conf hash. raise ConfigError, "`conf' must be a hash" unless (Hash === conf) # Check non existing parameter names. conf.each_key do |key| raise ConfigError, "Uknown parameter name '#{key}' in `conf' hash" unless CONF_PARAMETERS.include?(key) end # Check xcap_root parameter. @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. @user = conf[:user].freeze raise ConfigError, "`user' must be a non empty string" unless (String === @user && ! @user.empty?) @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) @http_client.protocol_retry_count = 3 ### TODO: Set an appropiate value (min 2 for 401). @http_client.connect_timeout = HTTP_TIMEOUT @http_client.send_timeout = HTTP_TIMEOUT @http_client.receive_timeout = HTTP_TIMEOUT @xcap_root.freeze # Freeze now as it has been modified in @http_client.set_auth. # Check ssl_verify_cert parameter. if URI::HTTPS === @xcap_root @ssl_verify_cert = conf[:ssl_verify_cert] || false raise ConfigError, "`ssl_verify_cert' must be true or false" unless [TrueClass, FalseClass].include?(@ssl_verify_cert.class) @http_client.ssl_config.verify_mode = ( @ssl_verify_cert ? 3 : 0 ) end # Generate applications. @applications = {} # Add the "xcap-caps" application. @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" }) # Add custom applications. applications.each do |auid, data| @applications[auid] = Application.new(auid, data) end @applications.freeze end |
Instance Attribute Details
#auth_user ⇒ Object (readonly)
Returns the value of attribute auth_user.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def auth_user @auth_user end |
#identity_header ⇒ Object (readonly)
Returns the value of attribute identity_header.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def identity_header @identity_header end |
#identity_user ⇒ Object (readonly)
Returns the value of attribute identity_user.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def identity_user @identity_user end |
#password ⇒ Object (readonly)
Returns the value of attribute password.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def password @password end |
#ssl_verify_cert ⇒ Object (readonly)
Returns the value of attribute ssl_verify_cert.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def ssl_verify_cert @ssl_verify_cert end |
#user ⇒ Object (readonly)
Returns the value of attribute user.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def user @user end |
#xcap_root ⇒ Object (readonly)
Returns the value of attribute xcap_root.
51 52 53 |
# File 'lib/xcapclient/client.rb', line 51 def xcap_root @xcap_root end |
Instance Method Details
#application(auid) ⇒ Object
Returns the XCAPClient::Application whose auid mathes the auid parameter.
Example:
@xcapclient.application("pres-rules")
177 178 179 |
# File 'lib/xcapclient/client.rb', line 177 def application(auid) @applications[auid] end |
#applications ⇒ Object
Returns an Array with all the applications configured in the client.
183 184 185 |
# File 'lib/xcapclient/client.rb', line 183 def applications @applications end |
#delete(auid, document = nil, check_etag = true) ⇒ Object
Delete a document in the server.
Example:
@xcapclient.delete("pres-rules")
If success:
-
The method returns true.
-
Local plain document and ETag are deleted.
252 253 254 255 256 257 258 259 260 261 262 263 |
# File 'lib/xcapclient/client.rb', line 252 def delete(auid, document=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:delete, application, document, nil, nil, nil, nil, check_etag) # Reset the local document. document.plain = nil document.etag = nil return true end |
#delete_attribute(auid, document, selector, attribute_name, xml_namespaces = nil, check_etag = true) ⇒ Object
Delete a node attribute in the document stored in the server.
Example, deleting the “name” attribute of the node with “id” = “sip:[email protected]”:
@xcapclient.delete_attribute("pres-rules", nil,
'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]',
"name",
{"cp" => "urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns true.
-
Local plain document and ETag are deleted (as the document has changed).
411 412 413 414 415 416 417 418 419 420 421 422 |
# File 'lib/xcapclient/client.rb', line 411 def delete_attribute(auid, document, selector, attribute_name, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:delete, application, document, selector + "/@#{attribute_name}", nil, xml_namespaces, nil, check_etag) # Reset local plain document and ETag as we have modified it document.plain = nil document.etag = nil return true end |
#delete_node(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Delete a node in the document stored in the server.
Example, deleting the node with “id” = “sip:[email protected]”:
@xcapclient.delete_node("pres-rules", nil,
'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]',
{"cp" => "urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns true.
-
Local plain document and ETag are deleted (as the document has changed).
328 329 330 331 332 333 334 335 336 337 338 339 |
# File 'lib/xcapclient/client.rb', line 328 def delete_node(auid, document, selector, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:delete, application, document, selector, nil, xml_namespaces, nil, check_etag) # Reset local plain document and ETag as we have modified it document.plain = nil document.etag = nil return true end |
#get(auid, document = nil, check_etag = true) ⇒ Object
Fetch a document from the server.
Example:
@xcapclient.get("pres-rules")
If success:
-
The method returns true.
-
Received XML plain document is stored in
@xcapclient.application("pres-rules").document.plain
(the default document). -
Received ETag is stored in
@xcapclient.application("pres-rules").document.etag
.
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 |
# File 'lib/xcapclient/client.rb', line 199 def get(auid, document=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:get, application, document, nil, nil, nil, nil, check_etag) # Check Content-Type. check_content_type(response, application.mime_type) # Store the plain document. document.plain = response.body.content # Update ETag. document.etag = response.header["ETag"].first return true end |
#get_attribute(auid, document, selector, attribute_name, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch a node attribute from the document stored in the server.
Example, fetching the “name” attribute of the node with “id” = “sip:[email protected]”:
@xcapclient.get_attribute("pres-rules", nil,
'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]',
"name",
{"cp" => "urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns the attribute as a String.
355 356 357 358 359 360 361 362 363 364 365 |
# File 'lib/xcapclient/client.rb', line 355 def get_attribute(auid, document, selector, attribute_name, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:get, application, document, selector + "/@#{attribute_name}", nil, xml_namespaces, nil, check_etag) # Check Content-Type. check_content_type(response, "application/xcap-att+xml") return response.body.content end |
#get_node(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch a node from the document stored in the server.
Example, fetching the node with “id” = “sip:[email protected]”:
@xcapclient.get_node("pres-rules", nil,
'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]',
{"cp" => "urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns the node as a String.
277 278 279 280 281 282 283 284 285 286 287 |
# File 'lib/xcapclient/client.rb', line 277 def get_node(auid, document, selector, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:get, application, document, selector, nil, xml_namespaces, nil, check_etag) # Check Content-Type. check_content_type(response, "application/xcap-el+xml") return response.body.content end |
#get_node_namespaces(auid, document, selector, xml_namespaces = nil, check_etag = true) ⇒ Object
Fetch the namespace prefixes of a node.
If the client wants to create/replace a node, the body of the PUT request must use the same namespaces and prefixes as those used in the document stored in the server. This methods allows the client to fetch these namespaces and prefixes.
Related documentation: RFC 4825 section 7.10, RFC 4825 section 10
Example:
@xcapclient.get_node_namespaces("pres-rules", nil,
'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:
HTTP/1.1 200 OK
Content-Type: application/xcap-ns+xml
<cp:identity xmlns:pr="urn:ietf:params:xml:ns:pres-rules"
xmlns:cp="urn:ietf:params:xml:ns:common-policy" />
If Nokogiri is available the method returns a hash:
{"pr"=>"urn:ietf:params:xml:ns:pres-rules", "cp"=>"urn:ietf:params:xml:ns:common-policy"}
If not, the method returns the response body as a String and the application must parse it.
453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 |
# File 'lib/xcapclient/client.rb', line 453 def get_node_namespaces(auid, document, selector, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:get, application, document, selector + "/namespace::*", nil, xml_namespaces, nil, check_etag) # Check Content-Type. check_content_type(response, "application/xcap-ns+xml") return case NOKOGIRI_INSTALLED when true Nokogiri::XML.parse(response.body.content).namespaces when false response.body.content end end |
#get_xcap_auids ⇒ Object
Fetch the XCAP applications (auids) supported by the server.
Related documentation: RFC 4825 section 12
If Nokogiri is available the method returns an Array containing the auids. If not, the response body is returned as a String.
478 479 480 481 482 483 484 485 486 487 488 489 |
# File 'lib/xcapclient/client.rb', line 478 def get_xcap_auids body = get_node("xcap-caps", nil, 'xcap-caps/auids') return case NOKOGIRI_INSTALLED when true parse(body).xpath("auids/auid", {"xmlns" => XCAP_CAPS_XMLNS}).map {|auid| auid.content} when false body end end |
#get_xcap_extensions ⇒ Object
Fetch the XCAP extensions supported by the server.
Same as XCAPClient::Client::get_xcap_auids but fetching the supported extensions.
496 497 498 499 500 501 502 503 504 505 506 507 |
# File 'lib/xcapclient/client.rb', line 496 def get_xcap_extensions body = get_node("xcap-caps", nil, 'xcap-caps/extensions') return case NOKOGIRI_INSTALLED when true parse(body).xpath("extensions/extension", {"xmlns" => XCAP_CAPS_XMLNS}).map {|extension| extension.content} when false body end end |
#get_xcap_namespaces ⇒ Object
Fetch the XCAP namespaces supported by the server.
Same as XCAPClient::Client::get_xcap_auids but fetching the supported namespaces.
514 515 516 517 518 519 520 521 522 523 524 525 |
# File 'lib/xcapclient/client.rb', line 514 def get_xcap_namespaces body = get_node("xcap-caps", nil, 'xcap-caps/namespaces') return case NOKOGIRI_INSTALLED when true parse(body).xpath("namespaces/namespace", {"xmlns" => XCAP_CAPS_XMLNS}).map {|namespace| namespace.content} when false body end end |
#put(auid, document = nil, check_etag = true) ⇒ Object
Create/replace a document in the server.
Example:
@xcapclient.put("pres-rules")
If success:
-
The method returns true.
-
Local plain document in
@xcapclient.application("pres-rules").document.plain
is uploaded to the server. -
Received ETag is stored in
@xcapclient.application("pres-rules").document.etag
.
229 230 231 232 233 234 235 236 237 238 239 |
# File 'lib/xcapclient/client.rb', line 229 def put(auid, document=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:put, application, document, nil, nil, nil, application.mime_type, check_etag) # Update ETag. document.etag = response.header["ETag"].first return true end |
#put_attribute(auid, document, selector, attribute_name, attribute_value, xml_namespaces = nil, check_etag = true) ⇒ Object
Create/replace a node attribute in the document stored in the server.
Example, creating/replacing the “name” attribute of the node with “id” = “sip:[email protected]” 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:[email protected]"]',
"name",
"Alice Yeah",
{"cp" => "urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns true.
-
Local plain document and ETag are deleted (as the document has changed).
383 384 385 386 387 388 389 390 391 392 393 394 |
# File 'lib/xcapclient/client.rb', line 383 def put_attribute(auid, document, selector, attribute_name, attribute_value, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:put, application, document, selector + "/@#{attribute_name}", attribute_value, xml_namespaces, "application/xcap-att+xml", check_etag) # Reset local plain document and ETag as we have modified it. document.plain = nil document.etag = nil return true end |
#put_node(auid, document, selector, selector_body, xml_namespaces = nil, check_etag = true) ⇒ Object
Create/replace a node in the document stored in the server.
Example, creating/replacing the node with “id” = “sip:[email protected]”:
@xcapclient.put_node("pres-rules", nil,
'cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:[email protected]"]',
'<cp:one id="sip:[email protected]"/>',
{"cp"=>"urn:ietf:params:xml:ns:common-policy"})
If success:
-
The method returns true.
-
Local plain document and ETag are deleted (as the document has changed).
302 303 304 305 306 307 308 309 310 311 312 313 |
# File 'lib/xcapclient/client.rb', line 302 def put_node(auid, document, selector, selector_body, xml_namespaces=nil, check_etag=true) application, document = get_app_doc(auid, document) response = send_request(:put, application, document, selector, selector_body, xml_namespaces, "application/xcap-el+xml", check_etag) # Reset local plain document and ETag as we have modified it. document.plain = nil document.etag = nil return true end |