Public Member Functions | Protected Attributes

wosh::bundles::JabberGlooxBundle Class Reference
[WOSH Bundles]

Instant Messaging Communicator, Jabber/XMPP compatible (such as GTalk), based on gloox library. More...

#include <H:/WOSH/win32_vc2010/src/bundles/JabberGloox/JabberGlooxBundle.h>

List of all members.

Public Member Functions

 JabberGlooxBundle ()
 Empty constructor, init bundle and vars, Properties and Methods. Allocate the internal JabberGlooxImpl.
virtual ~JabberGlooxBundle ()
 Empty destructor, may (synch) stop bundle and internal threads when still running.
virtual void busMessage (const Message &message, const Bus *source)
 Method raised by the Bus when it processes a new message. Implementations will probably analyze the message and perform actions.
JabberGloox Interface
const std::string & getServerAddress () const
 Get server address.
int getServerPort () const
 Get server port.
const std::string & getAccountName () const
 Get account username.
int getPriority () const
 Get priority.
wosh::security::AuthenticationProvider3rdParty & getCredentialsIO ()
bool setServer (const std::string &address, int port)
 Set server address and port. Provided for convenience.
bool setAccount (const std::string &username, const std::string &password)
 Set server account name and password. Provided for convenience.
bool setPriority (int value)
 Set priority of the account (login)
WRESULT doContactsSynch (bool add, bool remove)
Communicator Interface
bool isUserReachable (const std::string &username) const
 Check if user is online now (logged in current server)
bool isUserRegistered (const std::string &username) const
 Check if user is registered to current server.
int64 getUserLastSeen (const std::string &username) const
 Get the timestamp of last(seen) online-status of given user.
WRESULT sendMessageToUser (const std::string &userWosh, const std::string &message)
 Send a text message to given (wosh) username.
WRESULT sendMessageTo (const std::string &userID, const std::string &message)
 Send a text message to given account name [example: asd123@gmail.com].
WRESULT notify (const Notification *notification, const Message *notification_message=NULL)
 Send a Notification translated into a text message.
IJabberGlooxListener Events
void jabbbot_Connection (int state, const char *description, JabberGlooxImpl *bot)
 Raised when a connection state changes.
void jabbbot_UserStatus (const std::string &username, int status, const std::string &status_message, JabberGlooxImpl *bot)
 Raised when a contact change its presence status (as going online/offline) (also raised periodically)
void jabbbot_Message (const std::string &username, const std::string &message, JabberGlooxImpl *bot)
 Raised when a new message is sent to bot's account (outselves)
short jabbbot_SubscriptionChanged (const std::string &username, int status, JabberGlooxImpl *bot)
 Raised when subscription of an user is being updated.
ISessionProxyListener Events
void session_registration (short reg_unreg, wosh::communication::SessionProxy *session)
void session_timed_out (wosh::communication::SessionProxy *session)
WRESULT session_print_message (const char *message, unsigned int size, wosh::communication::SessionProxy *session)
WRESULT session_su (const std::string &username, SecurityAuthenticationSecret **secret, SecurityAuthenticationProvider **cprovider, wosh::communication::SessionProxy *session)

Protected Member Functions

Internal methods
ContactInfocheckCreateAccount_ (const std::string &accountname)
 Create an account (in the local list)
WRESULT setupUserSession_ (ContactInfo *info)
 Create a SessionProxy object for an account.
bool parseInternalCommand (const std::string &message, ContactInfo *info)
 Evaluate if message is an internal command (for the service itself) Internal commands always starts with "%" and are upcase.
std::string getAccountNameFromUsername (const std::string &username) const
 Retrieve account name from username.
std::string getUsernameFromAccountName (const std::string &accountname) const
 Retrieve username from account name.

Protected Attributes

JabberGlooxImpljabbWorker
 real implementation (basled on libgloox)
tStrContactInfoMap contacts
 contacts (friends) list: { name,info }
BusConnector BusSecurity
 connector to Security bus (posting only)
wosh::security::AuthenticationProvider3rdParty CredentialsIO
 user-authentication provider of incoming messages

Detailed Description

Instant Messaging Communicator, Jabber/XMPP compatible (such as GTalk), based on gloox library.

JabberGlooxBundle acts as adapter between WOSH and Jabber/XMPP network (protocol), compatible with GTalk and plenty of open servers.

But the JabberGlooxBundle is also a Communicator Service, so it implements some standard methods/functionalities and follow a set of specification in order to cooperate with Communication Manager.

In short, it allows WOSH system and its users to reach you with notifications (messages) and it masquerades a wosh::Session (SessionProxy) to local host (and whole system) as a chat. Communication is an hot topic in WOSH, to understand the architecture and global flows, you should read Sessions and WOSH Communication Framework docs.

This bundle is compatible with POSIX and Windows (desktop/server) systems.

Requirements:
Implementation is based on gloox library (multi-platform, open source, C++). Minimum required version is 0.9.x (available since Debian Lenny 5.0), last supported version is 1.0.x (available on gloox website).

JabberGlooxBundle has been tested on:

and using Google Talk network (service).

There are some changes (0.9 => 1.0) which broken backward-compatibility, so two different wrappers have been implemented, they both share the base abstract class JabberGlooxImpl: JabberGloox10 (gloox-1.x) and JabberGloox09 (gloox-0.9.x).

As said, on Linux, libgloox is available in Debian-based repositories, you may install it executing:

alex@linbox:/home/alex# sudo apt-get install libgloox-dev

At the time of writing, Debian Lenny provides gloox version 0.9.9.5-1.

On Windows systems, you may download gloox library and build locally using Microsoft Visual Studio. It will generate gloox.lib (to be placed in /lib/3rdparty) and the related DLL (to be placed in application's binary folder). Binary distribution of WOSH ships with a gloox library built.

Bot Configuration:
In order to have the jabber client connected to XMPP server (such as GTalk-service) you need to setup address and account information. Most important Properties are:
  • ServerAddress - the address (IP or hostname) of the XMPP server, such as talk.google.com
  • ServerPort - the port of the XMPP service, standard port is 5222
  • ServerAuthority - the name of the network authority, required to map external account to WOSH account
  • UserName - the username of the (bot) account (on GTalk it looks like "USER-NAME@gmail.com" )
  • UserPassword - the password of the account

A sample configuration is available: 380_JabberGloox.conf

Once the above properties have been configured properly, the service is able to connect, send and receive message from friends.

Friends Configuration:
Since the service is a bridge between WOSH and another network/authority, WOSH system has to identify and authorize users (for posing notification and opening sessions both). User identification/authorization is provided by wosh::security::AuthenticationProvider3rdParty, which will also map users' secrets to jabber-network provided identification. WOSH authentication architecture is explained in core security page. In fact, the literal value of ServerAuthority doesn't matter by itself, but its used as primary key when mapping WOSH accounts against Jabber-network account. It comes to be very easy to map a WOSH user to an external (3rdparty) trust authority:
    <wosh::User name="your-own-account-of-wosh" >
      <security>
        <secrets>
          <wosh::security::AuthenticationSecret3rdParty>
            <authority>google.com</authority>
            <username>your-own-account-of@gmail.com</username>
          </wosh::security::AuthenticationSecret3rdParty>
        </secrets>
      </security>
    </wosh::User>
This architecture also allows to have multiple JabberGlooxBundle instances connected to different networks, but still able to map different accounts to the right user. Note that the WOSH Security architecture will be able to access to information about external source (account) within associated SecurityToken.

JabberGlooxBundle supports also session masquerading when target user is 'wosh', else messages are interpreted as instant messages (textual notifications) to target user. Default user is 'wosh'. In short, the chat with the bot may work as a local shell to the WOSH kernel.

Internal commands
JabberGlooxBundle supports some internal commands (not parsed as messages) for quick (re)configuration and debugging. Internal commands always starts with "%" and are uppercase (sensitive).
  • HELP - prints a minimal help screen about these commands
  • INFO - prints information about yourself and current settings
  • TARGET - get/set the target user ('wosh' by default)
  • LANG - get/set your current language
  • PROTO - get/set the protocol used (SHELL by default)
Note:
You should create (or keep) a separate account for this service (don't use your personal account! it's non-sense), for example I named it something like "my-home@gmail.com". This account will look just like another friend in your contact list, acting as proxy and letting you 'talk' with WOSH system. While you register the account, have you both added each other.
Google Talk service may block the bot-account sometimes, then you may need to login manually through a web browser (while or before starting the service).
In very short, outgoing message Flow
Message (chat) posted by WOSH (the bot) to a jabber-user may come from two sources:
  • Notification: sender and recipient users are WOSH users. Even the WOSH system itself may notify something to users.
  • Session: JabberGlooxBundle support session masquerading, offering to the user a WOSH shell as a chat room.

When dealing with notifications, recipient user must be mapped to the jabber account (example: alex => "alex-rules@gmail.com"). This problem is solved by wosh::security::AuthenticationProvider3rdParty component:

inline_mscgraph_10

On the other side, session's output is easily redirected to the right user since session instance is directly associated to contacts (live accounts table). Note that Session is dynamically created on first incoming message (when recipent='wosh', default).

inline_mscgraph_11
In very short, incoming message Flow
The incoming messages (from XMPP network, the user to the bot) must be redirected to some WOSH user as wosh::Notification:
inline_mscgraph_12
or it may be interpreted as input of the (sender) associated wosh::communication::SessionProxy
inline_mscgraph_13
See also:
Refer to official gloox homepage: http://camaya.net/gloox/
WOSH Bundles, wosh::interfaces::communication::JabberGloox, wosh::interfaces::communication::Communicator
wosh::SessionManager, wosh::bundles::CommunicationManager
Version:
0.8.558
Id:
JabberGlooxBundle.h 3775 2011-01-01 16:38:17Z alex
Date:
Released stable on 2010-09-22
Author:
Alessandro Polo

Definition at line 256 of file JabberGlooxBundle.h.


Constructor & Destructor Documentation

wosh::bundles::JabberGlooxBundle::JabberGlooxBundle (  )

Empty constructor, init bundle and vars, Properties and Methods. Allocate the internal JabberGlooxImpl.

Definition at line 68 of file JabberGlooxBundle.cpp.

References _METHOD_Retrieve, and wosh::LOG_DEBUG.

wosh::bundles::JabberGlooxBundle::~JabberGlooxBundle (  ) [virtual]

Empty destructor, may (synch) stop bundle and internal threads when still running.

Definition at line 152 of file JabberGlooxBundle.cpp.

References wosh::LOG_DEBUG, wosh::LOG_INFO, wosh::LOG_VERBOSE, and wosh::LOG_WARNING.


Member Function Documentation

void wosh::bundles::JabberGlooxBundle::busMessage ( const Message message,
const Bus source 
) [virtual]

Method raised by the Bus when it processes a new message. Implementations will probably analyze the message and perform actions.

Parameters:
[in]messagethe incoming message
[in]sourcethe source Bus of the incoming message
Warning:
The current thread is own and managed by the caller Bus. Heavy, dangerous or time expensive operations should be executed asynchronously and not inline!

Reimplemented from wosh::BundleGeneric.

Definition at line 240 of file JabberGlooxBundle.cpp.

References wosh::MessageContent::asNotification(), BusCore, wosh::Message::getContent(), wosh::Message::getDestination(), wosh::Message::isEmpty(), wosh::MessageContent::isNotification(), wosh::BusConnector::postMessage(), and wosh::Message::replyTo().

ContactInfo * wosh::bundles::JabberGlooxBundle::checkCreateAccount_ ( const std::string &  accountname ) [protected]

Create an account (in the local list)

Parameters:
accountname[in] jabber-accont name
Returns:
pointer to the new Contact

Todo:
EVAL USER/SOURCE vs. SECURITY RULES here

Definition at line 315 of file JabberGlooxBundle.cpp.

References wosh::LOG_DEBUG, and wosh::LOG_INFO.

const std::string& wosh::bundles::JabberGlooxBundle::getAccountName (  ) const [inline, virtual]

Get account username.

Returns:
account username

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 291 of file JabberGlooxBundle.h.

std::string wosh::bundles::JabberGlooxBundle::getAccountNameFromUsername ( const std::string &  username ) const [protected]

Retrieve account name from username.

Parameters:
username[in] wosh-username to lookup
Returns:
account name associated with wosh-username
See also:
UserManager::getUserProperty()

Definition at line 788 of file JabberGlooxBundle.cpp.

References wosh::LOG_WARNING.

int wosh::bundles::JabberGlooxBundle::getPriority (  ) const [inline, virtual]

Get priority.

Returns:
priority

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 292 of file JabberGlooxBundle.h.

const std::string& wosh::bundles::JabberGlooxBundle::getServerAddress (  ) const [inline, virtual]

Get server address.

Returns:
address as string

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 289 of file JabberGlooxBundle.h.

int wosh::bundles::JabberGlooxBundle::getServerPort (  ) const [inline, virtual]

Get server port.

Returns:
server port

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 290 of file JabberGlooxBundle.h.

int64 wosh::bundles::JabberGlooxBundle::getUserLastSeen ( const std::string &  username ) const [virtual]

Get the timestamp of last(seen) online-status of given user.

Parameters:
username[in] wosh-username to lookup
Returns:
epoc timestamp if user is still online, negative epoch if user is actually offline; 0 means not available

Implements wosh::interfaces::communication::Communicator.

Definition at line 820 of file JabberGlooxBundle.cpp.

std::string wosh::bundles::JabberGlooxBundle::getUsernameFromAccountName ( const std::string &  accountname ) const [protected]

Retrieve username from account name.

Parameters:
accountname[in] account username to lookup
Returns:
wosh-username associated with account name
See also:
UserManager::findUserByProperty()

Definition at line 773 of file JabberGlooxBundle.cpp.

References wosh::LOG_WARNING.

bool wosh::bundles::JabberGlooxBundle::isUserReachable ( const std::string &  username ) const [virtual]

Check if user is online now (logged in current server)

Parameters:
username[in] wosh-username to lookup
Returns:
true if user is online; false else

Implements wosh::interfaces::communication::Communicator.

Definition at line 802 of file JabberGlooxBundle.cpp.

bool wosh::bundles::JabberGlooxBundle::isUserRegistered ( const std::string &  username ) const [virtual]

Check if user is registered to current server.

Parameters:
username[in] wosh-username to lookup
Returns:
true if user is in friends' list

Implements wosh::interfaces::communication::Communicator.

Definition at line 813 of file JabberGlooxBundle.cpp.

void wosh::bundles::JabberGlooxBundle::jabbbot_Connection ( int  state,
const char *  description,
JabberGlooxImpl source 
) [virtual]

Raised when a connection state changes.

Parameters:
state[in] state of the connection (see JabberGlooxImpl::CONNECTION_STATE)
description[in] description of the event (may be NULL)
source[in] instance of JabberGlooxImpl which raised the callback

Implements IJabberGlooxListener.

Definition at line 673 of file JabberGlooxBundle.cpp.

References JabberGlooxImpl::STATE_CONNECTED, JabberGlooxImpl::STATE_DISCONNECTED, and JabberGlooxImpl::STATE_FAILURE.

void wosh::bundles::JabberGlooxBundle::jabbbot_Message ( const std::string &  username,
const std::string &  message,
JabberGlooxImpl source 
) [virtual]

Raised when a new message is sent to bot's account (outselves)

Parameters:
username[in] username who sent the message
message[in] message sent by the user
source[in] instance of JabberGlooxImpl which raised the callback

Implements IJabberGlooxListener.

Definition at line 507 of file JabberGlooxBundle.cpp.

References BusCore, wosh::LOG_DEBUG, wosh::LOG_VERBOSE, wosh::LOG_WARNING, wosh::BusConnector::postMessage(), wosh::Message::setDestinationBroadcast(), and wosh::Message::setSource().

short wosh::bundles::JabberGlooxBundle::jabbbot_SubscriptionChanged ( const std::string &  username,
int  subscription_status,
JabberGlooxImpl source 
) [virtual]

Raised when subscription of an user is being updated.

Parameters:
username[in] target username
subscription_status[in] new subscription status
source[in] instance of JabberGlooxImpl which raised the callback
Returns:
return -1 to ignore the request; 1 to accept the subscription

Implements IJabberGlooxListener.

Definition at line 637 of file JabberGlooxBundle.cpp.

References wosh::LOG_INFO.

void wosh::bundles::JabberGlooxBundle::jabbbot_UserStatus ( const std::string &  username,
int  presence_status,
const std::string &  status_message,
JabberGlooxImpl source 
) [virtual]

Raised when a contact change its presence status (as going online/offline) (also raised periodically)

Parameters:
username[in] username of the contact who changed online status (such as online<->offline)
presence_status[in] new presence status of the user
status_message[in] status message of the user
source[in] instance of JabberGlooxImpl which raised the callback

Implements IJabberGlooxListener.

Definition at line 583 of file JabberGlooxBundle.cpp.

References wosh::LOG_CRITICAL, wosh::LOG_DEBUG, wosh::LOG_INFO, and wosh::LOG_WARNING.

WRESULT wosh::bundles::JabberGlooxBundle::notify ( const Notification notification,
const Message notification_message = NULL 
) [virtual]

Send a Notification translated into a text message.

Parameters:
notification[in] the Notification to communicate
notification_message[in] message containing the Notification to communicate
Returns:
WRET_ERR_PARAM if account wasn't found, WRET_OK when message was sent, WRET_ERR_INTERNAL else.

Todo:
validate notification (textual, !empty)

Implements wosh::interfaces::communication::Communicator.

Definition at line 854 of file JabberGlooxBundle.cpp.

References wosh::LOG_INFO, wosh::LOG_WARNING, WRET_ERR_PARAM, and WRET_OK.

bool wosh::bundles::JabberGlooxBundle::parseInternalCommand ( const std::string &  message,
ContactInfo info 
) [protected]

Evaluate if message is an internal command (for the service itself) Internal commands always starts with "%" and are upcase.

Available commands are:

  • HELP - prints a minimal help screen about these commands
  • INFO - prints information about yourself and current settings
  • TARGET - get/set the target user ('wosh' by default)
  • LANG - get/set your current language
  • PROTO - get/set the protocol used (SHELL by default)
Parameters:
message[in] message to be evaluated
info[in] the sender of the message
Returns:
true if the message is an internal command (so it won't be forwarded)

Definition at line 436 of file JabberGlooxBundle.cpp.

References wosh::LOG_CRITICAL, wosh::LOG_DEBUG, wosh::LOG_INFO, and wosh::LOG_WARNING.

WRESULT wosh::bundles::JabberGlooxBundle::sendMessageTo ( const std::string &  userID,
const std::string &  message 
) [virtual]

Send a text message to given account name [example: asd123@gmail.com].

Parameters:
userID[in] recipent of the message
message[in] message to be sent
Returns:
WRET_ERR_PARAM if account wasn't found, WRET_OK when message was sent, WRET_ERR_INTERNAL else.

Implements wosh::interfaces::communication::Communicator.

Definition at line 842 of file JabberGlooxBundle.cpp.

References WRET_ERR_INTERNAL, WRET_ERR_PARAM, and WRET_OK.

WRESULT wosh::bundles::JabberGlooxBundle::sendMessageToUser ( const std::string &  userWosh,
const std::string &  message 
) [virtual]

Send a text message to given (wosh) username.

Parameters:
userWosh[in] recipent of the message (as WOSH username)
message[in] message to be sent
Returns:
WRET_ERR_PARAM if account wasn't found, WRET_OK when message was sent, WRET_ERR_INTERNAL else.
See also:
getAccountNameFromUsername()

Implements wosh::interfaces::communication::Communicator.

Definition at line 831 of file JabberGlooxBundle.cpp.

References WRET_ERR_PARAM.

bool wosh::bundles::JabberGlooxBundle::setAccount ( const std::string &  username,
const std::string &  password 
) [inline, virtual]

Set server account name and password. Provided for convenience.

Parameters:
username[in] username used to log on the server
password[in] username used to log on the server
Returns:
false when internal thread is running, true else

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 297 of file JabberGlooxBundle.h.

bool wosh::bundles::JabberGlooxBundle::setPriority ( int  value ) [inline, virtual]

Set priority of the account (login)

Parameters:
value[in] true to set auto-presence
Returns:
false when internal thread is running, true else

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 298 of file JabberGlooxBundle.h.

bool wosh::bundles::JabberGlooxBundle::setServer ( const std::string &  address,
int  port 
) [inline, virtual]

Set server address and port. Provided for convenience.

Parameters:
address[in] address of the server
port[in] port of the server
Returns:
false when internal thread is running, true else

Implements wosh::interfaces::communication::JabberGloox.

Definition at line 296 of file JabberGlooxBundle.h.

WRESULT wosh::bundles::JabberGlooxBundle::setupUserSession_ ( ContactInfo info ) [protected]

Create a SessionProxy object for an account.

Parameters:
info[in] Contact instance
Returns:
WRET_OK on success
Note:
session is created ON FIRST USE (=first incoming message), moreover, the session si mapped and opened on session_registration callback.
See also:
session_registration()

Definition at line 351 of file JabberGlooxBundle.cpp.

References wosh::LOG_INFO, wosh::Session::setCreatorURI(), wosh::communication::SessionProxy::setListener(), WRET_ERR_INTERNAL, WRET_ERR_PARAM, and WRET_OK.


Member Data Documentation

connector to Security bus (posting only)

Definition at line 436 of file JabberGlooxBundle.h.

contacts (friends) list: { name,info }

Definition at line 435 of file JabberGlooxBundle.h.

wosh::security::AuthenticationProvider3rdParty wosh::bundles::JabberGlooxBundle::CredentialsIO [protected]

user-authentication provider of incoming messages

Definition at line 439 of file JabberGlooxBundle.h.

real implementation (basled on libgloox)

Definition at line 434 of file JabberGlooxBundle.h.


The documentation for this class was generated from the following files:

Generated on Tue Feb 8 2011 09:33:36 for WOSH system 0.8.888 [wolf] by Alessandro Polo, using DoxyGen 1.7.2 hosted by WOSH Framework