1 /* libmpdclient 2 (c) 2003-2019 The Music Player Daemon Project 3 This project's homepage is: http://www.musicpd.org 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 - Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 12 - Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in the 14 documentation and/or other materials provided with the distribution. 15 16 - Neither the name of the Music Player Daemon nor the names of its 17 contributors may be used to endorse or promote products derived from 18 this software without specific prior written permission. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 24 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! \file 34 * \brief MPD client library 35 * 36 * Do not include this header directly. Use mpd/client.h instead. 37 */ 38 39 #ifndef MPD_STATUS_H 40 #define MPD_STATUS_H 41 42 #include "compiler.h" 43 44 #include <stdbool.h> 45 46 /** 47 * MPD's playback state. 48 */ 49 enum mpd_state { 50 /** no information available */ 51 MPD_STATE_UNKNOWN = 0, 52 53 /** not playing */ 54 MPD_STATE_STOP = 1, 55 56 /** playing */ 57 MPD_STATE_PLAY = 2, 58 59 /** playing, but paused */ 60 MPD_STATE_PAUSE = 3, 61 }; 62 63 /** 64 * MPD's single state. 65 * 66 * @since libmpdclient 2.18, MPD 0.21. 67 */ 68 enum mpd_single_state { 69 /** disabled */ 70 MPD_SINGLE_OFF = 0, 71 72 /** enabled */ 73 MPD_SINGLE_ON, 74 75 /** 76 * enables single state (#MPD_SINGLE_ONESHOT) for a single song, then 77 * MPD disables single state (#MPD_SINGLE_OFF) if the current song 78 * has played and there is another song in the current playlist 79 * 80 * @since MPD 0.21 81 **/ 82 MPD_SINGLE_ONESHOT, 83 84 /** Unknown state */ 85 MPD_SINGLE_UNKNOWN, 86 }; 87 88 struct mpd_connection; 89 struct mpd_pair; 90 struct mpd_audio_format; 91 92 /** 93 * \struct mpd_status 94 * 95 * Holds information about MPD's status. 96 */ 97 struct mpd_status; 98 99 #ifdef __cplusplus 100 extern "C" { 101 #endif 102 103 /** 104 * Begins parsing the server status: creates a new empty #mpd_status 105 * object. Free it with mpd_status_free(). 106 * 107 * @return the newly allocated #mpd_status object, or NULL if out of 108 * memory 109 */ 110 mpd_malloc 111 struct mpd_status * 112 mpd_status_begin(void); 113 114 /** 115 * Parses the pair, adding its information to the specified 116 * #mpd_status object. 117 */ 118 void 119 mpd_status_feed(struct mpd_status *status, const struct mpd_pair *pair); 120 121 /** 122 * Sends the "status" command to MPD. Call mpd_recv_status() to read 123 * the response. 124 * 125 * @return true on success 126 */ 127 bool 128 mpd_send_status(struct mpd_connection *connection); 129 130 /** 131 * Receives a #mpd_status object from the server. 132 * 133 * @return the received #mpd_status object, or NULL on error 134 */ 135 mpd_malloc 136 struct mpd_status * 137 mpd_recv_status(struct mpd_connection *connection); 138 139 /** 140 * Executes the "status" command and reads the response. 141 * 142 * @return the #mpd_status object returned by the server, or NULL on 143 * error 144 */ 145 mpd_malloc 146 struct mpd_status * 147 mpd_run_status(struct mpd_connection *connection); 148 149 /** 150 * Releases a #mpd_status object. 151 */ 152 void mpd_status_free(struct mpd_status * status); 153 154 /** 155 * Returns the current volume: 0-100, or -1 when there is no volume 156 * support. 157 */ 158 mpd_pure 159 int mpd_status_get_volume(const struct mpd_status *status); 160 161 /** 162 * Returns true if repeat mode is on. 163 */ 164 mpd_pure 165 bool 166 mpd_status_get_repeat(const struct mpd_status *status); 167 168 /** 169 * Returns true if random mode is on. 170 */ 171 mpd_pure 172 bool 173 mpd_status_get_random(const struct mpd_status *status); 174 175 /** 176 * Returns the current state of single mode on MPD. 177 * 178 * If the state is #MPD_SINGLE_ONESHOT, MPD will transition to #MPD_SINGLE_OFF 179 * after a song is played and if there is another song in the queue. The 180 * #mpd_status object will not be updated accordingly. In this case, you need 181 * to call mpd_send_status() and mpd_recv_status() again. 182 * 183 * @since MPD 0.21, libmpdclient 2.18. 184 */ 185 mpd_pure 186 enum mpd_single_state 187 mpd_status_get_single_state(const struct mpd_status *status); 188 189 /** 190 * This function is deprecated as it does not distinguish the states of 191 * the single mode (added to MPD 0.21). Call mpd_status_get_single_state() in 192 * its place. 193 * 194 * Returns true if single mode is either on or in oneshot. 195 */ 196 mpd_pure 197 bool 198 mpd_status_get_single(const struct mpd_status *status); 199 200 /** 201 * Returns true if consume mode is on. 202 */ 203 mpd_pure 204 bool 205 mpd_status_get_consume(const struct mpd_status *status); 206 207 /** 208 * Returns the number of songs in the queue. If MPD did not 209 * specify that, this function returns 0. 210 */ 211 mpd_pure 212 unsigned 213 mpd_status_get_queue_length(const struct mpd_status *status); 214 215 /** 216 * Returns queue version number. You may use this to determine 217 * when the queue has changed since you have last queried it. 218 */ 219 mpd_pure 220 unsigned 221 mpd_status_get_queue_version(const struct mpd_status *status); 222 223 /** 224 * Returns the state of the player: either stopped, playing or paused. 225 */ 226 mpd_pure 227 enum mpd_state 228 mpd_status_get_state(const struct mpd_status *status); 229 230 /** 231 * Returns crossfade setting in seconds. 0 means crossfading is 232 * disabled. 233 */ 234 mpd_pure 235 unsigned 236 mpd_status_get_crossfade(const struct mpd_status *status); 237 238 /** 239 * Returns mixrampdb setting in db. 0 means mixrampdb is disabled. 240 * 241 * @since libmpdclient 2.2 242 */ 243 mpd_pure 244 float 245 mpd_status_get_mixrampdb(const struct mpd_status *status); 246 247 /** 248 * Returns mixrampdelay setting in seconds. Negative means mixrampdelay is 249 * disabled. 250 * 251 * @since libmpdclient 2.2 252 */ 253 mpd_pure 254 float 255 mpd_status_get_mixrampdelay(const struct mpd_status *status); 256 257 /** 258 * Returns the position of the currently playing song in the queue 259 * (beginning with 0) if a song is currently selected (always the case when 260 * state is MPD_STATE_PLAY or MPD_STATE_PAUSE). If there is no current song, 261 * -1 is returned. 262 */ 263 mpd_pure 264 int 265 mpd_status_get_song_pos(const struct mpd_status *status); 266 267 /** 268 * Returns the id of the current song. If there is no current song, 269 * -1 is returned. 270 */ 271 mpd_pure 272 int 273 mpd_status_get_song_id(const struct mpd_status *status); 274 275 /** 276 * The same as mpd_status_get_song_pos(), but for the next song to be 277 * played. 278 * 279 * @since libmpdclient 2.7 280 */ 281 mpd_pure 282 int 283 mpd_status_get_next_song_pos(const struct mpd_status *status); 284 285 /** 286 * Returns the id of the next song to be played. If it is not known, -1 is 287 * returned. 288 * 289 * @since libmpdclient 2.7 290 */ 291 mpd_pure 292 int 293 mpd_status_get_next_song_id(const struct mpd_status *status); 294 295 /** 296 * This function uses a deprecated feature of MPD, call 297 * mpd_status_get_elapsed_ms() instead. 298 * 299 * Returns time in seconds that have elapsed in the currently playing/paused 300 * song. 301 * 302 */ 303 mpd_pure 304 unsigned 305 mpd_status_get_elapsed_time(const struct mpd_status *status); 306 307 /** 308 * Returns time in milliseconds that have elapsed in the currently 309 * playing/paused song. 310 * 311 * @since libmpdclient 2.1 312 */ 313 mpd_pure 314 unsigned 315 mpd_status_get_elapsed_ms(const struct mpd_status *status); 316 317 /** 318 * Returns the length in seconds of the currently playing/paused song 319 */ 320 mpd_pure 321 unsigned 322 mpd_status_get_total_time(const struct mpd_status *status); 323 324 /** 325 * Returns current bit rate in kbps. 0 means unknown. 326 */ 327 mpd_pure 328 unsigned 329 mpd_status_get_kbit_rate(const struct mpd_status *status); 330 331 /** 332 * Returns audio format which MPD is currently playing. May return 333 * NULL if MPD is not playing or if the audio format is unknown. 334 */ 335 mpd_pure 336 const struct mpd_audio_format * 337 mpd_status_get_audio_format(const struct mpd_status *status); 338 339 /** 340 * Returns 1 if mpd is updating, 0 otherwise 341 */ 342 mpd_pure 343 unsigned 344 mpd_status_get_update_id(const struct mpd_status *status); 345 346 /** 347 * Returns the name of the current partition or NULL if the server did 348 * not send a name. 349 */ 350 mpd_pure 351 const char * 352 mpd_status_get_partition(const struct mpd_status *status); 353 354 /** 355 * Returns the error message 356 */ 357 mpd_pure 358 const char * 359 mpd_status_get_error(const struct mpd_status *status); 360 361 #ifdef __cplusplus 362 } 363 #endif 364 365 #endif 366