Class: Jabber::Session

Class
Jabber::Session

In:	jabber4r/session.rb
Parent:	Object

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

Methods

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