Class Jabber::Session
In: lib/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
:connection  [R] 

The Jabber::Protocol::Connection instance

:host  [R] 

The host this session is connected to

:iqHandlers  [RW] 

The iq handlers for this session

:jid  [R] 

The Jabber::JID of the current session

:password  [RW] 

The password to use for authenticating this session

:port  [R] 

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

:resource  [RW] 

The resource id for this session

:roster  [R] 

The Jabber::Roster instance

:session_id  [R] 

The session id sent from the Jabber service upon connection

:username  [RW] 

The username to use for authenticating this session

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

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)

Account registration method

bind_digest(jid, password, port=5222)

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)

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)

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

id()

Counter for message IDs

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

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?()

Is this an authenticated session?

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

Sends the initial presence message to the Jabber service

announce_extended_away(status=nil)

Sends an extended away presence message

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

Sends a free for chat presence message

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

Sends a 'normal' presence message

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

Sends an away from computer presence message

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

Sends a do not disturb presence message

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

Sets the handler for subscription requests, notifications, etc.

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

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

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

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)

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)

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

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

add_message_listener(&block)

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)

Deletes a message listener

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

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

close()

Same as _release

request_roster()

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

register_iq_filter()

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

register_roster_filter()

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

add_roster_listener(&block)

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)

Deletes the roster listener

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

Notifies message listeners of the received message

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