gloox  1.0.1
Public Member Functions | List of all members
Manager Class Reference

#include <linklocalmanager.h>

Public Member Functions

 Manager (const std::string &user, ConnectionHandler *connHandler, const LogSink &logInstance)
virtual ~Manager ()
void addTXTData (const std::string &key, const std::string &value)
void removeTXTData (const std::string &key)
void registerService ()
void deregisterService ()
void setUser (const std::string &user)
void setHost (const std::string &host)
void setDomain (const std::string &domain)
void setPort (const int port)
void setInterface (unsigned iface)
bool startBrowsing ()
void stopBrowsing ()
int socket () const
void recv (int timeout)
void registerLinkLocalHandler (Handler *handler)

Detailed Description

This is a manager for server-less messaging (XEP-0174).

Enable compilation of this code with the --enable-mdns switch to configure, or add #define HAVE_MDNS to your platform's config.h. dns_sd.h, libdns_sd.so, as well as the mdnsd daemon from Apple's bonjour distribution are required. The mdnsd daemon has to be running on the local host.

Browsing the local network for XMPP services

You can use the Manager to browse the local network for XMPP services. First, create a new instance, register a LinkLocal::Handler, and call startBrowsing().

m_mdns = new LinkLocal::Manager( ... );
m_mdns->registerLinkLocalHandler( yourHandler );
m_mdns->startBrowsing();

Then you will need to call recv() periodcally. The handler will then receive lists of available or removed services. Check the flag member of the Service struct.

void MyClass::handleBrowseReply( const Service& service )
{
LinkLocal::ServiceList::const_iterator it = services.begin();
for( ; it != services.end(); ++it )
{
if( (*it).flag == LinkLocal::AddService )
{
// new service
}
else
{
// service removed
}
}
}
Note
Note that your own service may show up in the list, too.

Connecting to an XMPP service

Using the info from the Service struct you can initiate a connection to the remote entity. First, create a new instance of LinkLocal::Client and register some basic handlers like you would with a normal gloox::Client:

LinkLocal::Client c( JID( "romeo@montague.net" ) );
c.logInstance().registerLogHandler( LogLevelDebug, LogAreaAll, this ); // optional
c.registerConnectionListener( yourConnectionListener );

Then call connect() and pass the paramters from the Service struct that you received in handleBrowseReply().

c.connect( "juliet@laptop", "_presence._tcp", ".local", 4 ); // don't use literal values

Put your LinkLocal::Client instance in your event loop (or in a separate thread) and call recv() periodically.

Advertising an XMPP service on the local network

To advertise your own XMPP service you can (re-)use the same Manager instance from 'browsing the local network' above.

You can publish some basic info about your service in a DNS TXT record. The Manager offers the addTXTData() function for that. See http://xmpp.org/registrar/linklocal.html for a list of official parameters.

m_mdns->addTXTData("nick","July");
m_mdns->addTXTData("1st","Juliet");
m_mdns->addTXTData("last","Capulet");
m_mdns->addTXTData("msg","Hanging out");
m_mdns->addTXTData("jid","julia@capulet.com");
m_mdns->addTXTData("status","avail");

Then, to start publishing the availability of your service as well as the TXT record with the additional info you just call registerService().

m_mdns->registerService();

Other entities on the network will now be informed about the availability of your service.

Listening for incoming connections

The second argument to Manager's constructor is a ConnectionHandler-derived class that will receive incoming connections.

When registerService() gets called, the Manager will also start a local server that will accept incoming connections. By default, it will listen on port 5562.

In handleIncomingConnection() you should create a new LinkLocal::Client and register some basic handlers:

LinkLocal::Client c( JID( "romeo@desktop" ) );
c.logInstance().registerLogHandler( LogLevelDebug, LogAreaAll, this );
c.registerMessageHandler( this );
c.registerConnectionListener( this );

Finally you have to attach the incoming connection to the Client instance, and call connect().

connection->registerConnectionDataHandler( &c );
c.setConnectionImpl( connection );
c.connect();

Add the Client to your event loop to call recv() periodically.

See Also
linklocal_example.cpp in src/examples/ for a (very) simple implementation of a bot handling both incoming and outgoing connections.
Author
Jakob Schroeter js@ca.nosp@m.maya.nosp@m..net
Since
1.0.x

Definition at line 167 of file linklocalmanager.h.

Constructor & Destructor Documentation

Manager ( const std::string &  user,
ConnectionHandler connHandler,
const LogSink logInstance 
)

Creates a new Link-local Manager instance. You can call registerService() and/or startBrowsing() immediately on a new Manager object, it will use sane defaults.

Parameters
userThe username to advertise, preferably (as per XEP-0174) the locally logged-in user. This is just the local part of the local JID.
connHandlerA pointer to a ConnectionHandler that will receive incoming connections.
logInstanceThe log target. Obtain it from ClientBase::logInstance().

Definition at line 45 of file linklocalmanager.cpp.

~Manager ( )
virtual

Virtual destructor.

Note
deregisterService() and stopBrowsing() will be called automatically if necessary.

Definition at line 55 of file linklocalmanager.cpp.

Member Function Documentation

void addTXTData ( const std::string &  key,
const std::string &  value 
)

Lets you add additional data to the published TXT record.

Note
The txtvers=1 parameter is included by default and cannot be changed.
Parameters
keyThe key of a key=value parameter pair. Must be non-empty. If the given key has been set before, its value will be overwritten by the new value.
valueThe value of a key=value parameter pair. Must be non-empty.
Note
If either parameter is empty, this function is a NOOP.
The additional data will not be automatically published if you have already called registerService(). You will have to call registerService() again to update the TXT record.

Definition at line 61 of file linklocalmanager.cpp.

void deregisterService ( )

Removes the published DNS records and thereby stops advertising link-local messaging capabilities.

Definition at line 117 of file linklocalmanager.cpp.

void recv ( int  timeout)

Checks once for new data on the socket used for browsing.

Parameters
timeoutThe timeout for select() in microseconds. Use -1 if blocking behavior is acceptable.

Definition at line 156 of file linklocalmanager.cpp.

void registerLinkLocalHandler ( Handler handler)
inline

Registers a handler that will be notfied about entities found on the network that match the given browse criteria.

Parameters
handlerThe handler to register.

Definition at line 308 of file linklocalmanager.h.

void registerService ( )

Starts advertising link-local messaging capabilities by publishing a number of DNS records, as per XEP-0174. You can call this function again to publish any values you updated after the first call.

Definition at line 74 of file linklocalmanager.cpp.

void removeTXTData ( const std::string &  key)

Lets you remove TXT record data by key.

Note
The txtvers=1 parameter is included by default and cannot be removed.
Parameters
keyThe key of the key=value parameter pair that should be removed. Must be non-empty.
Note
A published TXT record will not be automatically updated if you have already called registerService(). You will have to call registerService() again to update the TXT record.

Definition at line 69 of file linklocalmanager.cpp.

void setDomain ( const std::string &  domain)
inline

This function lets you set an alternate browse domain. The default domain should work in most cases.

Parameters
domainThe browse domain to set.
Note
The new domain will not be automatically used if you have already called registerService(). You will have to call registerService() again to update the domain. The same applies to startBrowsing().

Definition at line 247 of file linklocalmanager.h.

void setHost ( const std::string &  host)
inline

Lets you specify an alternate host name to advertise. By default the local machine's hostname as returned by gethostname() will be used.

Parameters
hostThe hostname to use.
Note
The new hostname will not be automatically advertised if you have already called registerService(). You will have to call registerService() again to update the hostname.

Definition at line 238 of file linklocalmanager.h.

void setInterface ( unsigned  iface)
inline

This function can be used to set a non-default interface. Use if_nametoindex() to find the index for a specific named device. By default DNS records will be broadcast on all available interfaces, and all available interfaces will be used or browsing services.

Parameters
ifaceThe interface to use. If you set an interface here, and want to change it back to 'any', use 0. Use -1 to broadcast only on the local machine.
Note
The new interface will not be automatically used if you have already called registerService(). You will have to call registerService() again to use the new interface. The same applies to startBrowsing().

Definition at line 272 of file linklocalmanager.h.

void setPort ( const int  port)
inline

Lets you specifiy a port to listen on for incoming server-less XMPP connections. Default for this implementation is port 5562, but any unused port can be used.

Note
In addition to the SRV record, the port will also be published in the TXT record automaticlly, you do not have to add it manually. That is, you should not call addTXTData() with a key of "port.p2pj".
Parameters
portThe port to use.
Note
The new port will not be automatically advertised if you have already called registerService(). You will have to call registerService() again to update the port.

Definition at line 259 of file linklocalmanager.h.

void setUser ( const std::string &  user)
inline

Lets you specify a new username.

Parameters
userThe new username.
Note
The new username will not be automatically advertised if you have already called registerService(). You will have to call registerService() again to update the username.

Definition at line 229 of file linklocalmanager.h.

int socket ( ) const
inline

Exposes the socket used for browsing so you can have it checked in your own event loop, if desired. If your event loop signals new data on the socket, you should NOT try to read from it directly. Instead you should call recv(). As an alternative to using the raw socket you could also put the Manager in a separate thread and call recv() repeatedly, or achieve this in any other way.

Definition at line 294 of file linklocalmanager.h.

bool startBrowsing ( )

Starts looking for other entities of type _presence. You have to set a handler for results using registerLinkLocalHandler() before calling this function. You can call this function again to re-start browsing with updated parameters.

Returns
Returns true if browsing could be started successfully, false otherwise.

Definition at line 126 of file linklocalmanager.cpp.

void stopBrowsing ( )

Stops the browsing.

Definition at line 147 of file linklocalmanager.cpp.


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