GnomeScanBackend

## GnomeScanBackend GnomeScanBackend — Probe scanners |

## Synopsis

                        GnomeScanBackend;
    GnomeScanBackend*   gnome_scan_backend_new              (GType backend_type);
    void                gnome_scan_backend_probe_scanners   (GnomeScanBackend *backend);
    void                gnome_scan_backend_add_scanner      (GnomeScanBackend *backend,
                                                             GnomeScanner *scanner);
    void                gnome_scan_backend_remove_scanner   (GnomeScanBackend *backend,
                                                             GnomeScanner *scanner);
    void                gnome_scan_backend_probe_done       (GnomeScanBackend *backend);

## Object Hierarchy

      GObject
       +----GnomeScanBackend

## Signals

      "probe-done"                                     : Run Last
      "scanner-added"                                  : Run Last
      "scanner-removed"                                : Run First

## Description

In Gnome Scan, the so called "backend" is only responsible to probe devices. In fact, the scanner is only responsible to detect scanner plug and unplug and trigger signal about that. Probing is just a way to add already plugged scanner just like adding a hotplugged scanner.

The backend itseld does not maintain a public list of scanner, it's up to the UI to maintain a list of scanner (e.g. through a GtkListStore).

GnomeScanBackend is the base class for real backend. If you want to instanciate all backends, just initialize all GnomeScanModules and instanciate each `g_type_children()` of GnomeScanBackend.

## Details

### GnomeScanBackend

    typedef struct _GnomeScanBackend GnomeScanBackend;

The GnomeScanBackend is only responsible to probe scanners, emitting signal on scanner plug or unplug. Ideally, most of the acquisition work is done through GnomeScanner.

### gnome_scan_backend_new ()

    GnomeScanBackend*   gnome_scan_backend_new              (GType backend_type);

Instanciate a new backend of type `type`. It check wether `type` is a child type of GnomeScanBackend.

`backend_type` : | the top level backend GType
Returns : | a new GnomeScanBackend.

### gnome_scan_backend_probe_scanners ()

    void                gnome_scan_backend_probe_scanners   (GnomeScanBackend *backend);

Trigger probe. Ideally called in a new thread through `g_thread_create()`.

See: `g_thread_create()`

`backend` : | a GnomeScanBackend

### gnome_scan_backend_add_scanner ()

    void                gnome_scan_backend_add_scanner      (GnomeScanBackend *backend,
                                                             GnomeScanner *scanner);

This function is used by child class to trigger GnomeScanBackend::scanner-added signal.

`backend` : | a GnomeScanBackend
`scanner` : | a new GnomeScanner

### gnome_scan_backend_remove_scanner ()

    void                gnome_scan_backend_remove_scanner   (GnomeScanBackend *backend,
                                                             GnomeScanner *scanner);

Trigger GnomeScanBackend::scanner-removed upon `scanner`. This function is to be used only by child class.

`backend` : | a GnomeScanBackend
`scanner` : | a deprecated GnomeScanner

### gnome_scan_backend_probe_done ()

    void                gnome_scan_backend_probe_done       (GnomeScanBackend *backend);

Trigger GnomeScanBackend::probe-done signal. Used by child class.

`backend` : | a GnomeScanBackend

## Signal Details

### The "probe-done" signal

    void                user_function                      (GnomeScanBackend *backend,
                                                            gpointer          user_data)      : Run Last

This signal allow app to know if the backend has found a scanner during probe. If the GnomeScanBackend::probe-done signal is emitted and no GnomeScanBackend::scanner-added signal has been sent, this mean that no scanner has been found at all. Remember the backend does not handle a list of GnomeScanner.

`backend` : | the emitting GnomeScanBackend
`user_data` : | user data set when the signal handler was connected.

### The "scanner-added" signal

    void                user_function                      (GnomeScanBackend *backend,
                                                            GnomeScanner     *scanner,
                                                            gpointer          user_data)      : Run Last

This backend is triggered each time it discover a new scanner during probe or on plug.

`backend` : | the emitting GnomeScanBackend
`scanner` : | the newly added GnomeScanner
`user_data` : | user data set when the signal handler was connected.

### The "scanner-removed" signal

    void                user_function                      (GnomeScanBackend *backend,
                                                            GnomeScanner     *scanner,
                                                            gpointer          user_data)      : Run First

This signal is emitted as a scanner is lost. Every reference to this scanner must be removed.

`backend` : | the emitting GnomeScanBackend
`scanner` : | the scanner removed
`user_data` : | user data set when the signal handler was connected.