Class
Jabber::Session
In: jabber4r/session.rb
Parent: Object

The Jabber Session is the main class for dealing with a Jabber service.

Methods

add_message_listener, add_roster_listener, announce_away_from_computer, announce_do_not_disturb, announce_extended_away, announce_free_for_chat, announce_initial_presence, announce_normal, authenticate, bind, bind_digest, close, delete_message_listener, delete_roster_listener, enable_autosubscription, id, is_authenticated?, new, new_chat_message, new_group_chat_message, new_message, notify_message_listeners, on_session_failure, register, register_iq_filter, register_message_filter, register_presence_filter, register_roster_filter, release, request_roster, set_subscription_handler, subscribe,
Attributes

 [R]  :connection

The Jabber::Protocol::Connection instance

 [R]  :host

The host this session is connected to

 [RW]  :iqHandlers

The iq handlers for this session

 [R]  :jid

The Jabber::JID of the current session

 [RW]  :password

The password to use for authenticating this session

 [R]  :port

The port (defaults to 5222) that this session is connected to

 [RW]  :resource

The resource id for this session

 [R]  :roster

The Jabber::Roster instance

 [R]  :session_id

The session id sent from the Jabber service upon connection

 [RW]  :username

The username to use for authenticating this session

Public Class methods
bind(jid, password, port=5222, digest=false) src

Session creation factory that creates a session, logs in, requests the roster, registers message and presence filters and announces initial presence. Login is done via plaintext password authentication.

jid:[String | JID] The account information ("account@host/resouce")
password:[String] The account password
port:[Integer = 5222] The host port
digest:[Boolean = false] Use digest authentication?
return:[Jabber::Session] The new session
register(jid, password, email="", name="", port=5222) src

Account registration method

bind_digest(jid, password, port=5222) src

Session creation factory that creates a session, logs in, requests the roster, registers message and presence filters and announces initial presence. Login is done via digest (SHA) password authentication.

jid:[String | JID] The account information ("account@host/resouce")
password:[String] The account password
port:[Integer = 5222] The host port
return:[Jabber::Session] The new session
new(host, port=5222) src

Creates a new session connected to the supplied host and port. The method attempts to build a Jabber::Protocol::Connection object and send the open_stream XML message. It then blocks to recieve the coorisponding reply open_stream and sets the session_id from that xml element.

host:[String] The hostname of the Jabber service
port:[Integer=5222] The port of the Jabber service
raise:[RuntimeException] If connection fails
Public Instance methods
on_session_failure(&block) src

Set a handler for session exceptions that get caught in communicating with the Jabber server.

id() src

Counter for message IDs

return:[String] A unique message id for this session
authenticate(username, password, resource, digest=false) src

Authenticate (logs into) this session with the supplied credentials. The method blocks waiting for a reply to the login message. Sets the authenticated attribute based on result.

username:[String] The username to use for authentication
password:[String] The password to use for authentication
resource:[String] The resource ID for this session
digest:[Boolean=false] True to use digest authentication (not sending password in the clear)
return:[Boolean] Whether the authentication succeeded or failed
is_authenticated?() src

Is this an authenticated session?

return:[Boolean] True if the session is authenticated
announce_initial_presence() src

Sends the initial presence message to the Jabber service

announce_extended_away(status=nil) src

Sends an extended away presence message

status:[String] The status message
announce_free_for_chat(status=nil) src

Sends a free for chat presence message

status:[String] The status message
announce_normal(status=nil) src

Sends a 'normal' presence message

status:[String] The status message
announce_away_from_computer(status=nil) src

Sends an away from computer presence message

status:[String] The status message
announce_do_not_disturb(status=nil) src

Sends a do not disturb presence message

status:[String] The status message
set_subscription_handler(handler=nil, &block) src

Sets the handler for subscription requests, notifications, etc.

enable_autosubscription() src
subscribe(to, name="") src
register_presence_filter() src

Adds a filter to the Connection to manage tracking resources that come online/offline

new_message(to, type=Jabber::Protocol::Message::NORMAL) src

Creates a new message to the supplied JID of type NORMAL

to:[Jabber::JID] Who to send the message to
type:[String = Jabber::Protocol::Message::NORMAL] The type of message to send (see Jabber::Protocol::Message)
return:[Jabber::Protocol::Message] The new message
new_chat_message(to) src

Creates a new message addressed to the supplied JID of type CHAT

to:[JID] Who to send the message to
return:[Jabber::Protocol::Message] The new (chat) message
new_group_chat_message(to) src

Creates a new message addressed to the supplied JID of type GROUPCHAT

to:[JID] Who to send the message to
return:[Jabber::Protocol::Message] The new (group chat) message
register_message_filter() src

Adds a filter to the Connection to manage tracking messages to forward to registered message listeners.

add_message_listener(&block) src

Add a listener for new messages

Usage:id = session.add_message_listener do |message|

  puts message

end

&block [Block] The block to process a message

return:[String] The listener ID...used to remove the listener
delete_message_listener(lid) src

Deletes a message listener

id:[String] A messanger ID returned from add_message_listener
release() src

Releases the connection and resets the session. The Session instance is no longer usable after this method is called

close() src

Same as _release

request_roster() src

Requests the Roster for the (authenticated) account. This method blocks until a reply to the roster request is received.

register_iq_filter() src

Registers the roster filter with the Connection to forward IQ requests to the IQ listeners(they register by namespace)

register_roster_filter() src

Registers the roster filter with the Connection to forward roster changes to the roster listeners.

add_roster_listener(&block) src

Registers a listener for roster events

&block:[Block] The listener block to process roster changes
return:[String] A roster ID to use when removing this listener
delete_roster_listener(id) src

Deletes the roster listener

id:[String] A roster ID received from the add_roster_listener method
notify_message_listeners(message) src

Notifies message listeners of the received message

message:[Jabber::Protocol::Message] The received message