BrowserFavorites

## BrowserFavorites BrowserFavorites — Favorites management |

## Synopsis

                        BrowserFavoritesPrivate;
    enum                BrowserFavoritesType;
    #define             BROWSER_FAVORITES_NB_TYPES
                        BrowserFavoritesAttributes;
                        BrowserFavorites;
    BrowserFavorites *  browser_favorites_new               (GdaMetaStore *store);
    gboolean            browser_favorites_add               (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesAttributes *fav,
                                                             gint order_key,
                                                             gint pos,
                                                             GError **error);
    GSList *            browser_favorites_list              (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesType type,
                                                             gint order_key,
                                                             GError **error);
    gboolean            browser_favorites_delete            (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesAttributes *fav,
                                                             GError **error);
    void                browser_favorites_free_list         (GSList *fav_list);
    void                browser_favorites_reset_attributes  (BrowserFavoritesAttributes *fav);
    gint                browser_favorites_find              (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             const gchar *contents,
                                                             BrowserFavoritesAttributes *out_fav,
                                                             GError **error);
    gboolean            browser_favorites_get               (BrowserFavorites *bfav,
                                                             gint fav_id,
                                                             BrowserFavoritesAttributes *out_fav,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----BrowserFavorites

## Signals

      "favorites-changed"                              : Run First / Has Details

## Description

Each connection uses a single BrowserFavorites object to manage its favorites, see `browser_connection_get_favorites()`.

## Details

### BrowserFavoritesPrivate

    typedef struct _BrowserFavoritesPrivate BrowserFavoritesPrivate;

### enum BrowserFavoritesType

    typedef enum {
            BROWSER_FAVORITES_TABLES   = 1 << 0,
    	BROWSER_FAVORITES_DIAGRAMS = 1 << 1,
    	BROWSER_FAVORITES_QUERIES  = 1 << 2,
    	BROWSER_FAVORITES_DATA_MANAGERS  = 1 << 3
    } BrowserFavoritesType;

Enum to identify favorite's types.

`BROWSER_FAVORITES_TABLES` | a database's table favorite
`BROWSER_FAVORITES_DIAGRAMS` | a diagram favorite
`BROWSER_FAVORITES_QUERIES` |
`BROWSER_FAVORITES_DATA_MANAGERS` |

### BROWSER_FAVORITES_NB_TYPES

    #define BROWSER_FAVORITES_NB_TYPES 4

### BrowserFavoritesAttributes

    typedef struct {
    	gint                  id;
    	BrowserFavoritesType  type;
    	gchar                *name;
    	gchar                *descr;
    	gchar                *contents;
    } BrowserFavoritesAttributes;

gint `id`; | the favorite ID, or <0 if not saved
BrowserFavoritesType `type`; | the favorite's type
gchar *`name`; | the favorite's name
gchar *`descr`; | the favorite's description
gchar *`contents`; | the favorite's contents, depending on the favorite type

### BrowserFavorites

    typedef struct _BrowserFavorites BrowserFavorites;

### browser_favorites_new ()

    BrowserFavorites *  browser_favorites_new               (GdaMetaStore *store);

Creates a new BrowserFavorites object

`store` : |
Returns : | the new object

### browser_favorites_add ()

    gboolean            browser_favorites_add               (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesAttributes *fav,
                                                             gint order_key,
                                                             gint pos,
                                                             GError **error);

Add a new favorite, or replace an existing one. NOTE:

- if `fav->id` is < 0 then it's either an update or an insert (depending if fav->contents exists) and if it's not it is an UPDATE

- `fav->type` can't be 0

- `fav->contents` can't be `NULL`

On success `fav->id` contains the favorite's ID, otherwise it will contain -1.

if `order_key` is negative, then no ordering is done and `pos` is ignored.

`bfav` : |
`session_id` : |
`fav` : |
`order_key` : |
`pos` : |
`error` : |
Returns : |

### browser_favorites_list ()

    GSList *            browser_favorites_list              (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesType type,
                                                             gint order_key,
                                                             GError **error);

Extract some favorites.

`bfav` : | a BrowserFavorites
`session_id` : | 0 for now
`type` : | filter the type of attributes to be listed
`order_key` : | a key to order the listed favorites, such as ORDER_KEY_SCHEMA
`error` : | a place to store errors, or `NULL`
Returns : | a new list of BrowserFavoritesAttributes pointers. The list has to be freed using `browser_favorites_free_list()`

### browser_favorites_delete ()

    gboolean            browser_favorites_delete            (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             BrowserFavoritesAttributes *fav,
                                                             GError **error);

`bfav` : |
`session_id` : |
`fav` : |
`error` : |
Returns : |

### browser_favorites_free_list ()

    void                browser_favorites_free_list         (GSList *fav_list);

Frees all the BrowserFavoritesAttributes of the `fav_list` list, and frees the list itself.

`fav_list` : | a list of BrowserFavoritesAttributes

### browser_favorites_reset_attributes ()

    void                browser_favorites_reset_attributes  (BrowserFavoritesAttributes *fav);

Resets `fav` with empty attributes; it does not free `fav`.

`fav` : | a pointer to a BrowserFavoritesAttributes

### browser_favorites_find ()

    gint                browser_favorites_find              (BrowserFavorites *bfav,
                                                             guint session_id,
                                                             const gchar *contents,
                                                             BrowserFavoritesAttributes *out_fav,
                                                             GError **error);

Get all the information about a favorite from its id: fills the `out_fav` pointed structure. Use `browser_favorites_reset_attributes()` to reset `out_fav`'s contents.

Retuns: the requested's favorite ID, or -1 if not found

`bfav` : | a BrowserFavorites
`session_id` : | 0 for now
`contents` : | the favorite's contents
`out_fav` : | a BrowserFavoritesAttributes to be filled with the favorite's attributes, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : |

### browser_favorites_get ()

    gboolean            browser_favorites_get               (BrowserFavorites *bfav,
                                                             gint fav_id,
                                                             BrowserFavoritesAttributes *out_fav,
                                                             GError **error);

Get all the information about a favorite from its id: fills the `out_fav` pointed structure. Use `browser_favorites_reset_attributes()` to reset `out_fav`'s contents.

Retuns: `TRUE` if no error occurred.

`bfav` : | a BrowserFavorites
`fav_id` : | the favorite's ID
`out_fav` : | a BrowserFavoritesAttributes to be filled with the favorite's attributes
`error` : | a place to store errors, or `NULL`
Returns : |

## Signal Details

### The `"favorites-changed"` signal

    void                user_function                      (BrowserFavorites *browserfavorites,
                                                            gpointer          user_data)             : Run First / Has Details

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