#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

user	The username to advertise, preferably (as per XEP-0174) the locally logged-in user. This is just the local part of the local JID.
connHandler	A pointer to a ConnectionHandler that will receive incoming connections.
logInstance	The 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

key	The 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.
value	The 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

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

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

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

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

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

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

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

user	The 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:

Public Member Functions

Detailed Description

Browsing the local network for XMPP services

Connecting to an XMPP service

Advertising an XMPP service on the local network

Listening for incoming connections

Constructor & Destructor Documentation

Member Function Documentation