st-handler-api.h

linux下网络收音机的源码

/*
 * Copyright (c) 2002, 2003, 2004 Jean-Yves Lefort
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of Jean-Yves Lefort nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _ST_HANDLER_API_H
#define _ST_HANDLER_API_H

#include <gtk/gtk.h>
#include <st-category-api.h>
#include <st-handler-field-api.h>
#include <st-plugin-api.h>
#include <st-stream-api.h>

G_BEGIN_DECLS

#define ST_TYPE_HANDLER			(st_handler_get_type())
#define ST_HANDLER(obj)			(G_TYPE_CHECK_INSTANCE_CAST((obj), ST_TYPE_HANDLER, STHandler))
#define ST_HANDLER_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST((klass), ST_TYPE_HANDLER, STHandlerClass))
#define ST_IS_HANDLER(obj)		(G_TYPE_CHECK_INSTANCE_TYPE((obj), ST_TYPE_HANDLER))
#define ST_IS_HANDLER_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE((klass), ST_TYPE_HANDLER))
#define ST_HANDLER_GET_CLASS(obj)	(G_TYPE_INSTANCE_GET_CLASS((obj), ST_TYPE_HANDLER, STHandlerClass))

typedef struct _STHandler		STHandler;
typedef struct _STHandlerClass		STHandlerClass;
typedef struct _STHandlerPrivate	STHandlerPrivate;

struct _STHandler
{
  GObject		object;

  STHandlerPrivate	*priv;
};
  
struct _STHandlerClass
{
  GObjectClass		parent_class;
};
  
typedef enum
{
  ST_HANDLER_NO_CATEGORIES		= 1 << 0,
  ST_HANDLER_CONFIRM_DELETION		= 1 << 1
} STHandlerFlags;

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;

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;

/**
 * STHandlerReloadCallback:
 * @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.
 *
 * 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.
 *
 * Return value: 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.
 **/
typedef gboolean   (*STHandlerReloadCallback)  (STCategory	*category,
						GNode		**categories,
						GList		**streams,
						gpointer	data,
						GError		**err);

/**
 * STHandlerReloadMultipleCallback:
 * @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.
 *
 * 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).
 *
 * Return value: 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.
 **/
typedef gboolean   (*STHandlerReloadMultipleCallback) (GNode      **categories,
						       GHashTable **streams,
						       gpointer   data,
						       GError     **err);

/**
 * STCategoryNewCallback:
 * @data: data passed to st_handler_bind().
 *
 * Specifies the type of function to bind to
 * #ST_HANDLER_EVENT_CATEGORY_NEW.
 *
 * The function is used to subclass #STCategory.
 *
 * Return value: the function should return a new #STCategory.
 **/
typedef STCategory*(*STCategoryNewCallback)    (gpointer	data);

/**
 * STCategoryFreeCallback:
 * @category: a category to free.
 * @data: data passed to st_handler_bind().
 *
 * Specifies the type of function to bind to
 * #ST_HANDLER_EVENT_CATEGORY_FREE.
 *
 * This function will be called to destroy a category.
 **/
typedef void       (*STCategoryFreeCallback)   (STCategory	*category,
						gpointer	data);

/**
 * STStreamNewCallback:
 * @data: data passed to st_handler_bind().
 *
 * Specifies the type of function to bind to
 * #ST_HANDLER_EVENT_STREAM_NEW.
 *
 * The function is used to subclass #STStream.
 *
 * Return value: the function should return a new #STStream.
 **/
typedef STStream*  (*STStreamNewCallback)      (gpointer	data);

/**
 * STStreamFieldGetCallback:
 * @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().
 *
 * 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.
 **/
typedef void	   (*STStreamFieldGetCallback) (STStream	*stream,
						STHandlerField	*field,
						GValue		*value,
						gpointer	data);

/**
 * STStreamFieldSetCallback:
 * @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().
 *
 * 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.
 **/
typedef void	   (*STStreamFieldSetCallback) (STStream	*stream,
						STHandlerField	*field,
						const GValue	*value,
						gpointer	data);

/**
 * STStreamModifyCallback:
 * @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.
 *
 * 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.
 *
 * Return value: the function should return %FALSE if there was an
 * error. In such case it should also set @err.
 **/
typedef gboolean   (*STStreamModifyCallback)   (STStream	*stream,
						GSList		*fields,
						GSList		*values,
						gpointer	data,
						GError		**err);

/**
 * STStreamDeleteCallback:
 * @stream: a stream.
 * @data: data passed to st_handler_bind().
 * @err: a location to store errors.
 *
 * 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.
 *
 * Return value: the function should return %FALSE if there was an
 * error. In such case it should also set @err.
 **/
typedef gboolean   (*STStreamDeleteCallback)   (STStream	*stream,
						gpointer	data,
						GError		**err);


/**
 * STStreamFreeCallback:
 * @stream: a stream.
 * @data: data passed to st_handler_bind().
 *
 * Specifies the type of function to bind to
 * #ST_HANDLER_EVENT_STREAM_FREE.
 *
 * This function will be called to destroy a stream.
 **/
typedef void	   (*STStreamFreeCallback)     (STStream	*stream,
						gpointer	data);


/**
 * STStreamResolveCallback:
 * @stream: a stream.
 * @data: data passed to st_handler_bind().
 * @err: a location to store errors.
 *
 * 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).
 *
 * Return value: 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.
 **/
typedef gboolean   (*STStreamResolveCallback)  (STStream	*stream,
						gpointer	data,
						GError		**err);

/**
 * STStreamTuneInCallback:
 * @stream: a stream.
 * @data: data passed to st_handler_bind().
 * @err: a location to store errors.
 *
 * 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.
 *
 * Return value: 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.
 **/
typedef gboolean   (*STStreamTuneInCallback)   (STStream	*stream,
						gpointer	data,
						GError		**err);

/**
 * STStreamRecordCallback:
 * @stream: a stream.
 * @data: data passed to st_handler_bind().