include/mpd/async.h

   1 /* libmpdclient
   2    (c) 2003-2017 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    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
  20    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  21    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  23    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  24    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  25    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  26    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 */
  28
  29 /*! \file
  30  * \brief Asynchronous MPD connections
  31  *
  32  * This class provides a very basic interface to MPD connections.  It
  33  * does not know much about the MPD protocol, it does not know any
  34  * specific MPD command.
  35  *
  36  * The constructor expects a socket descriptor which is already
  37  * connected to MPD.  The first thing it does is read the server's
  38  * handshake code ("OK MPD 0.15.0").
  39  */
  40
  41 #ifndef MPD_ASYNC_H
  42 #define MPD_ASYNC_H
  43
  44 #include "error.h"
  45 #include "compiler.h"
  46
  47 #include <stdbool.h>
  48 #include <stdarg.h>
  49
  50 /**
  51  * Event bit mask for polling.
  52  */
  53 enum mpd_async_event {
  54         /** ready to read from the file descriptor */
  55         MPD_ASYNC_EVENT_READ = 1,
  56
  57         /** ready to write to the file descriptor */
  58         MPD_ASYNC_EVENT_WRITE = 2,
  59
  60         /** hangup detected */
  61         MPD_ASYNC_EVENT_HUP = 4,
  62
  63         /** I/O error */
  64         MPD_ASYNC_EVENT_ERROR = 8,
  65 };
  66
  67 /**
  68  * \struct mpd_async
  69  *
  70  * This opaque object represents an asynchronous connection to a MPD
  71  * server.  Call mpd_async_new() to create a new instance.
  72  */
  73 struct mpd_async;
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 /**
  80  * Creates a new asynchronous MPD connection, based on a stream socket
  81  * connected with MPD.
  82  *
  83  * @param fd the socket file descriptor of the stream connection to MPD
  84  * @return a mpd_async object, or NULL on out of memory
  85  */
  86 mpd_malloc
  87 struct mpd_async *
  88 mpd_async_new(int fd);
  89
  90 /**
  91  * Closes the socket and frees memory.
  92  */
  93 void
  94 mpd_async_free(struct mpd_async *async);
  95
  96 /**
  97  * After an error has occurred, this function returns the error code.
  98  * If no error has occurred, it returns #MPD_ERROR_SUCCESS.
  99  */
 100 mpd_pure
 101 enum mpd_error
 102 mpd_async_get_error(const struct mpd_async *async);
 103
 104 /**
 105  * If mpd_async_is_alive() returns false, this function returns the
 106  * human readable error message which caused this.  This message is
 107  * optional, and may be NULL.  The pointer is invalidated by
 108  * mpd_async_free().
 109  *
 110  * For #MPD_ERROR_SERVER, the error message is encoded in UTF-8.
 111  * #MPD_ERROR_SYSTEM obtains its error message from the operating
 112  * system, and thus the locale's character set (and probably language)
 113  * is used.  Keep that in mind when you print error messages.
 114  */
 115 mpd_pure
 116 const char *
 117 mpd_async_get_error_message(const struct mpd_async *async);
 118
 119 /**
 120  * Returns the error code from the operating system; on most operating
 121  * systems, this is the errno value.  Calling this function is only
 122  * valid if mpd_async_get_error() returned #MPD_ERROR_SYSTEM.
 123  *
 124  * May be 0 if the operating system did not specify an error code.
 125  */
 126 mpd_pure
 127 int
 128 mpd_async_get_system_error(const struct mpd_async *async);
 129
 130 /**
 131  * Returns the file descriptor which should be polled by the caller.
 132  * Do not use the file descriptor for anything except polling!  The
 133  * file descriptor never changes during the lifetime of this
 134  * #mpd_async object.
 135  */
 136 mpd_pure
 137 int
 138 mpd_async_get_fd(const struct mpd_async *async);
 139
 140 /**
 141  * Enables (or disables) TCP keepalives.
 142  *
 143  * Keepalives are enabled using the SO_KEEPALIVE socket option.  They may be
 144  * required for long-idled connections to persist on some networks that
 145  * would otherwise terminate inactive TCP sessions.
 146  *
 147  * The default value is false.
 148  *
 149  * @param async the #mpd_async object
 150  * @param keepalive whether TCP keepalives should be enabled
 151  *
 152  * @since libmpdclient 2.10
 153  */
 154 void
 155 mpd_async_set_keepalive(struct mpd_async *async,
 156                         bool keepalive);
 157
 158 /**
 159  * Returns a bit mask of events which should be polled for.
 160  */
 161 mpd_pure
 162 enum mpd_async_event
 163 mpd_async_events(const struct mpd_async *async);
 164
 165 /**
 166  * Call this function when poll() has returned events for this
 167  * object's file descriptor.  libmpdclient will attempt to perform I/O
 168  * operations.
 169  *
 170  * @return false if the connection was closed due to an error
 171  */
 172 bool
 173 mpd_async_io(struct mpd_async *async, enum mpd_async_event events);
 174
 175 /**
 176  * Appends a command to the output buffer.
 177  *
 178  * @param async the connection
 179  * @param command the command name, followed by arguments, terminated by
 180  * NULL
 181  * @param args the argument list
 182  * @return true on success, false if the buffer is full
 183  */
 184 bool
 185 mpd_async_send_command_v(struct mpd_async *async, const char *command,
 186                          va_list args);
 187
 188 /**
 189  * Appends a command to the output buffer.
 190  *
 191  * @param async the connection
 192  * @param command the command name, followed by arguments, terminated by
 193  * NULL
 194  * @return true on success, false if the buffer is full
 195  */
 196 mpd_sentinel
 197 bool
 198 mpd_async_send_command(struct mpd_async *async, const char *command, ...);
 199
 200 /**
 201  * Receives a line from the input buffer.  The result will be
 202  * null-terminated, without the newline character.  The pointer is
 203  * only valid until the next async function is called.
 204  *
 205  * @param async the connection
 206  * @return a line on success, NULL otherwise
 207  */
 208 mpd_malloc
 209 char *
 210 mpd_async_recv_line(struct mpd_async *async);
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif