Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
plugin.h
Go to the documentation of this file.
00001 /*
00002  * plugin.h
00003  * Copyright 2005-2010 Audacious Development Team
00004  *
00005  * This file is part of Audacious.
00006  *
00007  * Audacious is free software: you can redistribute it and/or modify it under
00008  * the terms of the GNU General Public License as published by the Free Software
00009  * Foundation, version 2 or version 3 of the License.
00010  *
00011  * Audacious is distributed in the hope that it will be useful, but WITHOUT ANY
00012  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
00013  * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * Audacious. If not, see <http://www.gnu.org/licenses/>.
00017  *
00018  * The Audacious team does not consider modular code linking to Audacious or
00019  * using our public API to be a derived work.
00020  */
00021 
00022 #ifndef AUDACIOUS_PLUGIN_H
00023 #define AUDACIOUS_PLUGIN_H
00024 
00025 #include <audacious/api.h>
00026 #include <audacious/types.h>
00027 #include <libaudcore/audio.h>
00028 #include <libaudcore/index.h>
00029 #include <libaudcore/tuple.h>
00030 #include <libaudcore/vfs.h>
00031 
00032 /* "Magic" bytes identifying an Audacious plugin header. */
00033 #define _AUD_PLUGIN_MAGIC 0x8EAC8DE2
00034 
00035 /* API version.  Plugins are marked with this number at compile time.
00036  *
00037  * _AUD_PLUGIN_VERSION is the current version; _AUD_PLUGIN_VERSION_MIN is
00038  * the oldest one we are backward compatible with.  Plugins marked older than
00039  * _AUD_PLUGIN_VERSION_MIN or newer than _AUD_PLUGIN_VERSION are not loaded.
00040  *
00041  * Before releases that add new pointers to the end of the API tables, increment
00042  * _AUD_PLUGIN_VERSION but leave _AUD_PLUGIN_VERSION_MIN the same.
00043  *
00044  * Before releases that break backward compatibility (e.g. remove pointers from
00045  * the API tables), increment _AUD_PLUGIN_VERSION *and* set
00046  * _AUD_PLUGIN_VERSION_MIN to the same value. */
00047 
00048 #define _AUD_PLUGIN_VERSION_MIN 38 /* 3.2-alpha2 */
00049 #define _AUD_PLUGIN_VERSION     38
00050 
00051 /* A NOTE ON THREADS
00052  *
00053  * How thread-safe a plugin must be depends on the type of plugin.  Note that
00054  * some parts of the Audacious API are *not* thread-safe and therefore cannot be
00055  * used in some parts of some plugins; for example, input plugins cannot use
00056  * GUI-related calls or access the playlist except in about() and configure().
00057  *
00058  * Thread-safe plugins: transport, playlist, input, effect, and output.  These
00059  * must be mostly thread-safe.  init() and cleanup() may be called from
00060  * secondary threads; however, no other functions provided by the plugin will be
00061  * called at the same time.  about() and configure() will be called only from
00062  * the main thread.  All other functions provided by the plugin may be called
00063  * from any thread and from multiple threads simultaneously.
00064  *
00065  * Exceptions:
00066  * - Because many existing input plugins are not coded to handle simultaneous
00067  *   calls to play(), play() will only be called from one thread at a time.  New
00068  *   plugins should not rely on this exception, though.
00069  * - Some combinations of calls, especially for output and effect plugins, make
00070  *   no sense; for example, flush() in an output plugin will only be called
00071  *   after open_audio() and before close_audio().
00072  *
00073  * Single-thread plugins: visualization, general, and interface.  Functions
00074  * provided by these plugins will only be called from the main thread. */
00075 
00076 /* CROSS-PLUGIN MESSAGES
00077  *
00078  * Since 3.2, Audacious implements a basic messaging system between plugins.
00079  * Messages are sent using aud_plugin_send_message() and received through the
00080  * take_message() method specified in the header of the receiving plugin.
00081  * Plugins that do not need to receive messages can set take_message() to NULL.
00082  *
00083  * Each message includes a code indicating the type of message, a pointer to
00084  * some data, and a value indicating the size of that data. What the message
00085  * data contains is entirely up to the two plugins involved. For this reason, it
00086  * is crucial that both plugins agree on the meaning of the message codes used.
00087  *
00088  * Once the message is sent, an integer error code is returned. If the receiving
00089  * plugin does not provide the take_message() method, ENOSYS is returned. If
00090  * take_message() does not recognize the message code, it should ignore the
00091  * message and return EINVAL. An error code of zero represents success. Other
00092  * error codes may be used with more specific meanings.
00093  *
00094  * For the time being, aud_plugin_send_message() should only be called from the
00095  * program's main thread. */
00096 
00097 #define PLUGIN_COMMON_FIELDS \
00098     int magic; /* checked against _AUD_PLUGIN_MAGIC */ \
00099     int version; /* checked against _AUD_PLUGIN_VERSION */ \
00100     int type; /* PLUGIN_TYPE_XXX */ \
00101     int size; /* size in bytes of the struct */ \
00102     const char * name; \
00103     bool_t (* init) (void); \
00104     void (* cleanup) (void); \
00105     int (* take_message) (const char * code, const void * data, int size); \
00106     void (* about) (void); \
00107     void (* configure) (void); \
00108     PluginPreferences * settings;
00109 
00110 struct _Plugin
00111 {
00112     PLUGIN_COMMON_FIELDS
00113 };
00114 
00115 struct _TransportPlugin
00116 {
00117     PLUGIN_COMMON_FIELDS
00118     const char * const * schemes; /* array ending with NULL */
00119     const VFSConstructor * vtable;
00120 };
00121 
00122 struct _PlaylistPlugin
00123 {
00124     PLUGIN_COMMON_FIELDS
00125         const char * const * extensions; /* array ending with NULL */
00126         bool_t (* load) (const char * path, VFSFile * file,
00127      char * * title, /* pooled */
00128      Index * filenames, /* of (char *), pooled */
00129      Index * tuples); /* of (Tuple *) */
00130         bool_t (* save) (const char * path, VFSFile * file, const char * title,
00131      Index * filenames, /* of (char *) */
00132      Index * tuples); /* of (Tuple *) */
00133 };
00134 
00135 struct _OutputPlugin
00136 {
00137     PLUGIN_COMMON_FIELDS
00138 
00139     /* During probing, plugins with higher priority (10 to 0) are tried first. */
00140     int probe_priority;
00141 
00142     /* Returns current volume for left and right channels (0 to 100). */
00143     void (* get_volume) (int * l, int * r);
00144 
00145     /* Changes volume for left and right channels (0 to 100). */
00146     void (* set_volume) (int l, int r);
00147 
00148     /* Begins playback of a PCM stream.  <format> is one of the FMT_*
00149      * enumeration values defined in libaudcore/audio.h.  Returns nonzero on
00150      * success. */
00151     bool_t (* open_audio) (int format, int rate, int chans);
00152 
00153     /* Ends playback.  Any buffered audio data is discarded. */
00154     void (* close_audio) (void);
00155 
00156     /* Returns how many bytes of data may be passed to a following write_audio()
00157      * call.  NULL if the plugin supports only blocking writes (not recommended). */
00158     int (* buffer_free) (void);
00159 
00160     /* Waits until buffer_free() will return a size greater than zero.
00161      * output_time(), pause(), and flush() may be called meanwhile; if flush()
00162      * is called, period_wait() should return immediately.  NULL if the plugin
00163      * supports only blocking writes (not recommended). */
00164     void (* period_wait) (void);
00165 
00166     /* Buffers <size> bytes of data, in the format given to open_audio(). */
00167     void (* write_audio) (void * data, int size);
00168 
00169     /* Waits until all buffered data has been heard by the user. */
00170     void (* drain) (void);
00171 
00172     /* Returns time count (in milliseconds) of how much data has been written. */
00173     int (* written_time) (void);
00174 
00175     /* Returns time count (in milliseconds) of how much data has been heard by
00176      * the user. */
00177     int (* output_time) (void);
00178 
00179     /* Pauses the stream if <p> is nonzero; otherwise unpauses it.
00180      * write_audio() will not be called while the stream is paused. */
00181     void (* pause) (bool_t p);
00182 
00183     /* Discards any buffered audio data and sets the time counter (in
00184      * milliseconds) of data written. */
00185     void (* flush) (int time);
00186 
00187     /* Sets the time counter (in milliseconds) of data written without
00188      * discarding any buffered audio data.  If <time> is less than the amount of
00189      * buffered data, following calls to output_time() will return negative
00190      * values. */
00191     void (* set_written_time) (int time);
00192 };
00193 
00194 struct _EffectPlugin
00195 {
00196     PLUGIN_COMMON_FIELDS
00197 
00198     /* All processing is done in floating point.  If the effect plugin wants to
00199      * change the channel count or sample rate, it can change the parameters
00200      * passed to start().  They cannot be changed in the middle of a song. */
00201     void (* start) (int * channels, int * rate);
00202 
00203     /* process() has two options: modify the samples in place and leave the data
00204      * pointer unchanged or copy them into a buffer of its own.  If it sets the
00205      * pointer to dynamically allocated memory, it is the plugin's job to free
00206      * that memory.  process() may return different lengths of audio than it is
00207      * passed, even a zero length. */
00208     void (* process) (float * * data, int * samples);
00209 
00210     /* A seek is taking place; any buffers should be discarded. */
00211     void (* flush) (void);
00212 
00213     /* Exactly like process() except that any buffers should be drained (i.e.
00214      * the data processed and returned).  finish() will be called a second time
00215      * at the end of the last song in the playlist. */
00216     void (* finish) (float * * data, int * samples);
00217 
00218     /* Optional.  For effects that change the length of the song, these
00219      * functions allow the correct time to be displayed. */
00220     int (* decoder_to_output_time) (int time);
00221     int (* output_to_decoder_time) (int time);
00222 
00223     /* Effects with lowest order (0 to 9) are applied first. */
00224     int order;
00225 
00226     /* If the effect does not change the number of channels or the sampling
00227      * rate, it can be enabled and disabled more smoothly. */
00228     bool_t preserves_format;
00229 };
00230 
00231 struct OutputAPI
00232 {
00233     /* In a multi-thread plugin, only one of these functions may be called at
00234      * once (but see pause and abort_write for exceptions to this rule). */
00235 
00236     /* Prepare the output system for playback in the specified format.  Returns
00237      * nonzero on success.  If the call fails, no other output functions may be
00238      * called. */
00239     int (* open_audio) (int format, int rate, int channels);
00240 
00241     /* Informs the output system of replay gain values for the current song so
00242      * that volume levels can be adjusted accordingly, if the user so desires.
00243      * This may be called at any time during playback should the values change. */
00244     void (* set_replaygain_info) (ReplayGainInfo * info);
00245 
00246     /* Pass audio data to the output system for playback.  The data must be in
00247      * the format passed to open_audio, and the length (in bytes) must be an
00248      * integral number of frames.  This function blocks until all the data has
00249      * been written (though it may not yet be heard by the user); if the output
00250      * system is paused; this may be indefinitely.  See abort_write for a way to
00251      * interrupt a blocked call. */
00252     void (* write_audio) (void * data, int length);
00253 
00254     /* End playback.  Any audio data currently buffered by the output system
00255      * will be discarded.  After the call, no other output functions, except
00256      * open_audio, may be called. */
00257     void (* close_audio) (void);
00258 
00259     /* Pause or unpause playback.  This function may be called during a call to
00260      * write_audio, in which write_audio will block until playback is unpaused
00261      * (but see abort_write to prevent the call from blocking). */
00262     void (* pause) (bool_t pause);
00263 
00264     /* Discard any audio data currently buffered by the output system, and set
00265      * the time counter to a new value.  This function is intended to be used
00266      * for seeking. */
00267     void (* flush) (int time);
00268 
00269     /* Returns the time counter.  Note that this represents the amount of audio
00270      * data passed to the output system, not the amount actually heard by the
00271      * user.  This function is useful for handling a changed audio format:
00272      * First, save the time counter using this function.  Second, call
00273      * close_audio and then open_audio with the new format (note that the call
00274      * may fail).  Finally, restore the time counter using flush. */
00275     int (* written_time) (void);
00276 
00277     /* Returns TRUE if there is data remaining in the output buffer; FALSE if
00278      * all data written to the output system has been heard by the user.  This
00279      * function should be polled (1/50 second is a reasonable delay between
00280      * calls) at the end of a song before calling close_audio.  Once it returns
00281      * FALSE, close_audio can be called without cutting off any of the end of
00282      * the song. */
00283     bool_t (* buffer_playing) (void);
00284 
00285     /* Interrupt a call to write_audio so that it returns immediately.  This
00286      * works even when the call is blocked by pause.  Buffered audio data is
00287      * discarded as in flush.  Until flush is called or the output system is
00288      * reset, further calls to write_audio will have no effect and return
00289      * immediately.  This function is intended to be used in seeking or
00290      * stopping in a multi-thread plugin.  To seek, the handler function (called
00291      * in the main thread) should first set a flag for the decoding thread and
00292      * then call abort_write.  When the decoding thread notices the flag, it
00293      * should do the actual seek, call flush, and finally clear the flag.  Once
00294      * the flag is cleared, the handler function may return. */
00295     void (* abort_write) (void);
00296 };
00297 
00298 typedef const struct _InputPlayback InputPlayback;
00299 
00300 struct _InputPlayback
00301 {
00302     /* Pointer to the output API functions. */
00303     const struct OutputAPI * output;
00304 
00305     /* Allows the plugin to associate data with a playback instance. */
00306     void (* set_data) (InputPlayback * p, void * data);
00307 
00308     /* Returns the pointer passed to set_data. */
00309     void * (* get_data) (InputPlayback * p);
00310 
00311     /* Signifies that the plugin has started playback is ready to accept mseek,
00312      * pause, and stop calls. */
00313     void (* set_pb_ready) (InputPlayback * p);
00314 
00315     /* Updates attributes of the stream.  "bitrate" is in bits per second.
00316      * "samplerate" is in hertz. */
00317     void (* set_params) (InputPlayback * p, int bitrate, int samplerate,
00318      int channels);
00319 
00320     /* Updates metadata for the stream.  Caller gives up ownership of one
00321      * reference to the tuple. */
00322     void (* set_tuple) (InputPlayback * playback, Tuple * tuple);
00323 
00324     /* If replay gain settings are stored in the tuple associated with the
00325      * current song, this function can be called (after opening audio) to apply
00326      * those settings.  If the settings are changed in a call to set_tuple, this
00327      * function must be called again to apply the updated settings. */
00328     void (* set_gain_from_playlist) (InputPlayback * playback);
00329 };
00330 
00331 struct _InputPlugin
00332 {
00333     PLUGIN_COMMON_FIELDS
00334 
00335     /* Nonzero if the files handled by the plugin may contain more than one
00336      * song.  When reading the tuple for such a file, the plugin should set the
00337      * FIELD_SUBSONG_NUM field to the number of songs in the file.  For all
00338      * other files, the field should be left unset.
00339      *
00340      * Example:
00341      * 1. User adds a file named "somefile.xxx" to the playlist.  Having
00342      * determined that this plugin can handle the file, Audacious opens the file
00343      * and calls probe_for_tuple().  probe_for_tuple() sees that there are 3
00344      * songs in the file and sets FIELD_SUBSONG_NUM to 3.
00345      * 2. For each song in the file, Audacious opens the file and calls
00346      * probe_for_tuple() -- this time, however, a question mark and song number
00347      * are appended to the file name passed: "somefile.sid?2" refers to the
00348      * second song in the file "somefile.sid".
00349      * 3. When one of the songs is played, Audacious opens the file and calls
00350      * play() with a file name modified in this way.
00351      */
00352     bool_t have_subtune;
00353 
00354     /* Pointer to an array (terminated with NULL) of file extensions associated
00355      * with file types the plugin can handle. */
00356     const char * const * extensions;
00357     /* Pointer to an array (terminated with NULL) of MIME types the plugin can
00358      * handle. */
00359     const char * const * mimes;
00360     /* Pointer to an array (terminated with NULL) of custom URI schemes the
00361      * plugin can handle. */
00362     const char * const * schemes;
00363 
00364     /* How quickly the plugin should be tried in searching for a plugin to
00365      * handle a file which could not be identified from its extension.  Plugins
00366      * with priority 0 are tried first, 10 last. */
00367     int priority;
00368 
00369     /* Must return nonzero if the plugin can handle this file.  If the file
00370      * could not be opened, "file" will be NULL.  (This is normal in the case of
00371      * special URI schemes like cdda:// that do not represent actual files.) */
00372     bool_t (* is_our_file_from_vfs) (const char * filename, VFSFile * file);
00373 
00374     /* Must return a tuple containing metadata for this file, or NULL if no
00375      * metadata could be read.  If the file could not be opened, "file" will be
00376      * NULL.  Audacious takes over one reference to the tuple returned. */
00377     Tuple * (* probe_for_tuple) (const char * filename, VFSFile * file);
00378 
00379     /* Optional.  Must write metadata from a tuple to this file.  Must return
00380      * nonzero on success or zero on failure.  "file" will never be NULL. */
00381     /* Bug: This function does not support special URI schemes like cdda://,
00382      * since no file name is passed. */
00383     bool_t (* update_song_tuple) (const Tuple * tuple, VFSFile * file);
00384 
00385     /* Optional, and not recommended.  Must show a window with information about
00386      * this file.  If this function is provided, update_song_tuple should not be. */
00387     /* Bug: Implementing this function duplicates user interface code and code
00388      * to open the file in each and every plugin. */
00389     void (* file_info_box) (const char * filename);
00390 
00391     /* Optional.  Must try to read an "album art" image embedded in this file.
00392      * Must return nonzero on success or zero on failure.  If the file could not
00393      * be opened, "file" will be NULL.  On success, must fill "data" with a
00394      * pointer to a block of data allocated with g_malloc and "size" with the
00395      * size in bytes of that block.  The data may be in any format supported by
00396      * GTK.  Audacious will free the data when it is no longer needed. */
00397     bool_t (* get_song_image) (const char * filename, VFSFile * file,
00398      void * * data, int64_t * size);
00399 
00400     /* Must try to play this file.  "playback" is a structure containing output-
00401      * related functions which the plugin may make use of.  It also contains a
00402      * "data" pointer which the plugin may use to refer private data associated
00403      * with the playback state.  This pointer can then be used from pause,
00404      * mseek, and stop. If the file could not be opened, "file" will be NULL.
00405      * "start_time" is the position in milliseconds at which to start from, or
00406      * -1 to start from the beginning of the file.  "stop_time" is the position
00407      * in milliseconds at which to end playback, or -1 to play to the end of the
00408      * file.  "paused" specifies whether playback should immediately be paused.
00409      * Must return nonzero if some of the file was successfully played or zero
00410      * on failure. */
00411     bool_t (* play) (InputPlayback * playback, const char * filename,
00412      VFSFile * file, int start_time, int stop_time, bool_t pause);
00413 
00414     /* Must pause or unpause a file currently being played.  This function will
00415      * be called from a different thread than play, but it will not be called
00416      * before the plugin calls set_pb_ready or after stop is called. */
00417     void (* pause) (InputPlayback * playback, bool_t paused);
00418 
00419     /* Optional.  Must seek to the given position in milliseconds within a file
00420      * currently being played.  This function will be called from a different
00421      * thread than play, but it will not be called before the plugin calls
00422      * set_pb_ready or after stop is called. */
00423     void (* mseek) (InputPlayback * playback, int time);
00424 
00425     /* Must signal a currently playing song to stop and cause play to return.
00426      * This function will be called from a different thread than play.  It will
00427      * only be called once. It should not join the thread from which play is
00428      * called. */
00429     void (* stop) (InputPlayback * playback);
00430 
00431     /* Advanced, for plugins that do not use Audacious's output system.  Use at
00432      * your own risk. */
00433     int (* get_time) (InputPlayback * playback);
00434     int (* get_volume) (int * l, int * r);
00435     int (* set_volume) (int l, int r);
00436 };
00437 
00438 struct _GeneralPlugin
00439 {
00440     PLUGIN_COMMON_FIELDS
00441 
00442     bool_t enabled_by_default;
00443 
00444     /* GtkWidget * (* get_widget) (void); */
00445     void * (* get_widget) (void);
00446 };
00447 
00448 struct _VisPlugin
00449 {
00450     PLUGIN_COMMON_FIELDS
00451 
00452     /* reset internal state and clear display */
00453     void (* clear) (void);
00454 
00455     /* 512 frames of a single-channel PCM signal */
00456     void (* render_mono_pcm) (const float * pcm);
00457 
00458     /* 512 frames of an interleaved multi-channel PCM signal */
00459     void (* render_multi_pcm) (const float * pcm, int channels);
00460 
00461     /* intensity of frequencies 1/512, 2/512, ..., 256/512 of sample rate */
00462     void (* render_freq) (const float * freq);
00463 
00464     /* GtkWidget * (* get_widget) (void); */
00465     void * (* get_widget) (void);
00466 };
00467 
00468 struct _IfacePlugin
00469 {
00470     PLUGIN_COMMON_FIELDS
00471 
00472     /* is_shown() may return nonzero even if the interface is not actually
00473      * visible; for example, if it is obscured by other windows or minimized.
00474      * is_focused() only returns nonzero if the interface is actually visible;
00475      * in X11, this should be determined by whether the interface has the
00476      * toplevel focus.  show() should show and raise the interface, so that both
00477      * is_shown() and is_focused() will return nonzero. */
00478     void (* show) (bool_t show);
00479     bool_t (* is_shown) (void);
00480 
00481     void (* show_error) (const char * markup);
00482     void (* show_filebrowser) (bool_t play_button);
00483     void (* show_jump_to_track) (void);
00484 
00485     void (* run_gtk_plugin) (void /* GtkWidget */ * widget, const char * name);
00486     void (* stop_gtk_plugin) (void /* GtkWidget */ * widget);
00487 
00488     void (* install_toolbar) (void /* GtkWidget */ * button);
00489     void (* uninstall_toolbar) (void /* GtkWidget */ * button);
00490 
00491     /* added after 3.0-alpha1 */
00492     bool_t (* is_focused) (void);
00493 };
00494 
00495 #undef PLUGIN_COMMON_FIELDS
00496 
00497 #define AUD_PLUGIN(stype, itype, ...) \
00498 AudAPITable * _aud_api_table = NULL; \
00499 stype _aud_plugin_self = { \
00500  .magic = _AUD_PLUGIN_MAGIC, \
00501  .version = _AUD_PLUGIN_VERSION, \
00502  .type = itype, \
00503  .size = sizeof (stype), \
00504  __VA_ARGS__}; \
00505 stype * get_plugin_info (AudAPITable * table) { \
00506     _aud_api_table = table; \
00507     return & _aud_plugin_self; \
00508 }
00509 
00510 #define AUD_TRANSPORT_PLUGIN(...) AUD_PLUGIN (TransportPlugin, PLUGIN_TYPE_TRANSPORT, __VA_ARGS__)
00511 #define AUD_PLAYLIST_PLUGIN(...) AUD_PLUGIN (PlaylistPlugin, PLUGIN_TYPE_PLAYLIST, __VA_ARGS__)
00512 #define AUD_INPUT_PLUGIN(...) AUD_PLUGIN (InputPlugin, PLUGIN_TYPE_INPUT, __VA_ARGS__)
00513 #define AUD_EFFECT_PLUGIN(...) AUD_PLUGIN (EffectPlugin, PLUGIN_TYPE_EFFECT, __VA_ARGS__)
00514 #define AUD_OUTPUT_PLUGIN(...) AUD_PLUGIN (OutputPlugin, PLUGIN_TYPE_OUTPUT, __VA_ARGS__)
00515 #define AUD_VIS_PLUGIN(...) AUD_PLUGIN (VisPlugin, PLUGIN_TYPE_VIS, __VA_ARGS__)
00516 #define AUD_GENERAL_PLUGIN(...) AUD_PLUGIN (GeneralPlugin, PLUGIN_TYPE_GENERAL, __VA_ARGS__)
00517 #define AUD_IFACE_PLUGIN(...) AUD_PLUGIN (IfacePlugin, PLUGIN_TYPE_IFACE, __VA_ARGS__)
00518 
00519 #define PLUGIN_HAS_FUNC(p, func) \
00520  ((p)->size > (char *) & (p)->func - (char *) (p) && (p)->func)
00521 
00522 #endif /* AUDACIOUS_PLUGIN_H */