src/output_plugin.h

   1 /*
   2  * Copyright (C) 2003-2009 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          * Really open the device.
  71          *
  72          * @param audio_format the audio format in which data is going
  73          * to be delivered; may be modified by the plugin
  74          * @param error location to store the error occuring, or NULL
  75          * to ignore errors
  76          */
  77         bool (*open)(void *data, struct audio_format *audio_format,
  78                      GError **error);
  79
  80         /**
  81          * Close the device.
  82          */
  83         void (*close)(void *data);
  84
  85         /**
  86          * Display metadata for the next chunk.  Optional method,
  87          * because not all devices can display metadata.
  88          */
  89         void (*send_tag)(void *data, const struct tag *tag);
  90
  91         /**
  92          * Play a chunk of audio data.
  93          *
  94          * @param error location to store the error occuring, or NULL
  95          * to ignore errors
  96          * @return the number of bytes played, or 0 on error
  97          */
  98         size_t (*play)(void *data, const void *chunk, size_t size,
  99                        GError **error);
 100
 101         /**
 102          * Try to cancel data which may still be in the device's
 103          * buffers.
 104          */
 105         void (*cancel)(void *data);
 106
 107         /**
 108          * Pause the device.  If supported, it may perform a special
 109          * action, which keeps the device open, but does not play
 110          * anything.  Output plugins like "shout" might want to play
 111          * silence during pause, so their clients won't be
 112          * disconnected.  Plugins which do not support pausing will
 113          * simply be closed, and have to be reopened when unpaused.
 114          *
 115          * @return false on error (output will be closed then), true
 116          * for continue to pause
 117          */
 118         bool (*pause)(void *data);
 119
 120         /**
 121          * The mixer plugin associated with this output plugin.  This
 122          * may be NULL if no mixer plugin is implemented.  When
 123          * created, this mixer plugin gets the same #config_param as
 124          * this audio output device.
 125          */
 126         const struct mixer_plugin *mixer_plugin;
 127 };
 128
 129 static inline bool
 130 ao_plugin_test_default_device(const struct audio_output_plugin *plugin)
 131 {
 132         return plugin->test_default_device != NULL
 133                 ? plugin->test_default_device()
 134                 : false;
 135 }
 136
 137 static inline void *
 138 ao_plugin_init(const struct audio_output_plugin *plugin,
 139                const struct audio_format *audio_format,
 140                const struct config_param *param,
 141                GError **error)
 142 {
 143         return plugin->init(audio_format, param, error);
 144 }
 145
 146 static inline void
 147 ao_plugin_finish(const struct audio_output_plugin *plugin, void *data)
 148 {
 149         plugin->finish(data);
 150 }
 151
 152 static inline bool
 153 ao_plugin_open(const struct audio_output_plugin *plugin,
 154                void *data, struct audio_format *audio_format,
 155                GError **error)
 156 {
 157         return plugin->open(data, audio_format, error);
 158 }
 159
 160 static inline void
 161 ao_plugin_close(const struct audio_output_plugin *plugin, void *data)
 162 {
 163         plugin->close(data);
 164 }
 165
 166 static inline void
 167 ao_plugin_send_tag(const struct audio_output_plugin *plugin,
 168                    void *data, const struct tag *tag)
 169 {
 170         if (plugin->send_tag != NULL)
 171                 plugin->send_tag(data, tag);
 172 }
 173
 174 static inline size_t
 175 ao_plugin_play(const struct audio_output_plugin *plugin,
 176                void *data, const void *chunk, size_t size,
 177                GError **error)
 178 {
 179         return plugin->play(data, chunk, size, error);
 180 }
 181
 182 static inline void
 183 ao_plugin_cancel(const struct audio_output_plugin *plugin, void *data)
 184 {
 185         if (plugin->cancel != NULL)
 186                 plugin->cancel(data);
 187 }
 188
 189 static inline bool
 190 ao_plugin_pause(const struct audio_output_plugin *plugin, void *data)
 191 {
 192         return plugin->pause != NULL
 193                 ? plugin->pause(data)
 194                 : false;
 195 }
 196
 197 #endif