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

## Synopsis

    #include <dee.h>

    #define             DEE_PEER_DBUS_IFACE
    struct              DeePeer;
    struct              DeePeerClass;
    GSList *            dee_peer_get_connections            (DeePeer *self);
    const gchar *       dee_peer_get_swarm_leader           (DeePeer *self);
    const gchar *       dee_peer_get_swarm_name             (DeePeer *self);
    gboolean            dee_peer_is_swarm_leader            (DeePeer *self);
    gboolean            dee_peer_is_swarm_owner             (DeePeer *self);
    gchar **            dee_peer_list_peers                 (DeePeer *self);
    DeePeer *           dee_peer_new                        (const gchar *swarm_name);

## Object Hierarchy

      GObject
       +----DeePeer
             +----DeeClient
             +----DeeServer

## Properties

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

## Signals

      "connection-acquired"                            : Run Last
      "connection-closed"                              : Run Last
      "peer-found"                                     : Run Last
      "peer-lost"                                      : Run Last

## Description

DeePeer allows you to build objects that can rendevouz on DBus 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 is a well known 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);
    }

## Details

### DEE_PEER_DBUS_IFACE

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

### struct DeePeer

    struct DeePeer;

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

### struct DeePeerClass

    struct DeePeerClass {
      /*< signals >*/
      void (*peer_found)          (DeePeer *self, const gchar *name);
      void (*peer_lost)           (DeePeer *self, const gchar *name);
      void (*connection_acquired) (DeePeer *self, GDBusConnection *connection);
      void (*connection_closed)   (DeePeer *self, GDBusConnection *connection);

      /*< vtable >*/
      const gchar* (*get_swarm_leader)  (DeePeer *self);
      gboolean     (*is_swarm_leader)   (DeePeer *self);
      GSList*      (*get_connections)   (DeePeer *self);
      gchar**      (*list_peers)        (DeePeer *self);
    };

### dee_peer_get_connections ()

    GSList *            dee_peer_get_connections            (DeePeer *self);

Gets list of GDBusConnection instances used by this DeePeer instance.

`self` : | a DeePeer
Returns : | List of connections. [transfer container][element-type Gio.DBusConnection]

### dee_peer_get_swarm_leader ()

    const gchar *       dee_peer_get_swarm_leader           (DeePeer *self);

In case this peer is connected to a message bus, gets the unique DBus address of the current swarm leader, otherwise returns id of the leader.

`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

### dee_peer_is_swarm_leader ()

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

    gboolean            dee_peer_is_swarm_owner             (DeePeer *self);

Gets the value of the :swarm-owner property.

Note that this does NOT mean that the peer is leader of the swarm! Check also `dee_peer_is_swarm_leader()`.

`self` : | a DeePeer
Returns : | TRUE if the :swarm-owner property was set during construction.

### dee_peer_list_peers ()

    gchar **            dee_peer_list_peers                 (DeePeer *self);

Gets list of all peers currently in this swarm.

`self` : | a DeePeer
Returns : | List of peers (free using `g_strfreev()`). [transfer full]

### dee_peer_new ()

    DeePeer *           dee_peer_new                        (const gchar *swarm_name);

Create a new DeePeer. The peer will immediately connect to the swarm and start the peer discovery.

`swarm_name` : | The name of the swarm to join. Fx "org.example.DataProviders"
Returns : | A newly constructed DeePeer. Free with `g_object_unref()`. [transfer full]

## 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

### The `"swarm-owner"` property

      "swarm-owner"              gboolean              : Read / Write / Construct Only

Try to assume leadership of the swarm.

Default value: FALSE

## Signal Details

### The `"connection-acquired"` signal

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

`deepeer` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"connection-closed"` signal

    void                user_function                      (DeePeer         *self,
                                                            GDBusConnection *connection,
                                                            gpointer         user_data)       : Run Last

Connect to this signal to be notified when peers close their GDBusConnection.

`self` : | the DeePeer on which the signal is emitted
`connection` : | the closed GDBusConnection
`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.