DeePeer

DeePeer — Finds other objects with the same swarm-name on the bus.

Synopsis

#include <dee.h>

                    DeePeer;
                    DeePeerClass;
                    DeePeerPrivate;
#define             DEE_PEER_DBUS_IFACE
void                dee_peer_connect                    (DeePeer *self);
const gboolean      dee_peer_is_swarm_leader            (DeePeer *self);
const gchar*        dee_peer_get_swarm_leader           (DeePeer *self);
const gchar *       dee_peer_get_swarm_name             (DeePeer *self);

Object Hierarchy

  GObject
   +----DeePeer

Properties

  "swarm-leader"             gchar*                : Read
  "swarm-name"               gchar*                : Read / Write / Construct

Signals

  "bye"                                            : Run Last
  "connected"                                      : Run Last
  "peer-found"                                     : Run Last
  "peer-lost"                                      : Run Last
  "ping"                                           : Run Last
  "pong"                                           : Run Last

Description

DeePeer allows you to build objects that can 'find eachother' on D-Bus without the need for an central registration service. Think of it like peer-to-peer for your application. The DBus session bus will also implicitly elect a swarm leader - namely the one owning the swarm name on the bus, but it's up to the consumer of this API to determine whether swarm leadership has any concrete responsibilities associated.

Peers find eachother through a well-known "swarm-name", which loosely translates to a DBus name, such as: org.myapp.MyPeers. Choose a namespaced name that would not normally be used outside of your program.

For example:

{
  DeePeer *peer;

  peer = g_object_new (DBUS_TYPE_PEER,
                       "swarm-name", "org.myapp.MyPeers",
                       NULL);

  g_signal_connect (peer, "peer-found",
                    G_CALLBACK (on_peer_found), NULL);
  g_signal_connect (peer, "peer-lost",
                    G_CALLBACK (on_peer_lost), NULL);

  /* Publish this peer and start monitoring for other peers */
  dee_peer_connect (peer);
}

Commonly the callbacks for these signals will create (or tear down) a proxy for the relevant peer. With DBus-GLib it might look like:

void
on_peer_found (DeePeer *peer, const gchar *name)
{
  DBusGProxy *proxy;

  /* We have found a peer, so let's connect to it with a well-known
   * interface.
   */
  proxy = dbus_g_proxy_new_for_name_owner (connection,
                                           name,
                                           "/org/myapp/MyPeerIface",
                                           "org.myapp.MyPeerIface",
                                           NULL);
}

Details

DeePeer

typedef struct _DeePeer DeePeer;

All fields in the DeePeer structure are private and should never be accessed directly


DeePeerClass

typedef struct {
  /*< signals >*/
  void (*connected)  (DeePeer *peer, const gchar *peer_name);
  void (*peer_found) (DeePeer *peer, const gchar *name);
  void (*peer_lost)  (DeePeer *peer, const gchar *name);

  /*< vtable >*/
} DeePeerClass;


DeePeerPrivate

typedef struct _DeePeerPrivate DeePeerPrivate;

Ignore this structure.


DEE_PEER_DBUS_IFACE

#define DEE_PEER_DBUS_IFACE "com.canonical.Dee.Peer"


dee_peer_connect ()

void                dee_peer_connect                    (DeePeer *self);

Will cause self to connect to the swarm and begin monitoring peers.

self :

a DeePeer

dee_peer_is_swarm_leader ()

const gboolean      dee_peer_is_swarm_leader            (DeePeer *self);

self :

a DeePeer

Returns :

TRUE if and only if this peer owns the swarm name on the session bus

dee_peer_get_swarm_leader ()

const gchar*        dee_peer_get_swarm_leader           (DeePeer *self);

Gets the unique DBus address of the current swarm leader.

This function can only be used after dee_peer_connect() has been called.

self :

a DeePeer

Returns :

Unique DBus address of the current swarm leader, possibly NULL if the leader has not been detected yet

dee_peer_get_swarm_name ()

const gchar *       dee_peer_get_swarm_name             (DeePeer *self);

Gets the unique name for this swarm. The swarm leader is the Peer owning this name on the session bus.

self :

a DeePeer

Returns :

The swarm name

Property Details

The "swarm-leader" property

  "swarm-leader"             gchar*                : Read

Unique DBus address of the swarm leader.

Default value: NULL


The "swarm-name" property

  "swarm-name"               gchar*                : Read / Write / Construct

Well-known name to find other peers with.

Default value: NULL

Signal Details

The "bye" signal

void                user_function                      (DeePeer *deepeer,
                                                        gchar   *arg1,
                                                        gchar   *arg2,
                                                        gpointer user_data)      : Run Last

deepeer :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "connected" signal

void                user_function                      (DeePeer *self,
                                                        gchar   *unique_name,
                                                        gpointer user_data)        : Run Last

Connect to this signal to be notified when the peer connects to DBus. Sub-classes should connect to this signal so they register themselves on the bus at the same time.

self :

the DeePeer on which the signal is emitted

unique_name :

the unique name of the connection

user_data :

user data set when the signal handler was connected.

The "peer-found" signal

void                user_function                      (DeePeer *self,
                                                        gchar   *name,
                                                        gpointer user_data)      : Run Last

Connect to this signal to be notified of existing and new peers that are in your swarm.

self :

the DeePeer on which the signal is emitted

name :

the DBus name of the object found

user_data :

user data set when the signal handler was connected.

The "peer-lost" signal

void                user_function                      (DeePeer *self,
                                                        gchar   *name,
                                                        gpointer user_data)      : Run Last

Connect to this signal to be notified when peers disconnect from the swarm

self :

the DeePeer on which the signal is emitted

name :

the DBus name of the object that disconnected

user_data :

user data set when the signal handler was connected.

The "ping" signal

void                user_function                      (DeePeer *arg0,
                                                        gchar   *arg1,
                                                        gpointer user_data)      : Run Last

Private signal leaked because of how dbus-glib work with signals

user_data :

user data set when the signal handler was connected.

The "pong" signal

void                user_function                      (DeePeer *arg0,
                                                        gchar   *arg1,
                                                        gpointer user_data)      : Run Last

Private signal leaked because of how dbus-glib work with signals

user_data :

user data set when the signal handler was connected.