## BrowserFavorites BrowserFavorites — Favorites management |

## Synopsis

                        BrowserFavoritesPrivate;
    enum                BrowserFavoritesType;
    #define             BROWSER_FAVORITES_NB_TYPES
                        BrowserFavoritesAttributes;
    struct              BrowserFavorites;
    BrowserFavorites *  browser_favorites_new               (GdaMetaStore *store);
    const gchar *       browser_favorites_type_to_string    (BrowserFavoritesType type);
    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);

                        BrowserFavoriteAction;
    GSList *            browser_favorites_get_actions       (BrowserFavorites *bfav,
                                                             BrowserConnection *bcnc,
                                                             GdaSet *set);
    void                browser_favorites_free_action       (BrowserFavoriteAction *action);
    void                browser_favorites_free_actions_list (GSList *actions_list);

## Object Hierarchy

      GObject
       +----BrowserFavorites

## Signals

      "favorites-changed"                              : 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,
    	BROWSER_FAVORITES_ACTIONS  = 1 << 4,
    	BROWSER_FAVORITES_LDAP_DN  = 1 << 5,
    	BROWSER_FAVORITES_LDAP_CLASS = 1 << 6
    } 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_ACTIONS` |
`BROWSER_FAVORITES_LDAP_DN` |
`BROWSER_FAVORITES_LDAP_CLASS` |

### BROWSER_FAVORITES_NB_TYPES

    #define BROWSER_FAVORITES_NB_TYPES 7

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

### struct BrowserFavorites

    struct BrowserFavorites;

### browser_favorites_new ()

    BrowserFavorites *  browser_favorites_new               (GdaMetaStore *store);

Creates a new BrowserFavorites object

Returns : | the new object

### browser_favorites_type_to_string ()

    const gchar *       browser_favorites_type_to_string    (BrowserFavoritesType type);

`type` : | a BrowserFavoritesType
Returns : | a string representing `type`

### 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` : | a BrowserFavorites object
`session_id` : | session ID (0)
`fav` : | a pointer to a BrowserFavoritesAttributes structure
`order_key` : | ordering key or -1 for none
`pos` : | position (ignored if `order_key` < 0)
`error` : | a place to store errors, or `NULL`

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

Delete a favorite

`bfav` : | a BrowserFavorites
`session_id` : | 0 for now
`fav` : | a pointer to a BrowserFavoritesAttributes definning which favorite to delete
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred.

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

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

### BrowserFavoriteAction

    typedef struct {
    	gint                  id;
    	gchar                *name;
    	GdaStatement         *stmt;
    	GdaSet               *params;
    	gint                  nb_bound; /* number of GdaHolders in @params which are bound
    					 * to another GdaHolder */
    } BrowserFavoriteAction;

### browser_favorites_get_actions ()

    GSList *            browser_favorites_get_actions       (BrowserFavorites *bfav,
                                                             BrowserConnection *bcnc,
                                                             GdaSet *set);

Get a list of BrowserFavoriteAction which can be executed with the data in `set`.

`bfav` : | a BrowserFavorites
`bcnc` : | a BrowserConnection
`set` : | a GdaSet
Returns : | a new list of BrowserFavoriteAction, free list with `browser_favorites_free_actions()`

### browser_favorites_free_action ()

    void                browser_favorites_free_action       (BrowserFavoriteAction *action);

Frees `action`

`action` : | a BrowserFavoriteAction, or `NULL`

### browser_favorites_free_actions_list ()

    void                browser_favorites_free_actions_list (GSList *actions_list);

Free a list of BrowserFavoriteAction (frees the list and each BrowserFavoriteAction)

`actions_list` : | a list of BrowserFavoriteAction, or `NULL`

## Signal Details

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

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

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