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();
gloox::LinkLocal::Manager
This is a manager for server-less messaging (XEP-0174).
Definition linklocalmanager.h:168

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
}
}
}
gloox::LinkLocal::AddService
@ AddService
Definition linklocal.h:42
gloox::LinkLocal::Service
An abstraction of the parameters of a single link-local service.
Definition linklocal.h:53

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 );
gloox::JID
An abstraction of a JID.
Definition jid.h:31
gloox::LinkLocal::Client
An implementation of a link-local client.
Definition linklocalclient.h:46
gloox::LogAreaAll
@ LogAreaAll
Definition gloox.h:1073
gloox::LogLevelDebug
@ LogLevelDebug
Definition gloox.h:1081

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 Schröter js@ca.nosp@m.maya.nosp@m..net

Since
  1.0.1

Definition at line 167 of file linklocalmanager.h.

## Constructor & Destructor Documentation

## Manager()

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

~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

## addTXTData()

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.

## deregisterService()

void deregisterService | ( |  | ) |

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

Definition at line 117 of file linklocalmanager.cpp.

## recv()

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.

## registerLinkLocalHandler()

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.

## registerService()

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.

## removeTXTData()

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.

## setDomain()

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.

## setHost()

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.

## setInterface()

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.

## setPort()

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.

## setUser()

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.

## socket()

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.

## startBrowsing()

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.

## stopBrowsing()

void stopBrowsing | ( |  | ) |

Stops the browsing.

Definition at line 147 of file linklocalmanager.cpp.

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

- linklocalmanager.h
- linklocalmanager.cpp