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_IDLE_H 40 #define MPD_IDLE_H 41 42 #include "compiler.h" 43 44 #include <stdbool.h> 45 46 struct mpd_pair; 47 struct mpd_connection; 48 49 /** 50 * This enum contains bit masks for all idle events. 51 * 52 * @since libmpdclient 2.5 added support for #MPD_IDLE_STICKER, 53 * #MPD_IDLE_SUBSCRIPTION and #MPD_IDLE_MESSAGE. 54 * @since libmpdclient 2.17 added support for #MPD_IDLE_PARTITION. 55 * @since libmpdclient 2.19 added support for #MPD_IDLE_NEIGHBOR, 56 * #MPD_IDLE_MOUNT 57 */ 58 enum mpd_idle { 59 /** song database has been updated */ 60 MPD_IDLE_DATABASE = 0x1, 61 62 /** a stored playlist has been modified, created, deleted or 63 renamed */ 64 MPD_IDLE_STORED_PLAYLIST = 0x2, 65 66 /** the queue has been modified */ 67 MPD_IDLE_QUEUE = 0x4, 68 69 /** deprecated, don't use */ 70 MPD_IDLE_PLAYLIST = MPD_IDLE_QUEUE, 71 72 /** the player state has changed: play, stop, pause, seek, ... */ 73 MPD_IDLE_PLAYER = 0x8, 74 75 /** the volume has been modified */ 76 MPD_IDLE_MIXER = 0x10, 77 78 /** an audio output device has been enabled or disabled */ 79 MPD_IDLE_OUTPUT = 0x20, 80 81 /** options have changed: crossfade, random, repeat, ... */ 82 MPD_IDLE_OPTIONS = 0x40, 83 84 /** a database update has started or finished. */ 85 MPD_IDLE_UPDATE = 0x80, 86 87 /** a sticker has been modified. */ 88 MPD_IDLE_STICKER = 0x100, 89 90 /** a client has subscribed to or unsubscribed from a channel */ 91 MPD_IDLE_SUBSCRIPTION = 0x200, 92 93 /** a message on a subscribed channel was received */ 94 MPD_IDLE_MESSAGE = 0x400, 95 96 /** a partition was added or changed */ 97 MPD_IDLE_PARTITION = 0x800, 98 99 /** a neighbor was found or lost */ 100 MPD_IDLE_NEIGHBOR = 0x1000, 101 102 /** the mount list has changed */ 103 MPD_IDLE_MOUNT = 0x2000, 104 }; 105 106 #ifdef __cplusplus 107 extern "C" { 108 #endif 109 110 /** 111 * Returns the name of the specified idle event. 112 * 113 * @param idle an idle event id 114 * @return the name, or NULL if that event is not known 115 */ 116 mpd_const 117 const char * 118 mpd_idle_name(enum mpd_idle idle); 119 120 /** 121 * Parses the name of an idle event. 122 * 123 * @param name an idle event name 124 * @return the id, or 0 if that event is not known 125 */ 126 mpd_pure 127 enum mpd_idle 128 mpd_idle_name_parse(const char *name); 129 130 /** 131 * Enters "idle" mode: MPD will stall the response until an event has 132 * occurred. Call mpd_send_noidle() to abort the idle mode, or 133 * mpd_recv_idle() to read the event mask (or synchronously wait for 134 * events). 135 * 136 * @param connection the connection to MPD 137 * @return true on success 138 */ 139 bool 140 mpd_send_idle(struct mpd_connection *connection); 141 142 /** 143 * Same as mpd_send_idle(), but listen only on specific events. 144 * 145 * @param connection the connection to MPD 146 * @param mask a bit mask of idle events; must not be 0 147 * @return true on success 148 */ 149 bool 150 mpd_send_idle_mask(struct mpd_connection *connection, enum mpd_idle mask); 151 152 /** 153 * Tells MPD to leave the "idle" mode. MPD will then respond with a 154 * list of events which have occurred (which may be empty). Call 155 * mpd_recv_idle() after that. 156 * 157 * @param connection the connection to MPD 158 * @return true on success 159 */ 160 bool 161 mpd_send_noidle(struct mpd_connection *connection); 162 163 /** 164 * Parses a "changed" pair, which is part of MPD's response to the 165 * "idle" command. 166 * 167 * @param pair the "changed" pair 168 * @return an idle code, or 0 if the pair was not understood 169 */ 170 mpd_pure 171 enum mpd_idle 172 mpd_idle_parse_pair(const struct mpd_pair *pair); 173 174 /** 175 * Waits until MPD sends the list of idle events and returns it in a 176 * bit mask. 177 * 178 * @param connection the connection to MPD 179 * @param disable_timeout if true, then libmpdclient temporarily 180 * disables the configured timeout (see mpd_connection_set_timeout()): 181 * this function blocks forever, until either MPD sends a response, or 182 * an error occurs. 183 * @return the event bit mask, or 0 on error or if there were no 184 * events 185 */ 186 enum mpd_idle 187 mpd_recv_idle(struct mpd_connection *connection, bool disable_timeout); 188 189 /** 190 * Shortcut for mpd_send_idle() and mpd_recv_idle(). During 191 * mpd_recv_idle(), the configured timeout is disabled. 192 * 193 * @param connection the connection to MPD 194 * @return the event bit mask, or 0 on error 195 */ 196 enum mpd_idle 197 mpd_run_idle(struct mpd_connection *connection); 198 199 /** 200 * Shortcut for mpd_send_idle_mask() and mpd_recv_idle(). During 201 * mpd_recv_idle(), the configured timeout is disabled. 202 * 203 * @param connection the connection to MPD 204 * @param mask a bit mask of idle events; must not be 0 205 * @return the event bit mask, or 0 on error 206 */ 207 enum mpd_idle 208 mpd_run_idle_mask(struct mpd_connection *connection, enum mpd_idle mask); 209 210 /** 211 * Shortcut for mpd_send_noidle() and mpd_recv_idle(). During 212 * mpd_recv_idle(), the configured timeout is not disabled. 213 * 214 * @param connection the connection to MPD 215 * @return the event bit mask, or 0 on error or if there were no 216 * events 217 */ 218 enum mpd_idle 219 mpd_run_noidle(struct mpd_connection *connection); 220 221 #ifdef __cplusplus 222 } 223 #endif 224 225 #endif 226