## STHandler

STHandler — an object for handling a stream directory.

## Synopsis

    struct      STHandler;
    enum        STHandlerFlags;
    enum        STHandlerStockField;
    enum        STHandlerEvent;
    gboolean    (*STHandlerReloadCallback)      (STCategory *category,
                                                 GNode **categories,
                                                 GList **streams,
                                                 gpointer data,
                                                 GError **err);
    gboolean    (*STHandlerReloadMultipleCallback)
                                                (GNode **categories,
                                                 GHashTable **streams,
                                                 gpointer data,
                                                 GError **err);
    STCategory* (*STCategoryNewCallback)        (gpointer data);
    void        (*STCategoryFreeCallback)       (STCategory *category,
                                                 gpointer data);
    STStream*   (*STStreamNewCallback)          (gpointer data);
    void        (*STStreamFieldGetCallback)     (STStream *stream,
                                                 STHandlerField *field,
                                                 GValue *value,
                                                 gpointer data);
    void        (*STStreamFieldSetCallback)     (STStream *stream,
                                                 STHandlerField *field,
                                                 const GValue *value,
                                                 gpointer data);
    gboolean    (*STStreamModifyCallback)       (STStream *stream,
                                                 GSList *fields,
                                                 GSList *values,
                                                 gpointer data,
                                                 GError **err);
    gboolean    (*STStreamDeleteCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);
    void        (*STStreamFreeCallback)         (STStream *stream,
                                                 gpointer data);
    gboolean    (*STStreamResolveCallback)      (STStream *stream,
                                                 gpointer data,
                                                 GError **err);
    gboolean    (*STStreamTuneInCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);
    gboolean    (*STStreamRecordCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);
    gboolean    (*STStreamBrowseCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);
    gpointer    (*STThreadBeginCallback)        (gpointer data);
    void        (*STThreadEndCallback)          (gpointer thread_data,
                                                 gpointer data);
    gboolean    (*STStreamTuneInMultipleCallback)
                                                (GSList *streams,
                                                 gpointer data,
                                                 GError **err);
    void        (*STStreamStockFieldGetCallback)
                                                (STStream *stream,
                                                 STHandlerStockField stock_field,
                                                 GValue *value,
                                                 gpointer data);
    GtkWidget*  (*STHandlerPreferencesWidgetNewCallback)
                                                (gpointer data);
    STHandler*  st_handler_new                  (const char *name);
    STHandler*  st_handler_new_from_plugin      (STPlugin *plugin);
    void        st_handler_set_label            (STHandler *handler,
                                                 const char *label);
    void        st_handler_set_description      (STHandler *handler,
                                                 const char *description);
    void        st_handler_set_home             (STHandler *handler,
                                                 const char *home);
    void        st_handler_set_icon_from_pixbuf (STHandler *handler,
                                                 GdkPixbuf *pixbuf);
    void        st_handler_set_stock_categories (STHandler *handler,
                                                 GNode *categories);
    void        st_handler_set_flags            (STHandler *handler,
                                                 STHandlerFlags flags);
    void        st_handler_set_stream_version   (STHandler *handler,
                                                 int version);
    void        st_handler_add_field            (STHandler *handler,
                                                 STHandlerField *field);
    void        st_handler_bind                 (STHandler *handler,
                                                 STHandlerEvent event,
                                                 gpointer cb,
                                                 gpointer data);
    void        st_handler_notice               (STHandler *handler,
                                                 const char *format,
                                                 ...);
    void        st_handler_config_register      (STHandler *handler,
                                                 GParamSpec *pspec);
    GParamSpec* st_handler_config_lookup        (STHandler *handler,
                                                 const char *key);
    void        (*STHandlerConfigForeachCallback)
                                                (GParamSpec *pspec,
                                                 const GValue *value,
                                                 gpointer data);
    void        st_handler_config_foreach       (STHandler *handler,
                                                 STHandlerConfigForeachCallback cb,
                                                 gpointer data);
    void        st_handler_config_get_value     (STHandler *handler,
                                                 const char *key,
                                                 GValue *value);
    void        st_handler_config_set_value     (STHandler *handler,
                                                 const char *key,
                                                 const GValue *value);
    gboolean    st_handler_config_get_boolean   (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_boolean   (STHandler *handler,
                                                 const char *key,
                                                 gboolean value);
    int         st_handler_config_get_int       (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_int       (STHandler *handler,
                                                 const char *key,
                                                 int value);
    unsigned int st_handler_config_get_uint     (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_uint      (STHandler *handler,
                                                 const char *key,
                                                 unsigned int value);
    double      st_handler_config_get_double    (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_double    (STHandler *handler,
                                                 const char *key,
                                                 double value);
    char*       st_handler_config_get_string    (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_string    (STHandler *handler,
                                                 const char *key,
                                                 const char *value);
    GValueArray* st_handler_config_get_value_array
                                                (STHandler *handler,
                                                 const char *key);
    void        st_handler_config_set_value_array
                                                (STHandler *handler,
                                                 const char *key,
                                                 const GValueArray *value);
    void        st_handler_set_copyright        (STHandler *handler,
                                                 const char *copyright);
    void        st_handler_set_info             (STHandler *handler,
                                                 const char *label,
                                                 const char *copyright);
    void        st_handler_set_icon             (STHandler *handler,
                                                 int size,
                                                 const guint8 *data);
    void        st_handler_set_icon_from_inline (STHandler *handler,
                                                 int size,
                                                 const guint8 *data);
    gboolean    st_handler_set_icon_from_file   (STHandler *handler,
                                                 const char *filename,
                                                 GError **err);
    #define     ST_HANDLER_EVENT_REFRESH
    #define     ST_HANDLER_EVENT_REFRESH_MULTIPLE
    #define     N_ST_HANDLER_EVENTS
    typedef     STHandlerRefreshCallback;
    typedef     STHandlerRefreshMultipleCallback;

## Description

## Details

### struct STHandler

    struct STHandler {

      GObject		object;

      STHandlerPrivate	*priv;
    };

### enum STHandlerFlags

    typedef enum
    {
      ST_HANDLER_NO_CATEGORIES		= 1 << 0,
      ST_HANDLER_CONFIRM_DELETION		= 1 << 1
    } STHandlerFlags;

`ST_HANDLER_NO_CATEGORIES` | specifies that the handler has no categories. There will be no left pane in the handler tab.
`ST_HANDLER_CONFIRM_DELETION` | specifies that the user should be prompted for confirmation before deleting a stream.

### enum STHandlerStockField

    typedef enum
    {
      ST_HANDLER_STOCK_FIELD_NAME,
      ST_HANDLER_STOCK_FIELD_GENRE,
      ST_HANDLER_STOCK_FIELD_DESCRIPTION,
      ST_HANDLER_STOCK_FIELD_HOMEPAGE,
      ST_HANDLER_STOCK_FIELD_URI_LIST
    } STHandlerStockField;

`ST_HANDLER_STOCK_FIELD_NAME` | the stream name, of type G_TYPE_STRING
`ST_HANDLER_STOCK_FIELD_GENRE` | the stream genre, of type G_TYPE_STRING
`ST_HANDLER_STOCK_FIELD_DESCRIPTION` | the stream description, of type G_TYPE_STRING
`ST_HANDLER_STOCK_FIELD_HOMEPAGE` | the stream homepage URL, of type G_TYPE_STRING
`ST_HANDLER_STOCK_FIELD_URI_LIST` | the stream listen URL list, of type G_TYPE_VALUE_ARRAY

### enum STHandlerEvent

    typedef enum
    {
      ST_HANDLER_EVENT_RELOAD,

      ST_HANDLER_EVENT_STREAM_NEW,
      ST_HANDLER_EVENT_STREAM_FIELD_GET,
      ST_HANDLER_EVENT_STREAM_FIELD_SET,
      ST_HANDLER_EVENT_STREAM_FREE,

      ST_HANDLER_EVENT_STREAM_TUNE_IN,
      ST_HANDLER_EVENT_STREAM_RECORD,
      ST_HANDLER_EVENT_STREAM_BROWSE,

      ST_HANDLER_EVENT_CATEGORY_NEW,
      ST_HANDLER_EVENT_CATEGORY_FREE,

      ST_HANDLER_EVENT_THREAD_BEGIN,
      ST_HANDLER_EVENT_THREAD_END,

      ST_HANDLER_EVENT_STREAM_TUNE_IN_MULTIPLE,
      ST_HANDLER_EVENT_RELOAD_MULTIPLE,

      ST_HANDLER_EVENT_STREAM_MODIFY,
      ST_HANDLER_EVENT_STREAM_DELETE,

      ST_HANDLER_EVENT_STREAM_STOCK_FIELD_GET,
      ST_HANDLER_EVENT_STREAM_RESOLVE,

      ST_HANDLER_EVENT_PREFERENCES_WIDGET_NEW,

      ST_HANDLER_N_EVENTS
    } STHandlerEvent;

`ST_HANDLER_EVENT_RELOAD` | see STHandlerReloadCallback.
`ST_HANDLER_EVENT_STREAM_NEW` | see STStreamNewCallback.
`ST_HANDLER_EVENT_STREAM_FIELD_GET` | see STStreamFieldGetCallback.
`ST_HANDLER_EVENT_STREAM_FIELD_SET` | see STStreamFieldSetCallback.
`ST_HANDLER_EVENT_STREAM_FREE` | see STStreamFreeCallback.
`ST_HANDLER_EVENT_STREAM_TUNE_IN` | see STStreamTuneInCallback.
`ST_HANDLER_EVENT_STREAM_RECORD` | see STStreamRecordCallback.
`ST_HANDLER_EVENT_STREAM_BROWSE` | see STStreamBrowseCallback.
`ST_HANDLER_EVENT_CATEGORY_NEW` | see STCategoryNewCallback.
`ST_HANDLER_EVENT_CATEGORY_FREE` | see STCategoryFreeCallback.
`ST_HANDLER_EVENT_THREAD_BEGIN` | see STThreadBeginCallback.
`ST_HANDLER_EVENT_THREAD_END` | see STThreadEndCallback.
`ST_HANDLER_EVENT_STREAM_TUNE_IN_MULTIPLE` | see STStreamTuneInMultipleCallback.
`ST_HANDLER_EVENT_RELOAD_MULTIPLE` | see STHandlerReloadMultipleCallback.
`ST_HANDLER_EVENT_STREAM_MODIFY` | see STStreamModifyCallback.
`ST_HANDLER_EVENT_STREAM_DELETE` | see STStreamDeleteCallback.
`ST_HANDLER_EVENT_STREAM_STOCK_FIELD_GET` | see STStreamStockFieldGetCallback.
`ST_HANDLER_EVENT_STREAM_RESOLVE` | see STStreamResolveCallback.
`ST_HANDLER_EVENT_PREFERENCES_WIDGET_NEW` | see STHandlerPreferencesWidgetNewCallback.
`ST_HANDLER_N_EVENTS` |

### STHandlerReloadCallback ()

    gboolean    (*STHandlerReloadCallback)      (STCategory *category,
                                                 GNode **categories,
                                                 GList **streams,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_RELOAD.

The function will be called to reload the list of categories and the contents of a specific category, and should store a tree of categories at `categories`, and a list of streams for `category` at `streams` (you are giving the ownership of `categories` and `streams` to streamtuner, which will free them when no longer needed).

Note that if ST_HANDLER_EVENT_RELOAD_MULTIPLE is bound, this function will not be called, since ST_HANDLER_EVENT_RELOAD_MULTIPLE has priority over ST_HANDLER_EVENT_RELOAD.

`category` : | the category to reload.
`categories` : | a location to store a GNode of categories.
`streams` : | a location to store a GList of streams for `category`.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the reload was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STHandlerReloadMultipleCallback ()

    gboolean    (*STHandlerReloadMultipleCallback)
                                                (GNode **categories,
                                                 GHashTable **streams,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_RELOAD_MULTIPLE.

The function will be called to reload the list of categories and streams of a directory, and should store a tree of categories at `categories`, and a hash table of streams at `streams` (you are giving the ownership of `categories` and `streams` to streamtuner, which will free them when no longer needed).

`categories` : | a location to store a GNode of categories.
`streams` : | a location to store a GHashTable containing all the streams of the directory. The hash table must contain string/GList key/value pairs, where the string is the name of a category, and the GList is the list of streams for that category. The ownership of the hash table is given to streamtuner, which will destroy it using `g_hash_table_destroy()` when no longer needed. If you intend to use allocated strings as keys, create the hash table using g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL). However, never supply a destructor for the values, as streamtuner will take care of them.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the reload was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STCategoryNewCallback ()

    STCategory* (*STCategoryNewCallback)        (gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_CATEGORY_NEW.

The function is used to subclass STCategory.

`data` : | data passed to `st_handler_bind()`.
Returns : | the function should return a new STCategory.

### STCategoryFreeCallback ()

    void        (*STCategoryFreeCallback)       (STCategory *category,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_CATEGORY_FREE.

This function will be called to destroy a category.

`category` : | a category to free.
`data` : | data passed to `st_handler_bind()`.

### STStreamNewCallback ()

    STStream*   (*STStreamNewCallback)          (gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_NEW.

The function is used to subclass STStream.

`data` : | data passed to `st_handler_bind()`.
Returns : | the function should return a new STStream.

### STStreamFieldGetCallback ()

    void        (*STStreamFieldGetCallback)     (STStream *stream,
                                                 STHandlerField *field,
                                                 GValue *value,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_FIELD_GET.

The function will be called when streamtuner needs to get the value of a stream field.

`stream` : | a stream.
`field` : | a field to get the value of.
`value` : | a value (initialized to the type of `field`) to store the field value in.
`data` : | data passed to `st_handler_bind()`.

### STStreamFieldSetCallback ()

    void        (*STStreamFieldSetCallback)     (STStream *stream,
                                                 STHandlerField *field,
                                                 const GValue *value,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_FIELD_SET.

The function will be called when streamtuner needs to set the value of a stream field.

`stream` : | a stream.
`field` : | a field to set the value of.
`value` : | a value to set the value field from. The type of the value is the one passed to `st_handler_field_new()`.
`data` : | data passed to `st_handler_bind()`.

### STStreamModifyCallback ()

    gboolean    (*STStreamModifyCallback)       (STStream *stream,
                                                 GSList *fields,
                                                 GSList *values,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_MODIFY.

The function will be called when the user modifies a stream. The first element of `values` is the value of the first element of `fields`, and so on.

`stream` : | a stream.
`fields` : | a list of STHandlerField fields to modify.
`values` : | a list of GValue values for `fields`.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error. In such case it should also set `err`.

### STStreamDeleteCallback ()

    gboolean    (*STStreamDeleteCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_DELETE.

The function will be called when the user deletes a stream. If the ST_HANDLER_CONFIRM_DELETION flag is set, the function will only be called if the user confirms the stream deletion.

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error. In such case it should also set `err`.

### STStreamFreeCallback ()

    void        (*STStreamFreeCallback)         (STStream *stream,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_FREE.

This function will be called to destroy a stream.

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.

### STStreamResolveCallback ()

    gboolean    (*STStreamResolveCallback)      (STStream *stream,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_RESOLVE.

The function will be called when streamtuner needs to resolve `stream` (streams should be resolved before they are bookmarked).

The function should resolve the stream in a handler-specific way (for instance, it should connect to the stream directory server and retrieve the stream URL).

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the task was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STStreamTuneInCallback ()

    gboolean    (*STStreamTuneInCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_TUNE_IN.

The function will be called when the user tunes into `stream`, and should perform the action needed to tune into `stream`.

Note that if ST_HANDLER_EVENT_STREAM_TUNE_IN_MULTIPLE is bound, this function will not be called, since ST_HANDLER_EVENT_STREAM_TUNE_IN_MULTIPLE has priority over ST_HANDLER_EVENT_STREAM_TUNE_IN.

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the task was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STStreamRecordCallback ()

    gboolean    (*STStreamRecordCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_RECORD.

The function will be called when the user records `stream`, and should perform the action needed to record `stream`.

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the task was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STStreamBrowseCallback ()

    gboolean    (*STStreamBrowseCallback)       (STStream *stream,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_BROWSE.

The function will be called when the user browses the web page of `stream`, and should perform the action needed to browse the web page of `stream`.

`stream` : | a stream.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the task was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STThreadBeginCallback ()

    gpointer    (*STThreadBeginCallback)        (gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_THREAD_BEGIN.

The function will be called after a new thread of execution has been spawned.

`data` : | data passed to `st_handler_bind()`.
Returns : | the returned value will be passed to `STThreadEndCallback()` when the thread is about to exit.

### STThreadEndCallback ()

    void        (*STThreadEndCallback)          (gpointer thread_data,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_THREAD_END.

The function will be called when a thread of execution is about to exit.

`thread_data` : | data returned by `STThreadBeginCallback()`.
`data` : | data passed to `st_handler_bind()`.

### STStreamTuneInMultipleCallback ()

    gboolean    (*STStreamTuneInMultipleCallback)
                                                (GSList *streams,
                                                 gpointer data,
                                                 GError **err);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_TUNE_IN_MULTIPLE.

The function will be called when the user tunes into `streams`, and should perform the action needed to tune into `streams`.

`streams` : | a list of STStream streams.
`data` : | data passed to `st_handler_bind()`.
`err` : | a location to store errors.
Returns : | the function should return `FALSE` if there was an error, or if the task was cancelled by the user. Additionally, if there was an error, `err` must be set.

### STStreamStockFieldGetCallback ()

    void        (*STStreamStockFieldGetCallback)
                                                (STStream *stream,
                                                 STHandlerStockField stock_field,
                                                 GValue *value,
                                                 gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_STREAM_STOCK_FIELD_GET.

The function will be called when streamtuner needs to get the value of a stream stock field.

`stream` : | a stream.
`stock_field` : | a stock field to get the value of.
`value` : | a value (initialized to the type of `stock_field`) to store the stock field value in.
`data` : | data passed to `st_handler_bind()`.

### STHandlerPreferencesWidgetNewCallback ()

    GtkWidget*  (*STHandlerPreferencesWidgetNewCallback)
                                                (gpointer data);

Specifies the type of function to bind to ST_HANDLER_EVENT_PREFERENCES_WIDGET_NEW.

If a function is bound to the ST_HANDLER_EVENT_PREFERENCES_WIDGET_NEW event, a page containing the returned widget will be available in the streamtuner preferences.

`data` : | data passed to `st_handler_bind()`.
Returns : | the function should return a new GtkWidget.

### st_handler_new ()

    STHandler*  st_handler_new                  (const char *name);

Creates a new STHandler. After creating the handler, you must set its label using `st_handler_set_label()`, add your stream fields using `st_handler_add_field()`, and bind functions to events using `st_handler_bind()`.

Functions must be bound to ST_HANDLER_EVENT_STREAM_FIELD_GET and ST_HANDLER_EVENT_STREAM_FIELD_SET. Additionally, if one of the fields added with `st_handler_add_field()` has the ST_HANDLER_FIELD_EDITABLE flag set, a function must be bound to ST_HANDLER_EVENT_STREAM_MODIFY.

`name` : | the name of the handler.
Returns : | the newly created STHandler.

### st_handler_new_from_plugin ()

    STHandler*  st_handler_new_from_plugin      (STPlugin *plugin);

Creates a new STHandler, using the name, label and icon of `plugin`. You must set the name and label of `plugin` before calling this function.

`plugin` : | a plugin to take the name, label and icon from.
Returns : | the newly created STHandler.

### st_handler_set_label ()

    void        st_handler_set_label            (STHandler *handler,
                                                 const char *label);

Sets the handler label, which will be used in the handler tab, and in various other places of the user interface.

`handler` : | a handler.
`label` : | the handler label.

### st_handler_set_description ()

    void        st_handler_set_description      (STHandler *handler,
                                                 const char *description);

Sets the handler description, which will be displayed in the toolbar when the handler is selected.

`handler` : | a handler.
`description` : | the handler description.

### st_handler_set_home ()

    void        st_handler_set_home             (STHandler *handler,
                                                 const char *home);

Sets the home page URL of the directory handled by `handler`. Setting the home page URL will allow the user to visit the page by clicking on the toolbar link.

`handler` : | a handler.
`home` : | the handler home page URL.

### st_handler_set_icon_from_pixbuf ()

    void        st_handler_set_icon_from_pixbuf (STHandler *handler,
                                                 GdkPixbuf *pixbuf);

Sets the handler icon from a GdkPixbuf.

`handler` : | a handler.
`pixbuf` : | an icon.

### st_handler_set_stock_categories ()

    void        st_handler_set_stock_categories (STHandler *handler,
                                                 GNode *categories);

Sets the handler stock categories. The "__main" category is mandatory.

Special category names: __main and __search.

The stock categories will not be saved to permanent storage.

`handler` : | a handler.
`categories` : | a tree of stock categories.

### st_handler_set_flags ()

    void        st_handler_set_flags            (STHandler *handler,
                                                 STHandlerFlags flags);

Sets the handler flags.

`handler` : | a handler.
`flags` : | the handler flags.

### st_handler_set_stream_version ()

    void        st_handler_set_stream_version   (STHandler *handler,
                                                 int version);

Sets the handler stream version.

`handler` : | a handler:
`version` : | the stream version.

### st_handler_add_field ()

    void        st_handler_add_field            (STHandler *handler,
                                                 STHandlerField *field);

Add a stream field to `handler`.

`handler` : | a handler.
`field` : | a field to add to `handler`.

### st_handler_bind ()

    void        st_handler_bind                 (STHandler *handler,
                                                 STHandlerEvent event,
                                                 gpointer cb,
                                                 gpointer data);

Binds callback function `cb` to event `event`. If a function is already bound to `cb`, the previous binding will be overriden (only one function can be bound to an event).

`handler` : | a handler.
`event` : | an event to bind `cb` to.
`cb` : | a callback function to bind to `event`.
`data` : | data to pass to `cb`.

### st_handler_notice ()

    void        st_handler_notice               (STHandler *handler,
                                                 const char *format,
                                                 ...);

Outputs a formatted handler notice to the standard error output.

`handler` : | a handler.
`format` : | the message format. See the `printf()` documentation.
`...` : | the parameters to insert into the format string.

### st_handler_config_register ()

    void        st_handler_config_register      (STHandler *handler,
                                                 GParamSpec *pspec);

Registers a new configuration key.

`handler` : | a handler.
`pspec` : | a param spec defining the configuration key to register. The param spec value type must be G_TYPE_BOOLEAN, G_TYPE_INT, G_TYPE_UINT, G_TYPE_DOUBLE, G_TYPE_STRING or G_TYPE_VALUE_ARRAY. The param spec flags must be G_PARAM_READWRITE.

### st_handler_config_lookup ()

    GParamSpec* st_handler_config_lookup        (STHandler *handler,
                                                 const char *key);

Looks up the GParamSpec of a configuration key.

`handler` : | a handler.
`key` : | a configuration key.
Returns : | the GParamSpec of `key`, or `NULL` if no such configuration key exists.

### STHandlerConfigForeachCallback ()

    void        (*STHandlerConfigForeachCallback)
                                                (GParamSpec *pspec,
                                                 const GValue *value,
                                                 gpointer data);

Specifies the type of function to pass to `st_handler_config_foreach()`. The function will be called for each key/value pair in the handler configuration database.

`pspec` : | the param spec of the configuration key.
`value` : | the value of the configuration key.
`data` : | data passed to `st_handler_config_foreach()`.

### st_handler_config_foreach ()

    void        st_handler_config_foreach       (STHandler *handler,
                                                 STHandlerConfigForeachCallback cb,
                                                 gpointer data);

Calls the given function for each key/value pair in the configuration database of `handler`. You must not call any other st_handler_config_* function while iterating over the database.

`handler` : | a handler.
`cb` : | a function to call for each key/value pair.
`data` : | data to pass to `cb`.

### st_handler_config_get_value ()

    void        st_handler_config_get_value     (STHandler *handler,
                                                 const char *key,
                                                 GValue *value);

Gets a configuration value. `value` must be zero-filled (but not initialized), and should be unset with `g_value_unset()` when no longer needed.

`handler` : | a handler.
`key` : | a configuration key previously registered with `st_handler_config_register()`.
`value` : | a location to copy the value of `key` to.

### st_handler_config_set_value ()

    void        st_handler_config_set_value     (STHandler *handler,
                                                 const char *key,
                                                 const GValue *value);

Sets a configuration value. `value` must match the value type of the param spec of `key`.

`handler` : | a handler.
`key` : | a configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_boolean ()

    gboolean    st_handler_config_get_boolean   (STHandler *handler,
                                                 const char *key);

Gets a boolean configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_BOOLEAN configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`.

### st_handler_config_set_boolean ()

    void        st_handler_config_set_boolean   (STHandler *handler,
                                                 const char *key,
                                                 gboolean value);

Sets a boolean configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_BOOLEAN configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_int ()

    int         st_handler_config_get_int       (STHandler *handler,
                                                 const char *key);

Gets a signed integer configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_INT configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`.

### st_handler_config_set_int ()

    void        st_handler_config_set_int       (STHandler *handler,
                                                 const char *key,
                                                 int value);

Sets a signed integer configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_INT configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_uint ()

    unsigned int st_handler_config_get_uint     (STHandler *handler,
                                                 const char *key);

Gets an unsigned integer configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_UINT configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`.

### st_handler_config_set_uint ()

    void        st_handler_config_set_uint      (STHandler *handler,
                                                 const char *key,
                                                 unsigned int value);

Sets an unsigned integer configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_UINT configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_double ()

    double      st_handler_config_get_double    (STHandler *handler,
                                                 const char *key);

Gets a double configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_DOUBLE configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`.

### st_handler_config_set_double ()

    void        st_handler_config_set_double    (STHandler *handler,
                                                 const char *key,
                                                 double value);

Sets a double configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_DOUBLE configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_string ()

    char*       st_handler_config_get_string    (STHandler *handler,
                                                 const char *key);

Gets a string configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_STRING configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`. The value should be freed when no longer needed.

### st_handler_config_set_string ()

    void        st_handler_config_set_string    (STHandler *handler,
                                                 const char *key,
                                                 const char *value);

Sets a string configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_STRING configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_config_get_value_array ()

    GValueArray* st_handler_config_get_value_array
                                                (STHandler *handler,
                                                 const char *key);

Gets a value array configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_VALUE_ARRAY configuration key previously registered with `st_handler_config_register()`.
Returns : | the value of `key`. The value should be freed with `g_value_array_free()` when no longer needed.

### st_handler_config_set_value_array ()

    void        st_handler_config_set_value_array
                                                (STHandler *handler,
                                                 const char *key,
                                                 const GValueArray *value);

Sets a value array configuration value.

`handler` : | a handler.
`key` : | a G_TYPE_VALUE_ARRAY configuration key previously registered with `st_handler_config_register()`.
`value` : | the value to set.

### st_handler_set_copyright ()

    void        st_handler_set_copyright        (STHandler *handler,
                                                 const char *copyright);

### Warning

`st_handler_set_copyright` is deprecated and should not be used in newly-written code.

`handler` : |
`copyright` : |

### st_handler_set_info ()

    void        st_handler_set_info             (STHandler *handler,
                                                 const char *label,
                                                 const char *copyright);

### Warning

`st_handler_set_info` is deprecated and should not be used in newly-written code.

`handler` : |
`label` : |
`copyright` : |

### st_handler_set_icon ()

    void        st_handler_set_icon             (STHandler *handler,
                                                 int size,
                                                 const guint8 *data);

### Warning

`st_handler_set_icon` is deprecated and should not be used in newly-written code.

`handler` : |
`size` : |
`data` : |

### st_handler_set_icon_from_inline ()

    void        st_handler_set_icon_from_inline (STHandler *handler,
                                                 int size,
                                                 const guint8 *data);

### Warning

`st_handler_set_icon_from_inline` is deprecated and should not be used in newly-written code.

Sets the handler icon using inline data. See the `gdk_pixbuf_new_from_inline()` documentation.

`handler` : | a handler.
`size` : | the size of the inline data.
`data` : | the inline data.

### st_handler_set_icon_from_file ()

    gboolean    st_handler_set_icon_from_file   (STHandler *handler,
                                                 const char *filename,
                                                 GError **err);

### Warning

`st_handler_set_icon_from_file` is deprecated and should not be used in newly-written code.

Sets the handler icon using an external file. See the `gdk_pixbuf_new_from_file()` documentation.

`handler` : | a handler.
`filename` : | an icon file.
`err` : | a location to store errors, or `NULL`.
Returns : | `FALSE` if the file could not be loaded. In such case `err` will be set.

### ST_HANDLER_EVENT_REFRESH

    #define ST_HANDLER_EVENT_REFRESH		ST_HANDLER_EVENT_RELOAD

### Warning

`ST_HANDLER_EVENT_REFRESH` is deprecated and should not be used in newly-written code.

### ST_HANDLER_EVENT_REFRESH_MULTIPLE

    #define ST_HANDLER_EVENT_REFRESH_MULTIPLE	ST_HANDLER_EVENT_RELOAD_MULTIPLE

### Warning

`ST_HANDLER_EVENT_REFRESH_MULTIPLE` is deprecated and should not be used in newly-written code.

### N_ST_HANDLER_EVENTS

    #define N_ST_HANDLER_EVENTS			ST_HANDLER_N_EVENTS

### Warning

`N_ST_HANDLER_EVENTS` is deprecated and should not be used in newly-written code.

### STHandlerRefreshCallback

    typedef STHandlerReloadCallback			STHandlerRefreshCallback;

### Warning

`STHandlerRefreshCallback` is deprecated and should not be used in newly-written code.

### STHandlerRefreshMultipleCallback

    typedef STHandlerReloadMultipleCallback		STHandlerRefreshMultipleCallback;

### Warning

`STHandlerRefreshMultipleCallback` is deprecated and should not be used in newly-written code.

## See Also

STCategory, STHandlerField, st-handlers, STPlugin, st-state, STStream