DmapControlShare: libdmapsharing Reference Manual

## DmapControlShare DmapControlShare — A DACP share. |

## Functions

DmapControlShare * | dmap_control_share_new ()
void | dmap_control_share_pair ()
gboolean | dmap_control_share_start_lookup ()
gboolean | dmap_control_share_stop_lookup ()
void | dmap_control_share_player_updated ()

## Properties

char * | library-name | Read / Write
GObject * | player | Read / Write / Construct Only

## Signals

void | add-guid | Run Last
gboolean | lookup-guid | Run Last
void | remote-found | Run Last
void | remote-lost | Run Last
void | remote-paired | Run Last

## Object Hierarchy

        GObject
        ╰── DmapShare
            ╰── DmapControlShare

## Description

DmapControlShare objects encapsulate a DACP share.

## Functions

### dmap_control_share_new ()

    DmapControlShare *
    dmap_control_share_new (const gchar *library_name,
                            DmapControlPlayer *player,
                            DmapDb *db,
                            DmapContainerDb *container_db);

Creates a new DACP share and publishes it using mDNS.

#### Parameters

library_name | The library name that will be shown in the remote. |
player | A DmapControlPlayer instance, used to retrieve information from a player implementation. |
db | a media database represented by a DmapDb instance. |
container_db | a container (album) database represented by a DmapContainerDb instance. |

#### Returns

a pointer to a DmapControlShare.

### dmap_control_share_pair ()

    void
    dmap_control_share_pair (DmapControlShare *share,
                             gchar *service_name,
                             gchar passcode[4]);

Pairs a DACP client (Remote) with this server. If the passcode is correct (the same as shown on the remote), the remote will start connecting to this server.

#### Parameters

share | a DmapControlShare |
service_name | DACP client (remote) service identifier. |
passcode | 4-Digit PIN code entered by the user. |

### dmap_control_share_start_lookup ()

    gboolean
    dmap_control_share_start_lookup (DmapControlShare *share,
                                     GError **error);

Start looking up for DACP remotes. Connect to “remote-found” signal to detect new remotes. Be aware that when a DmapControlShare is created, only after calling this function is that it starts looking up for Remotes on the network.

#### Parameters

share | A DmapControlShare. |
error | A GError. |

#### Returns

TRUE on success, else FALSE with error set.

### dmap_control_share_stop_lookup ()

    gboolean
    dmap_control_share_stop_lookup (DmapControlShare *share,
                                    GError **error);

Stop looking up for DACP remotes.

#### Parameters

share | A DmapControlShare. |
error | A GError. |

### dmap_control_share_player_updated ()

    void
    dmap_control_share_player_updated (DmapControlShare *share);

## Property Details

### The `“library-name”` property

      “library-name”             char *

Library name as will be shown in the Remote.

Owner: DmapControlShare

Flags: Read / Write

Default value: NULL

### The `“player”` property

      “player”                   GObject *

Player.

Owner: DmapControlShare

Flags: Read / Write / Construct Only

## Signal Details

### The `“add-guid”` signal

    void
    user_function (DmapControlShare *share,
                   char             *guid,
                   gpointer          user_data)

Signal emited when the remote wants to log in and save a special guid which will be used later when it wants to reconnect. With this guid, we know that this remote has connected before, thus this signal must save somewhere all guids that connected before, so that ::lookup-guid will find this remote. The user interface probably wants to include a button to forget previously connected remotes, so that the user may disconnect all previously connected remotes.

#### Parameters

share | the DmapControlShare that received the signal |
guid | a string containing the guid to be saved. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“lookup-guid”` signal

    gboolean
    user_function (DmapControlShare *share,
                   char             *guid,
                   gpointer          user_data)

Signal emited when the remote has logged in before and wants to be validated. An implementation must implement this signal to lookup for guids saved by ::add-guid

#### Parameters

share | the DmapControlShare that received the signal |
guid | a string containing the guid to be validated. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“remote-found”` signal

    void
    user_function (DmapControlShare *share,
                   char             *service_name,
                   char             *remote_name,
                   gpointer          user_data)

Signal emited when a remote is found in the local network.

#### Parameters

share | the DmapControlShare that received the signal. |
service_name | the remote identifier. |
remote_name | the remote friendly name. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“remote-lost”` signal

    void
    user_function (DmapControlShare *share,
                   char             *service_name,
                   gpointer          user_data)

Signal emited when a remote is lost in the local network.

#### Parameters

share | the DmapControlShare that received the signal |
service_name | the remote identifier. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“remote-paired”` signal

    void
    user_function (DmapControlShare *share,
                   char             *service_name,
                   gboolean          connected,
                   gpointer          user_data)

Signal emited when a remote is paired.

#### Parameters

share | the DmapControlShare that received the signal |
service_name | the remote identifier. |
connected | indicates if the connection was succesfull or not. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last