Method: XCAPClient::Client#initialize

Defined in:
lib/xcapclient/client.rb

#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.

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"
  },
  "rls-services" => {
    :xmlns => "urn:ietf:params:xml:ns:rls-services",
    :mime_type => "application/rls-services+xml"
  }
}

@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.

Raises:



100
101
102
103
104
105
106
107
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
 
# File 'lib/xcapclient/client.rb', line 100

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 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"
  })
  @applications["xcap-caps"].add_document("index", :global)

  # Add custom applications.
  applications.each do |auid, data|
    @applications[auid] = Application.new(auid, data)
  end

  @applications.freeze

end