src/output_plugin.h

   1 /*
   2  * Copyright (C) 2003-2010 The Music Player Daemon Project
   3  * http://www.musicpd.org
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18  */
  19
  20 #ifndef MPD_OUTPUT_PLUGIN_H
  21 #define MPD_OUTPUT_PLUGIN_H
  22
  23 #include <glib.h>
  24
  25 #include <stdbool.h>
  26 #include <stddef.h>
  27
  28 struct config_param;
  29 struct audio_format;
  30 struct tag;
  31
  32 /**
  33  * A plugin which controls an audio output device.
  34  */
  35 struct audio_output_plugin {
  36         /**
  37          * the plugin's name
  38          */
  39         const char *name;
  40
  41         /**
  42          * Test if this plugin can provide a default output, in case
  43          * none has been configured.  This method is optional.
  44          */
  45         bool (*test_default_device)(void);
  46
  47         /**
  48          * Configure and initialize the device, but do not open it
  49          * yet.
  50          *
  51          * @param audio_format the configured audio format, or NULL if
  52          * none is configured
  53          * @param param the configuration section, or NULL if there is
  54          * no configuration
  55          * @param error location to store the error occuring, or NULL
  56          * to ignore errors
  57          * @return NULL on error, or an opaque pointer to the plugin's
  58          * data
  59          */
  60         void *(*init)(const struct audio_format *audio_format,
  61                       const struct config_param *param,
  62                       GError **error);
  63
  64         /**
  65          * Free resources allocated by this device.
  66          */
  67         void (*finish)(void *data);
  68
  69         /**
  70          * Enable the device.  This may allocate resources, preparing
  71          * for the device to be opened.  Enabling a device cannot
  72          * fail: if an error occurs during that, it should be reported
  73          * by the open() method.
  74          *
  75          * @param error_r location to store the error occuring, or
  76          * NULL to ignore errors
  77          * @return true on success, false on error
  78          */
  79         bool (*enable)(void *data, GError **error_r);
  80
  81         /**
  82          * Disables the device.  It is closed before this method is
  83          * called.
  84          */
  85         void (*disable)(void *data);
  86
  87         /**
  88          * Really open the device.
  89          *
  90          * @param audio_format the audio format in which data is going
  91          * to be delivered; may be modified by the plugin
  92          * @param error location to store the error occuring, or NULL
  93          * to ignore errors
  94          */
  95         bool (*open)(void *data, struct audio_format *audio_format,
  96                      GError **error);
  97
  98         /**
  99          * Close the device.
 100          */
 101         void (*close)(void *data);
 102
 103         /**
 104          * Display metadata for the next chunk.  Optional method,
 105          * because not all devices can display metadata.
 106          */
 107         void (*send_tag)(void *data, const struct tag *tag);
 108
 109         /**
 110          * Play a chunk of audio data.
 111          *
 112          * @param error location to store the error occuring, or NULL
 113          * to ignore errors
 114          * @return the number of bytes played, or 0 on error
 115          */
 116         size_t (*play)(void *data, const void *chunk, size_t size,
 117                        GError **error);
 118
 119         /**
 120          * Wait until the device has finished playing.
 121          */
 122         void (*drain)(void *data);
 123
 124         /**
 125          * Try to cancel data which may still be in the device's
 126          * buffers.
 127          */
 128         void (*cancel)(void *data);
 129
 130         /**
 131          * Pause the device.  If supported, it may perform a special
 132          * action, which keeps the device open, but does not play
 133          * anything.  Output plugins like "shout" might want to play
 134          * silence during pause, so their clients won't be
 135          * disconnected.  Plugins which do not support pausing will
 136          * simply be closed, and have to be reopened when unpaused.
 137          *
 138          * @return false on error (output will be closed then), true
 139          * for continue to pause
 140          */
 141         bool (*pause)(void *data);
 142
 143         /**
 144          * The mixer plugin associated with this output plugin.  This
 145          * may be NULL if no mixer plugin is implemented.  When
 146          * created, this mixer plugin gets the same #config_param as
 147          * this audio output device.
 148          */
 149         const struct mixer_plugin *mixer_plugin;
 150 };
 151
 152 static inline bool
 153 ao_plugin_test_default_device(const struct audio_output_plugin *plugin)
 154 {
 155         return plugin->test_default_device != NULL
 156                 ? plugin->test_default_device()
 157                 : false;
 158 }
 159
 160 static inline void *
 161 ao_plugin_init(const struct audio_output_plugin *plugin,
 162                const struct audio_format *audio_format,
 163                const struct config_param *param,
 164                GError **error)
 165 {
 166         return plugin->init(audio_format, param, error);
 167 }
 168
 169 static inline void
 170 ao_plugin_finish(const struct audio_output_plugin *plugin, void *data)
 171 {
 172         plugin->finish(data);
 173 }
 174
 175 static inline bool
 176 ao_plugin_enable(const struct audio_output_plugin *plugin, void *data,
 177                  GError **error_r)
 178 {
 179         return plugin->enable != NULL
 180                 ? plugin->enable(data, error_r)
 181                 : true;
 182 }
 183
 184 static inline void
 185 ao_plugin_disable(const struct audio_output_plugin *plugin, void *data)
 186 {
 187         if (plugin->disable != NULL)
 188                 plugin->disable(data);
 189 }
 190
 191 static inline bool
 192 ao_plugin_open(const struct audio_output_plugin *plugin,
 193                void *data, struct audio_format *audio_format,
 194                GError **error)
 195 {
 196         return plugin->open(data, audio_format, error);
 197 }
 198
 199 static inline void
 200 ao_plugin_close(const struct audio_output_plugin *plugin, void *data)
 201 {
 202         plugin->close(data);
 203 }
 204
 205 static inline void
 206 ao_plugin_send_tag(const struct audio_output_plugin *plugin,
 207                    void *data, const struct tag *tag)
 208 {
 209         if (plugin->send_tag != NULL)
 210                 plugin->send_tag(data, tag);
 211 }
 212
 213 static inline size_t
 214 ao_plugin_play(const struct audio_output_plugin *plugin,
 215                void *data, const void *chunk, size_t size,
 216                GError **error)
 217 {
 218         return plugin->play(data, chunk, size, error);
 219 }
 220
 221 static inline void
 222 ao_plugin_drain(const struct audio_output_plugin *plugin, void *data)
 223 {
 224         if (plugin->drain != NULL)
 225                 plugin->drain(data);
 226 }
 227
 228 static inline void
 229 ao_plugin_cancel(const struct audio_output_plugin *plugin, void *data)
 230 {
 231         if (plugin->cancel != NULL)
 232                 plugin->cancel(data);
 233 }
 234
 235 static inline bool
 236 ao_plugin_pause(const struct audio_output_plugin *plugin, void *data)
 237 {
 238         return plugin->pause != NULL
 239                 ? plugin->pause(data)
 240                 : false;
 241 }
 242
 243 #endif