### Home Classes Methods

### In Files

- lib/xmpp4r/client.rb

### Parent

Connection

### Methods

- ::new
- #auth
- #auth_anonymous
- #auth_anonymous_sasl
- #auth_nonsasl
- #auth_sasl
- #bind
- #close
- #connect
- #password=
- #register
- #register_info
- #remove_registration
- #restart
- #start
- #supports_anonymous?
- #unbind

### Files

- CHANGELOG
- COPYING
- LICENSE
- README.rdoc
- README_ruby19.txt

### Class/Module Index

Quicksearch

- Jabber
- Jabber::ArgumentError
- Jabber::Bytestreams
- Jabber::Bytestreams::IBB
- Jabber::Bytestreams::IBBInitiator
- Jabber::Bytestreams::IBBQueueItem
- Jabber::Bytestreams::IBBTarget
- Jabber::Bytestreams::IqQueryBytestreams
- Jabber::Bytestreams::IqSi
- Jabber::Bytestreams::IqSiFile
- Jabber::Bytestreams::IqSiFileRange
- Jabber::Bytestreams::SOCKS5Bytestreams
- Jabber::Bytestreams::SOCKS5BytestreamsInitiator
- Jabber::Bytestreams::SOCKS5BytestreamsPeer
- Jabber::Bytestreams::SOCKS5BytestreamsServer
- Jabber::Bytestreams::SOCKS5BytestreamsServerStreamHost
- Jabber::Bytestreams::SOCKS5BytestreamsTarget
- Jabber::Bytestreams::SOCKS5Socket
- Jabber::Bytestreams::StreamHost
- Jabber::Bytestreams::StreamHostUsed
- Jabber::Callback
- Jabber::CallbackList
- Jabber::Caps
- Jabber::Caps::C
- Jabber::Caps::Helper
- Jabber::Client
- Jabber::ClientAuthenticationFailure
- Jabber::Command
- Jabber::Command::IqCommand
- Jabber::Command::Responder
- Jabber::Component
- Jabber::ComponentAuthenticationFailure
- Jabber::Connection
- Jabber::Connection::SSLSocketUTF8
- Jabber::Dataforms
- Jabber::Dataforms::XData
- Jabber::Dataforms::XDataField
- Jabber::Dataforms::XDataInstructions
- Jabber::Dataforms::XDataReported
- Jabber::Dataforms::XDataTitle
- Jabber::Delay
- Jabber::Delay::XDelay
- Jabber::Discovery
- Jabber::Discovery::Feature
- Jabber::Discovery::Helper
- Jabber::Discovery::Identity
- Jabber::Discovery::IqQueryDiscoInfo
- Jabber::Discovery::IqQueryDiscoItems
- Jabber::Discovery::Item
- Jabber::Discovery::Responder
- Jabber::EntityTime
- Jabber::EntityTime::IqTime
- Jabber::EntityTime::Responder
- Jabber::ErrorResponse
- Jabber::FeatureNegotiation
- Jabber::FeatureNegotiation::IqFeature
- Jabber::FileTransfer
- Jabber::FileTransfer::FileSource
- Jabber::FileTransfer::Helper
- Jabber::FileTransfer::TransferSource
- Jabber::Framework
- Jabber::Framework::Base
- Jabber::Framework::Bot
- Jabber::HTTPBinding
- Jabber::HTTPBinding::Client
- Jabber::IdGenerator
- Jabber::InvalidChatState
- Jabber::Iq
- Jabber::IqQuery
- Jabber::JID
- Jabber::JabberError
- Jabber::LastActivity
- Jabber::LastActivity::Helper
- Jabber::LastActivity::IqQueryLastActivity
- Jabber::MUC
- Jabber::MUC::IqQueryMUCAdmin
- Jabber::MUC::IqQueryMUCAdminItem
- Jabber::MUC::IqQueryMUCOwner
- Jabber::MUC::MUCBrowser
- Jabber::MUC::MUCClient
- Jabber::MUC::SimpleMUCClient
- Jabber::MUC::UserItem
- Jabber::MUC::XMUC
- Jabber::MUC::XMUCUser
- Jabber::MUC::XMUCUserInvite
- Jabber::MUC::XMUCUserItem
- Jabber::Message
- Jabber::NoNameXmlnsRegistered
- Jabber::NotConnected
- Jabber::Observable
- Jabber::Observable::Contact
- Jabber::Observable::PubSub
- Jabber::Observable::PubSub::AlreadySet
- Jabber::Observable::PubSub::NoService
- Jabber::Observable::Subscriptions
- Jabber::Presence
- Jabber::PubSub
- Jabber::PubSub::Configuration
- Jabber::PubSub::Event
- Jabber::PubSub::EventItem
- Jabber::PubSub::EventItems
- Jabber::PubSub::IqPubSub
- Jabber::PubSub::IqPubSubOwner
- Jabber::PubSub::Item
- Jabber::PubSub::Items
- Jabber::PubSub::NodeBrowser
- Jabber::PubSub::NodeConfig
- Jabber::PubSub::NodeHelper
- Jabber::PubSub::OAuthPubSubStreamHelper
- Jabber::PubSub::OAuthServiceHelper
- Jabber::PubSub::OwnerNodeConfig
- Jabber::PubSub::Publish
- Jabber::PubSub::Retract
- Jabber::PubSub::ServiceHelper
- Jabber::PubSub::Subscription
- Jabber::PubSub::SubscriptionConfig
- Jabber::PubSub::Unsubscribe
- Jabber::RPC
- Jabber::RPC::Client
- Jabber::RPC::IqQueryRPC
- Jabber::RPC::Server
- Jabber::Reliable
- Jabber::Reliable::Connection
- Jabber::Reliable::Listener
- Jabber::Roster
- Jabber::Roster::Helper
- Jabber::Roster::Helper::RosterItem
- Jabber::Roster::IqQueryRoster
- Jabber::Roster::RosterItem
- Jabber::Roster::RosterX
- Jabber::Roster::RosterXItem
- Jabber::Roster::XRoster
- Jabber::Roster::XRosterItem
- Jabber::SASL
- Jabber::SASL::Anonymous
- Jabber::SASL::Base
- Jabber::SASL::DigestMD5
- Jabber::SASL::Plain
- Jabber::SOCKS5Error
- Jabber::Semaphore
- Jabber::ServerDisconnected
- Jabber::Stream
- Jabber::Stream::ThreadBlock
- Jabber::StreamParser
- Jabber::Test
- Jabber::Test::ListenerMocker
- Jabber::UserLocation
- Jabber::UserLocation::Helper
- Jabber::UserLocation::Location
- Jabber::UserTune
- Jabber::UserTune::Helper
- Jabber::UserTune::Tune
- Jabber::Vcard
- Jabber::Vcard::Helper
- Jabber::Vcard::IqVcard
- Jabber::Version
- Jabber::Version::IqQueryVersion
- Jabber::Version::Responder
- Jabber::Version::SimpleResponder
- Jabber::X
- Jabber::XHTML
- Jabber::XHTML::Body
- Jabber::XHTML::HTML
- Jabber::XMPPElement
- Jabber::XMPPStanza
- Jabber::XParent
- REXML
- REXML::Element
- REXML::IOSource
- XMLRPC
- XMLRPC::Create
- Base64
- ObservableThing
- QObserver
- ThreadStore

No matching classes.

# Jabber::Client

The client class provides everything needed to build a basic XMPP Client.

If you want your connection to survive disconnects and timeouts, catch exception in Stream#on_exception and re-call Client#connect and Client#auth. Don't forget to re-send initial Presence and everything else you need to setup your session.

### Attributes

jid[R]

The client's JID

### Public Class Methods

new(jid) click to toggle source

Create a new Client.

Remember to always put a resource in your JID unless the server can do SASL.

    # File lib/xmpp4r/client.rb, line 27
    def initialize(jid)
      super()
      @jid = (jid.kind_of?(JID) ? jid : JID.new(jid.to_s))
      @authenticated = false
    end

### Public Instance Methods

auth(password) click to toggle source

Authenticate with the server

Throws ClientAuthenticationFailure

Authentication mechanisms are used in the following preference:

- SASL DIGEST-MD5

- SASL PLAIN

- Non-SASL digest

password

String

    # File lib/xmpp4r/client.rb, line 108
    def auth(password)
      begin
        if @stream_mechanisms.include? 'DIGEST-MD5'
          auth_sasl SASL.new(self, 'DIGEST-MD5'), password
        elsif @stream_mechanisms.include? 'PLAIN'
          auth_sasl SASL.new(self, 'PLAIN'), password
        else
          auth_nonsasl(password)
        end
        @authenticated = true
      rescue
        Jabber::debuglog("#{$!.class}: #{$!}\n#{$!.backtrace.join("\n")}")
        raise ClientAuthenticationFailure.new, $!.to_s
      end
    end

auth_anonymous() click to toggle source

See Client#auth_anonymous_sasl

    # File lib/xmpp4r/client.rb, line 210
    def auth_anonymous
      auth_anonymous_sasl
    end

auth_anonymous_sasl() click to toggle source

Shortcut for anonymous connection to server

Throws ClientAuthenticationFailure

    # File lib/xmpp4r/client.rb, line 219
    def auth_anonymous_sasl
      if self.supports_anonymous?
        begin
          auth_sasl SASL.new(self, 'ANONYMOUS'), ""
        rescue
          Jabber::debuglog("#{$!.class}: #{$!}\n#{$!.backtrace.join("\n")}")
          raise ClientAuthenticationFailure, $!.to_s
        end
      else
        raise ClientAuthenticationFailure, 'Anonymous authentication unsupported'
      end
    end

auth_nonsasl(password, digest=true) click to toggle source

Send auth with given password and wait for result (non-SASL)

Throws ServerError

password

String

  the password

digest

Boolean

  use Digest authentication

    # File lib/xmpp4r/client.rb, line 248
    def auth_nonsasl(password, digest=true)
      authset = nil
      if digest
        authset = Iq.new_authset_digest(@jid, @streamid.to_s, password)
      else
        authset = Iq.new_authset(@jid, password)
      end
      send_with_id(authset)
      $>.flush

      true
    end

auth_sasl(sasl, password) click to toggle source

Use a SASL authentication mechanism and bind to a resource

If there was no resource given in the jid, the jid/resource generated by the server will be accepted.

This method should not be used directly. Instead, Client#auth may look for the best mechanism suitable.

sasl | Descendant of [Jabber::SASL::Base]

password

String

    # File lib/xmpp4r/client.rb, line 175
    def auth_sasl(sasl, password)
      sasl.auth(password)

      # Restart stream after SASL auth
      restart
      # And wait for features - again
      @features_sem.wait

      # Resource binding (RFC3920 - 7)
      if @stream_features.has_key? 'bind'
        Jabber::debuglog("**********Handling bind")
        @jid = bind(@jid.resource)
      end

      # Session starting
      if @stream_features.has_key? 'session'
        iq = Iq.new(:set)
        session = iq.add REXML::Element.new('session')
        session.add_namespace @stream_features['session']

        semaphore = Semaphore.new
        send_with_id(iq) {
          semaphore.run
        }
        semaphore.wait
      end
    end

bind(desired_resource=nil) click to toggle source

Resource binding (RFC3920bis-06 - section 8.)

XMPP allows to bind to multiple resources

    # File lib/xmpp4r/client.rb, line 128
    def bind(desired_resource=nil)
      iq = Iq.new(:set)
      bind = iq.add REXML::Element.new('bind')
      bind.add_namespace @stream_features['bind']
      if desired_resource
        resource = bind.add REXML::Element.new('resource')
        resource.text = desired_resource
      end

      jid = nil
      semaphore = Semaphore.new
      send_with_id(iq) do |reply|
        reply_bind = reply.first_element('bind')
        if reply_bind
          reported_jid = reply_bind.first_element('jid')
          if reported_jid and reported_jid.text
            jid = JID.new(reported_jid.text)
          end
        end
        semaphore.run
      end
      semaphore.wait
      jid
    end

close() click to toggle source

Close the connection, sends `</stream:stream>` tag first

    # File lib/xmpp4r/client.rb, line 78
    def close
      if @status == CONNECTED
        send("</stream:stream>")
      end
      super
    end

connect(host = nil, port = 5222) click to toggle source

connect to the server (chaining-friendly)

If you omit the optional host argument SRV records for your jid will be resolved. If none works, fallback is connecting to the domain part of the jid.

host

String

  Optional c2s host, will be extracted from jid if nil

port

Fixnum

  The server port (default: 5222)

return | self

    # File lib/xmpp4r/client.rb, line 43
    def connect(host = nil, port = 5222)
      if host.nil?
        begin
          srv = []
          Resolv::DNS.open { |dns|
            # If ruby version is too old and SRV is unknown, this will raise a NameError
            # which is caught below
            Jabber::debuglog("RESOLVING:\n_xmpp-client._tcp.#{@jid.domain} (SRV)")
            srv = dns.getresources("_xmpp-client._tcp.#{@jid.domain}", Resolv::DNS::Resource::IN::SRV)
          }
          # Sort SRV records: lowest priority first, highest weight first
          srv.sort! { |a,b| (a.priority != b.priority) ? (a.priority <=> b.priority) : (b.weight <=> a.weight) }

          srv.each { |record|
            begin
              connect(record.target.to_s, record.port)
              # Success
              return self
            rescue SocketError, Errno::ECONNREFUSED
              # Try next SRV record
            end
          }
        rescue NameError
          Jabber::debuglog "Resolv::DNS does not support SRV records. Please upgrade to ruby-1.8.3 or later!"
        end
        # Fallback to normal connect method
      end

      super(host.nil? ? jid.domain : host, port)
      self
    end

password=(new_password) click to toggle source

Change the client's password

Threading is suggested, as this code waits for an answer.

Raises an exception upon error response (ServerError from Stream#send_with_id).

new_password

String

  New password

    # File lib/xmpp4r/client.rb, line 348
    def password=(new_password)
      iq = Iq.new_query(:set, @jid.domain)
      iq.query.add_namespace('jabber:iq:register')
      iq.query.add(REXML::Element.new('username')).text = @jid.node
      iq.query.add(REXML::Element.new('password')).text = new_password

      err = nil
      send_with_id(iq)
    end

register(password, fields={}) click to toggle source

Register a new user account (may be used instead of Client#auth)

This method may raise ServerError if the registration was not successful.

password | String
fields | {String=>String} additional registration information

XEP-0077 Defines the following fields for registration information: www.xmpp.org/extensions/xep-0077.html

'username' => 'Account name associated with the user' 'nick' => 'Familiar name of the user' 'password' => 'Password or secret for the user' 'name' => 'Full name of the user' 'first' => 'First name or given name of the user' 'last' => 'Last name, surname, or family name of the user' 'email' => 'Email address of the user' 'address' => 'Street portion of a physical or mailing address' 'city' => 'Locality portion of a physical or mailing address' 'state' => 'Region portion of a physical or mailing address' 'zip' => 'Postal code portion of a physical or mailing address' 'phone' => 'Telephone number of the user' 'url' => 'URL to web page describing the user' 'date' => 'Some date (e.g., birth date, hire date, sign-up date)'

    # File lib/xmpp4r/client.rb, line 317
    def register(password, fields={})
      reg = Iq.new_register(jid.node, password)
      reg.to = jid.domain
      fields.each { |name,value|
        reg.query.add(REXML::Element.new(name)).text = value
      }

      send_with_id(reg)
    end

register_info() click to toggle source

Get instructions and available fields for registration

return

instructions, fields

  Where instructions is a String and fields is an Array of Strings

    # File lib/xmpp4r/client.rb, line 264
    def register_info
      instructions = nil
      fields = []

      reg = Iq.new_registerget
      reg.to = jid.domain
      send_with_id(reg) do |answer|
        if answer.query
          answer.query.each_element { |e|
            if e.namespace == 'jabber:iq:register'
              if e.name == 'instructions'
                instructions = e.text.strip
              else
                fields << e.name
              end
            end
          }
        end

        true
      end

      [instructions, fields]
    end

remove_registration() click to toggle source

Remove the registration of a user account

WARNING: this deletes your roster and everything else stored on the server!

    # File lib/xmpp4r/client.rb, line 332
    def remove_registration
      reg = Iq.new_register
      reg.to = jid.domain
      reg.query.add(REXML::Element.new('remove'))
      send_with_id(reg)
    end

restart() click to toggle source

    # File lib/xmpp4r/client.rb, line 203
    def restart
      stop
      start
    end

start() click to toggle source

Start the stream-parser and send the client-specific stream opening element

    # File lib/xmpp4r/client.rb, line 87
    def start
      super
      send(generate_stream_start(@jid.domain)) { |e|
        if e.name == 'stream'
          true
        else
          false
        end
      }
    end

supports_anonymous?() click to toggle source

Reports whether or not anonymous authentication is reported by the client.

Returns true or false

    # File lib/xmpp4r/client.rb, line 237
    def supports_anonymous?
      @stream_mechanisms.include? 'ANONYMOUS'
    end

unbind(desired_resource) click to toggle source

Resource unbinding (RFC3920bis-06 - section 8.6.3.)

    # File lib/xmpp4r/client.rb, line 155
    def unbind(desired_resource)
      iq = Iq.new(:set)
      unbind = iq.add REXML::Element.new('unbind')
      unbind.add_namespace @stream_features['unbind']
      resource = unbind.add REXML::Element.new('resource')
      resource.text = desired_resource

      send_with_id(iq)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.