-------------------------------------------------------------------------------
 To-do list for streamtuner
-------------------------------------------------------------------------------

Search this file for the token APIBREAK to know what to implement at
the next API break.

Stability, correctness

	- use GError domains and codes
	  there will be one error code for ABORT
	  (which isn't really an error) (APIBREAK?)

	- use threads to make a poll transfer API

	- better object oriented design through the use of GObject
	  class hierarchy (APIBREAK):

		STObject
		  |
		   -->	STHandler
		  |
		   -->	STViewable
			  |
			   -->	STCategory
			  |
			   -->	STStream

	- fix possible leaks using Boehm gc

	- we must have something like (APIBREAK):

		gboolean plugin_init (STPlugin *plugin, GError **err)

	  and:

		st_plugin_add_handler (STPlugin *plugin, STHandler *handler)
		st_plugin_add_action (STPlugin *plugin, const char *id, const char *label, const char *command)
			(that should add an action to the global actions
			 hash table, or increment the refcount of an already
			 existing entry in the hash table)
		st_plugin_set_about_text (STPlugin *plugin, const char *text)

	  this will allow to unload a plugin cleanly, removing
	  all its handlers and programs

Features, completeness

	- (APIBREAK)

	  Conceptually, a stream can be compared to a hostname/ip pair: the raw
	  stream object in memory is the "hostname", and it can be translated
	  into an "IP address" (the URI list of the stream, needed to play the
	  stream, view its website, etc) by using its plugin magic (actually,
	  the plugins do that internally in their tune in, browse or record
	  callbacks).

	  So, we introduce:

		typedef struct
		{
			GSList	*audio;		/* list of mp3/ogg/... URIs */
			GSList	*documents;	/* list of html URIs */
		} STResolvedStream;		/* think of a better name */

	  and a new stream event:

		ST_HANDLER_EVENT_STREAM_RESOLVE

	  whose callback is prototyped as:

		typedef gboolean (Callback) (STStream	*stream,
					     GError	*err)
	
	  It'll resolve and fill the new STStream->resolved member
	  (just a pointer to a STResolvedStream structure).
	  If the STStream is already resolved (->resolved is not null),
	  then it'll of course do nothing.
		  
	  Some handlers (such as Live365) will fill the ->resolved member upon
	  stream creation, some others with slow resolving (SHOUTcast) will
	  fill it on demand only.

	  This would allow us to:

		- obsolete ST_HANDLER_EVENT_STREAM_{TUNE_IN|RECORD|BROWSE}:
		  streamtuner would handle these functions by calling
		  the appropriate program on a STResolvedStream

	- (APIBREAK): implement a stream notion of "label field": this would
	  be the field used as default for a bookmark name, for instance

	- The new API should be truly signal based: it would allow us to
	  bind to signals in the shell code, for instance:

		g_signal_connect(G_OBJECT(handler), "stream-selected",
				 st_browser_window_stream_selected_h, NULL);

		void st_browser_window_stream_selected_h (STHandler *handler,
							  STStream *stream,
							  gpointer data)
		{
			st_toolbar_update_sensitivity(window->toolbar);
			st_menubar_update_sensitivity(window->menubar);
		}

	  and shell signals:

		g_signal_connect(G_OBJECT(shell),
				 "stream-selected",
				 st_stream_properties_dialog_stream_selected_h,
				 shell->stream_properties_dialog);

		void st_stream_properties_dialog_stream_selected_h (STShell *shell,
								    STStream *stream,
								    gpointer data)
		{
			STStreamPropertiesDialog *dialog = data;
			st_stream_properties_dialog_set_stream(dialog, stream);
		}

	- go for GNOME? atm the advantages i see of using GNOME would be:
		- GNOME-wide proxy settings
		- GNOME-wide toolbar and menu settings
		- use GNOME instead of st-action
		- GNOME argv parsing and --help display
		- rest of the GNOME things, such as GNOME about dialog,
		  GNOME dialogs etc

	- write plugin API reference

	- plugins must be able to register their own settings

	- add cache settings
	- the cache code should be rewritten with performance in mind:
		- load a category-specific cache file only when refreshing
		  that category for the first time
		- save a cache file upon each reload

	- add the ability to manually add some streams
	  (http://mail.gnu.org/archive/html/streamtuner-misc/2004-01/msg00002.html)
