## BtSetup

BtSetup — class with all machines and wires (BtMachine and BtWire) for a BtSong instance

## Synopsis

    #include <libbtcore/core.h>

                        BtSetup;
    BtSetup *           bt_setup_new                        (const BtSong * const song);
    gboolean            bt_setup_add_machine                (const BtSetup * const self,
                                                             const BtMachine * const machine);
    gboolean            bt_setup_add_wire                   (const BtSetup * const self,
                                                             const BtWire * const wire);
    void                bt_setup_remove_machine             (const BtSetup * const self,
                                                             const BtMachine * const machine);
    void                bt_setup_remove_wire                (const BtSetup * const self,
                                                             const BtWire * const wire);
    BtMachine *         bt_setup_get_machine_by_id          (const BtSetup * const self,
                                                             const gchar * const id);
    BtMachine *         bt_setup_get_machine_by_type        (const BtSetup * const self,
                                                             const GType type);
    GList *             bt_setup_get_machines_by_type       (const BtSetup * const self,
                                                             const GType type);
    BtWire *            bt_setup_get_wire_by_src_machine    (const BtSetup * const self,
                                                             const BtMachine * const src);
    BtWire *            bt_setup_get_wire_by_dst_machine    (const BtSetup * const self,
                                                             const BtMachine * const dst);
    BtWire *            bt_setup_get_wire_by_machines       (const BtSetup * const self,
                                                             const BtMachine * const src,
                                                             const BtMachine * const dst);
    GList *             bt_setup_get_wires_by_src_machine   (const BtSetup * const self,
                                                             const BtMachine * const src);
    GList *             bt_setup_get_wires_by_dst_machine   (const BtSetup * const self,
                                                             const BtMachine * const dst);
    gchar *             bt_setup_get_unique_machine_id      (const BtSetup * const self,
                                                             gchar * const base_name);
    void                bt_setup_remember_missing_machine   (const BtSetup * const self,
                                                             const gchar * const str);

## Object Hierarchy

      GObject
       +----BtSetup

## Implemented Interfaces

BtSetup implements

## Properties

      "machines"                 gpointer              : Read
      "missing-machines"         gpointer              : Read
      "properties"               gpointer              : Read
      "song"                     BtSong*               : Read / Write / Construct Only
      "wires"                    gpointer              : Read

## Signals

      "machine-added"                                  : Run Last / No Recursion / No Hooks
      "machine-removed"                                : Run Last / No Recursion / No Hooks
      "wire-added"                                     : Run Last / No Recursion / No Hooks
      "wire-removed"                                   : Run Last / No Recursion / No Hooks

## Description

The setup manages virtual gear. That is used BtMachines and the BtWires that connect them.

It also manages the GStreamer GstPipleine content.

## Details

### BtSetup

    typedef struct _BtSetup BtSetup;

virtual hardware setup (contains BtMachine and BtWire objects)

### bt_setup_new ()

    BtSetup *           bt_setup_new                        (const BtSong * const song);

Create a new instance

`song` : | the song the new instance belongs to
Returns : | the new instance or `NULL` in case of an error

### bt_setup_add_machine ()

    gboolean            bt_setup_add_machine                (const BtSetup * const self,
                                                             const BtMachine * const machine);

Let the setup know that the suplied machine is now part of the song.

`self` : | the setup to add the machine to
`machine` : | the new machine instance
Returns : | return true, if the machine can be added. Returns false if the machine is currently added to the setup.

### bt_setup_add_wire ()

    gboolean            bt_setup_add_wire                   (const BtSetup * const self,
                                                             const BtWire * const wire);

Let the setup know that the suplied wire is now part of the song.

`self` : | the setup to add the wire to
`wire` : | the new wire instance
Returns : | returns true, if the wire is added. Returns false, if the setup contains a wire witch is link between the same src and dst machines (cycle check).

### bt_setup_remove_machine ()

    void                bt_setup_remove_machine             (const BtSetup * const self,
                                                             const BtMachine * const machine);

Let the setup know that the suplied machine is removed from the song.

`self` : | the setup to remove the machine from
`machine` : | the machine instance to remove

### bt_setup_remove_wire ()

    void                bt_setup_remove_wire                (const BtSetup * const self,
                                                             const BtWire * const wire);

Let the setup know that the suplied wire is removed from the song.

`self` : | the setup to remove the wire from
`wire` : | the wire instance to remove

### bt_setup_get_machine_by_id ()

    BtMachine *         bt_setup_get_machine_by_id          (const BtSetup * const self,
                                                             const gchar * const id);

Search the setup for a machine by the supplied id. The machine must have been added previously to this setup with `bt_setup_add_machine()`. Unref the machine, when done with it.

`self` : | the setup to search for the machine
`id` : | the identifier of the machine
Returns : | BtMachine instance or `NULL` if not found

### bt_setup_get_machine_by_type ()

    BtMachine *         bt_setup_get_machine_by_type        (const BtSetup * const self,
                                                             const GType type);

Search the setup for the first machine with the given type. The machine must have been added previously to this setup with `bt_setup_add_machine()`. Unref the machine, when done with it.

`self` : | the setup to search for the machine
`type` : | the gobject type (sink,processor,source)
Returns : | BtMachine instance or `NULL` if not found

### bt_setup_get_machines_by_type ()

    GList *             bt_setup_get_machines_by_type       (const BtSetup * const self,
                                                             const GType type);

Gathers all machines of the given type from the setup. Free the list (and unref the machines), when done with it.

`self` : | the setup to search for the machine
`type` : | the gobject type (sink,processor,source)
Returns : | the list instance or `NULL` if not found

### bt_setup_get_wire_by_src_machine ()

    BtWire *            bt_setup_get_wire_by_src_machine    (const BtSetup * const self,
                                                             const BtMachine * const src);

Searches for the first wire in setup that uses the given BtMachine as a source. In other words - it returns the first wire that starts at the given BtMachine. Unref the wire, when done with it.

`self` : | the setup to search for the wire
`src` : | the machine that is at the src end of the wire
Returns : | the BtWire or `NULL`

### bt_setup_get_wire_by_dst_machine ()

    BtWire *            bt_setup_get_wire_by_dst_machine    (const BtSetup * const self,
                                                             const BtMachine * const dst);

Searches for the first wire in setup that uses the given BtMachine as a target. In other words - it returns the first wire that ends at the given BtMachine. Unref the wire, when done with it.

`self` : | the setup to search for the wire
`dst` : | the machine that is at the dst end of the wire
Returns : | the BtWire or `NULL`

### bt_setup_get_wire_by_machines ()

    BtWire *            bt_setup_get_wire_by_machines       (const BtSetup * const self,
                                                             const BtMachine * const src,
                                                             const BtMachine * const dst);

Searches for a wire in setup that uses the given BtMachine instances as a source and dest. Unref the wire, when done with it.

`self` : | the setup to search for the wire
`src` : | the machine that is at the src end of the wire
`dst` : | the machine that is at the dst end of the wire
Returns : | the BtWire or NULL

### bt_setup_get_wires_by_src_machine ()

    GList *             bt_setup_get_wires_by_src_machine   (const BtSetup * const self,
                                                             const BtMachine * const src);

Searches for all wires in setup that use the given BtMachine as a source. Free the list (and unref the wires), when done with it.

`self` : | the setup to search for the wire
`src` : | the machine that is at the src end of the wire
Returns : | a GList with the BtWires or `NULL`

### bt_setup_get_wires_by_dst_machine ()

    GList *             bt_setup_get_wires_by_dst_machine   (const BtSetup * const self,
                                                             const BtMachine * const dst);

Searches for all wires in setup that use the given BtMachine as a target. Free the list (and unref the wires), when done with it.

`self` : | the setup to search for the wire
`dst` : | the machine that is at the dst end of the wire
Returns : | a GList with the BtWires or `NULL`

### bt_setup_get_unique_machine_id ()

    gchar *             bt_setup_get_unique_machine_id      (const BtSetup * const self,
                                                             gchar * const base_name);

The function makes the supplied base_name unique in this setup by eventually adding a number postfix. This method should be used when adding new machines.

`self` : | the setup for which the name should be unique
`base_name` : | the leading name part
Returns : | the newly allocated unique name

### bt_setup_remember_missing_machine ()

    void                bt_setup_remember_missing_machine   (const BtSetup * const self,
                                                             const gchar * const str);

Loaders can use this function to collect information about machines that failed to load. The front-end can access this later by reading BtSetup::missing-machines property.

`self` : | the setup
`str` : | human readable description of the missing machine

## Property Details

### The `"machines"` property

      "machines"                 gpointer              : Read

A copy of the list of machines.

### The `"missing-machines"` property

      "missing-machines"         gpointer              : Read

The list of missing machines, don't change.

### The `"properties"` property

      "properties"               gpointer              : Read

list of setup properties.

### The `"song"` property

      "song"                     BtSong*               : Read / Write / Construct Only

Set song object, the setup belongs to.

### The `"wires"` property

      "wires"                    gpointer              : Read

A copy of the list of wires.

## Signal Details

### The `"machine-added"` signal

    void                user_function                      (BtSetup   *self,
                                                            BtMachine *machine,
                                                            gpointer   user_data)      : Run Last / No Recursion / No Hooks

A new machine item has been added to the setup

`self` : | the setup object that emitted the signal
`machine` : | the new machine
`user_data` : | user data set when the signal handler was connected.

### The `"machine-removed"` signal

    void                user_function                      (BtSetup   *self,
                                                            BtMachine *machine,
                                                            gpointer   user_data)      : Run Last / No Recursion / No Hooks

A machine item has been removed from the setup

`self` : | the setup object that emitted the signal
`machine` : | the old machine
`user_data` : | user data set when the signal handler was connected.

### The `"wire-added"` signal

    void                user_function                      (BtSetup *self,
                                                            BtWire  *wire,
                                                            gpointer user_data)      : Run Last / No Recursion / No Hooks

A new wire item has been added to the setup

`self` : | the setup object that emitted the signal
`wire` : | the new wire
`user_data` : | user data set when the signal handler was connected.

### The `"wire-removed"` signal

    void                user_function                      (BtSetup *self,
                                                            BtWire  *wire,
                                                            gpointer user_data)      : Run Last / No Recursion / No Hooks

A wire item has been removed from the setup

`self` : | the setup object that emitted the signal
`wire` : | the old wire
`user_data` : | user data set when the signal handler was connected.