src/libmpd-status.h

   1 /* libmpd (high level libmpdclient library)
   2  * Copyright (C) 2004-2009 Qball Cow <qball@sarine.nl>
   3  * Project homepage: http://gmpcwiki.sarine.nl/
   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
  21 #ifndef __MPD_LIB_STATUS__
  22 #define __MPD_LIB_STATUS__
  23 /**\defgroup 20status Status
  24  * Functions to get and modify the status/state of mpd.
  25  */
  26 /*@{*/
  27
  28 /**
  29  * @param mi a #MpdObj
  30  *
  31  * Checks if there is status information available. if not available, it tries to fetch it.
  32  * This function is called from within libmpd, and shouldn't be called from the program.
  33  *
  34  * @returns 0 when successful
  35  */
  36 int             mpd_status_check                        (MpdObj *mi);
  37
  38
  39
  40 /**
  41  * @param mi a #MpdObj
  42  *
  43  * Marks the current status invalid, the next time status is needed it will be fetched from mpd.
  44  *
  45  * @returns 0 when successful
  46  */
  47 int             mpd_status_queue_update                 (MpdObj *mi);
  48
  49
  50
  51 /**
  52  * @param mi a #MpdObj
  53  *
  54  * Updates the status field from mpd.
  55  * Call this function every 0.x seconds from the program's main-loop to receive signals when mpd's status has changed.
  56  *
  57  * @returns 0 when succesfull
  58  */
  59 int             mpd_status_update                       (MpdObj *mi);
  60
  61
  62
  63 /**
  64  * @param mi a #MpdObj
  65  * @param fvol a float between 0.0 and 1.0
  66  *
  67  * Set the output volume
  68  * @returns the new volume or a value below 0 when failed.
  69  */
  70 float           mpd_status_set_volume_as_float          (MpdObj *mi, float fvol);
  71
  72
  73 /**
  74  * @param mi a #MpdObj
  75  * @param volume a value between 0 and 100.
  76  *
  77  * Set the output volume
  78  *
  79  * @returns the new volume or < 0 when failed.
  80  */
  81 int             mpd_status_set_volume                   (MpdObj *mi,int volume);
  82
  83
  84
  85 /**
  86  * @param mi a #MpdObj
  87  *
  88  * Get the audio output volume.
  89  *
  90  * @returns the audio output volume between 0 and 100 or < 0 when failed
  91  */
  92 int             mpd_status_get_volume                   (MpdObj *mi);
  93
  94
  95
  96 /**
  97  * @param mi a #MpdObj
  98  *
  99  * get the bitrate of the currently playing song in kbs. This is a constantly updating value. (for vbr songs)
 100  *
 101  * @returns bitrate in kbs
 102  */
 103 int             mpd_status_get_bitrate                  (MpdObj *mi);
 104
 105
 106
 107 /**
 108  * @param mi a #MpdObj
 109  *
 110  * get the samplerate of the currently playing song in bps.
 111  *
 112  * @returns samplerate in bps
 113  */
 114 unsigned int    mpd_status_get_samplerate                       (MpdObj *mi);
 115
 116
 117
 118 /**
 119  * @param mi a #MpdObj
 120  *
 121  * get the number of channels in the currently playing song. This is usually only 1(mono) or 2(stereo), but this might change in the future.
 122  *
 123  * @returns number of channels
 124  */
 125 int             mpd_status_get_channels                 (MpdObj *mi);
 126
 127
 128
 129 /**
 130  * @param mi a #MpdObj
 131  *
 132  * get the number of bits per sample of the currently playing song.
 133  *
 134  * @returns bits per sample
 135  */
 136 int             mpd_status_get_bits                     (MpdObj *mi);
 137
 138
 139
 140 /**
 141  * @param mi a #MpdObj
 142  *
 143  * get the total length of the currently playing song.
 144  *
 145  * @returns time in seconds or <0 when failed.
 146  */
 147 int             mpd_status_get_total_song_time          (MpdObj *mi);
 148
 149
 150 /**
 151  * @param mi a #MpdObj
 152  *
 153  * Gets the elapsed time of the currently playing song.
 154  *
 155  * @returns Time in seconds
 156  */
 157 int             mpd_status_get_elapsed_song_time        (MpdObj *mi);
 158
 159
 160 /**
 161  * @param mi a #MpdObj
 162  *
 163  * Get the crossfade time. 0 is disabled.
 164  *
 165  * @returns The crossfade time in seconds
 166  */
 167 int             mpd_status_get_crossfade                (MpdObj *mi);
 168
 169
 170
 171 /**
 172  * @param mi a #MpdObj
 173  * @param crossfade_time the time to crossfade in seconds
 174  *
 175  * Sets the crossfade time. 0 to disable crossfade.
 176  *
 177  * @returns 0 when successful
 178  */
 179 int             mpd_status_set_crossfade                (MpdObj *mi, int crossfade_time);
 180
 181
 182
 183 /**
 184  * @param mi a #MpdObj
 185  *
 186  * Checks if mpd is updating it's music db.
 187  *
 188  * @returns TRUE if mpd is still updating, FALSE if not.
 189  */
 190 int             mpd_status_db_is_updating               (MpdObj *mi);
 191
 192 /**
 193  * @param mi a #MpdObj
 194  *
 195  * @returns the error message that mpd last reported, or NULL. Needs to be freed.
 196  */
 197
 198 char * mpd_status_get_mpd_error(MpdObj *mi);
 199
 200 /*@}*/
 201
 202 /**\defgroup 20stats Stats
 203  * Functions to get mpd statistics
 204  */
 205 /*@{*/
 206
 207
 208
 209
 210 /**
 211  * @param mi a #MpdObj
 212  *
 213  * Shouldn't be used from the program.
 214  */
 215 int             mpd_stats_update                        (MpdObj *mi);
 216
 217
 218 /**
 219  * @param mi a #MpdObj
 220  *
 221  * Gets the total number of songs in the database
 222  *
 223  * @returns The total number of songs
 224  */
 225 int             mpd_stats_get_total_songs               (MpdObj *mi);
 226
 227
 228 /**
 229  * @param mi a #MpdObj
 230  *
 231  * Gets the total number of artists in the database.
 232  *
 233  * @returns The number of artists in the database
 234  */
 235 int             mpd_stats_get_total_artists             (MpdObj *mi);
 236
 237
 238
 239 /**
 240  * @param mi a #MpdObj
 241  *
 242  * Gets the total number of albums in the database
 243  *
 244  * @returns The number of albums in the database
 245  */
 246 int             mpd_stats_get_total_albums              (MpdObj *mi);
 247
 248
 249
 250 /**
 251  * @param mi a #MpdObj
 252  *
 253  * Gets the time since mpd has been running
 254  *
 255  * @returns time since mpd has been running in seconds
 256  */
 257 int             mpd_stats_get_uptime                    (MpdObj *mi);
 258 /**
 259  * @param mi a #MpdObj
 260  *
 261  * Gets the total time of the database
 262  *
 263  * @returns the total time of the database
 264  */
 265 int             mpd_stats_get_db_playtime               (MpdObj *mi);
 266
 267
 268
 269 /**
 270  * @param mi a #MpdObj
 271  *
 272  * Gets the time mpd is playing
 273  *
 274  * @returns time that mpd is playing in seconds
 275  */
 276 int             mpd_stats_get_playtime                  (MpdObj *mi);
 277
 278
 279
 280
 281 /*@}*/
 282 #endif