1 /* shout.h 2 * 3 * API for libshout, the streaming library for icecast 4 * 5 * Copyright (C) 2002-2003 the Icecast team <team@icecast.org>, 6 * Copyright (C) 2012-2015 Philipp "ph3-der-loewe" Schafft <lion@lion.leolix.org> 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Library General Public 10 * License as published by the Free Software Foundation; either 11 * version 2 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Library General Public License for more details. 17 * 18 * You should have received a copy of the GNU Library General Public 19 * License along with this library; if not, write to the Free 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 */ 22 #ifndef __LIBSHOUT_SHOUT_H__ 23 #define __LIBSHOUT_SHOUT_H__ 24 25 #include <sys/types.h> 26 #if defined(WIN32) && !defined(__MINGW64__) && !defined(__MINGW32__) 27 #include <os.h> 28 #endif 29 30 #define SHOUTERR_SUCCESS ( 0) /* No error */ 31 #define SHOUTERR_INSANE ( -1) /* Nonsensical arguments e.g. self being NULL */ 32 #define SHOUTERR_NOCONNECT ( -2) /* Couldn't connect */ 33 #define SHOUTERR_NOLOGIN ( -3) /* Login failed */ 34 #define SHOUTERR_SOCKET ( -4) /* Socket error */ 35 #define SHOUTERR_MALLOC ( -5) /* Out of memory */ 36 #define SHOUTERR_METADATA ( -6) 37 #define SHOUTERR_CONNECTED ( -7) /* Cannot set parameter while connected */ 38 #define SHOUTERR_UNCONNECTED ( -8) /* Not connected */ 39 #define SHOUTERR_UNSUPPORTED ( -9) /* This libshout doesn't support the requested option */ 40 #define SHOUTERR_BUSY (-10) /* Socket is busy */ 41 #define SHOUTERR_NOTLS (-11) /* TLS requested but not supported by peer */ 42 #define SHOUTERR_TLSBADCERT (-12) /* TLS connection can not be established because of bad certificate */ 43 #define SHOUTERR_RETRY (-13) /* Retry last operation. */ 44 45 #define SHOUT_FORMAT_OGG ( 0) /* application/ogg */ 46 #define SHOUT_FORMAT_MP3 ( 1) /* audio/mpeg */ 47 #define SHOUT_FORMAT_WEBM ( 2) /* video/webm */ 48 #define SHOUT_FORMAT_WEBMAUDIO ( 3) /* audio/webm audio only */ 49 #define SHOUT_FORMAT_AAC ( 10) /* audio/aac */ 50 #define SHOUT_FORMAT_AACPLUS ( 11) /* audio/aacp */ 51 52 /* backward-compatibility alias */ 53 #define SHOUT_FORMAT_VORBIS SHOUT_FORMAT_OGG 54 55 #define SHOUT_PROTOCOL_HTTP ( 0) 56 #define SHOUT_PROTOCOL_XAUDIOCAST ( 1) 57 #define SHOUT_PROTOCOL_ICY ( 2) 58 #define SHOUT_PROTOCOL_ROARAUDIO ( 3) 59 60 /* Possible TLS modes */ 61 #define SHOUT_TLS_DISABLED ( 0) /* Do not use TLS at all */ 62 #define SHOUT_TLS_AUTO ( 1) /* Autodetect which TLS mode to use if any */ 63 #define SHOUT_TLS_AUTO_NO_PLAIN ( 2) /* Like SHOUT_TLS_AUTO_NO_PLAIN but does not allow plain connections */ 64 #define SHOUT_TLS_RFC2818 ( 11) /* Use TLS for transport layer like HTTPS [RFC2818] does. */ 65 #define SHOUT_TLS_RFC2817 ( 12) /* Use TLS via HTTP Upgrade:-header [RFC2817]. */ 66 67 #define SHOUT_AI_BITRATE "bitrate" 68 #define SHOUT_AI_SAMPLERATE "samplerate" 69 #define SHOUT_AI_CHANNELS "channels" 70 #define SHOUT_AI_QUALITY "quality" 71 72 #define SHOUT_META_NAME "name" 73 #define SHOUT_META_URL "url" 74 #define SHOUT_META_GENRE "genre" 75 #define SHOUT_META_DESCRIPTION "description" 76 #define SHOUT_META_IRC "irc" 77 #define SHOUT_META_AIM "aim" 78 #define SHOUT_META_ICQ "icq" 79 80 typedef struct shout shout_t; 81 typedef struct _util_dict shout_metadata_t; 82 83 #ifdef __cplusplus 84 extern "C" { 85 #endif 86 87 /* initializes the shout library. Must be called before anything else */ 88 void shout_init(void); 89 90 /* shuts down the shout library, deallocating any global storage. Don't call 91 * anything afterwards */ 92 void shout_shutdown(void); 93 94 /* returns a static version string. Non-null parameters will be set to the 95 * value of the library major, minor, and patch levels, respectively */ 96 const char *shout_version(int *major, int *minor, int *patch); 97 98 /* Allocates and sets up a new shout_t. Returns NULL if it can't get enough 99 * memory. The returns shout_t must be disposed of with shout_free. */ 100 shout_t *shout_new(void); 101 102 /* Free all memory allocated by a shout_t */ 103 void shout_free(shout_t *self); 104 105 /* Returns a statically allocated string describing the last shout error 106 * to occur. Only valid until the next libshout call on this shout_t */ 107 const char *shout_get_error(shout_t *self); 108 109 /* Return the error code (e.g. SHOUTERR_SOCKET) for this shout instance */ 110 int shout_get_errno(shout_t *self); 111 112 /* returns SHOUTERR_CONNECTED or SHOUTERR_UNCONNECTED */ 113 int shout_get_connected(shout_t *self); 114 115 /* Parameter manipulation functions. libshout makes copies of all parameters, 116 * the caller may free its copies after giving them to libshout. May return 117 * SHOUTERR_MALLOC */ 118 119 /* Connection parameters */ 120 int shout_set_host(shout_t *self, const char *host); 121 const char *shout_get_host(shout_t *self); 122 123 int shout_set_port(shout_t *self, unsigned short port); 124 unsigned short shout_get_port(shout_t *self); 125 126 int shout_set_agent(shout_t *self, const char *agent); 127 const char *shout_get_agent(shout_t *self); 128 129 /* See SHOUT_TLS_* above */ 130 int shout_set_tls(shout_t *self, int mode); 131 int shout_get_tls(shout_t *self); 132 133 /* Set the directory for CA certs. Default: operating system's default */ 134 int shout_set_ca_directory(shout_t *self, const char *directory); 135 const char *shout_get_ca_directory(shout_t *self); 136 137 /* Set a CA cert file for checking. If you use a self signed server cert 138 * you can pass this cert using this function for verification. 139 * Default: operating system's default */ 140 int shout_set_ca_file(shout_t *self, const char *file); 141 const char *shout_get_ca_file(shout_t *self); 142 143 /* Set list of allowed ciphers. 144 * This function should only be used in case of using an old libshout 145 * after some attacks got known. Watch the icecast mailinglist for 146 * known problems. 147 * DO NOT SET THIS TO ANY FIXED VALUE. IF YOU USE THIS FUNCTION 148 * EXPOSE IT TO THE USER. OTHERWISE YOU WILL HARM SECURITY. 149 * Default: internal list of secure ciphers. */ 150 int shout_set_allowed_ciphers(shout_t *self, const char *ciphers); 151 const char *shout_get_allowed_ciphers(shout_t *self); 152 153 /* Authentication parameters */ 154 int shout_set_user(shout_t *self, const char *username); 155 const char *shout_get_user(shout_t *self); 156 157 int shout_set_password(shout_t *, const char *password); 158 const char *shout_get_password(shout_t *self); 159 160 /* Set a client certificate for TLS connections. 161 * This must be in PEM format with both cert and private key in the same file. 162 * Default: none. */ 163 int shout_set_client_certificate(shout_t *self, const char *certificate); 164 const char *shout_get_client_certificate(shout_t *self); 165 166 /* Mount parameters */ 167 int shout_set_mount(shout_t *self, const char *mount); 168 const char *shout_get_mount(shout_t *self); 169 170 /* Other parameters */ 171 int shout_set_name(shout_t *self, const char *name); // obsolete 172 const char *shout_get_name(shout_t *self); // obsolete 173 174 int shout_set_url(shout_t *self, const char *url); // obsolete 175 const char *shout_get_url(shout_t *self); // obsolete 176 177 int shout_set_genre(shout_t *self, const char *genre); // obsolete 178 const char *shout_get_genre(shout_t *self); // obsolete 179 180 int shout_set_description(shout_t *self, const char *description); // obsolete 181 const char *shout_get_description(shout_t *self); // obsolete 182 183 int shout_set_dumpfile(shout_t *self, const char *dumpfile); 184 const char *shout_get_dumpfile(shout_t *self); 185 186 int shout_set_audio_info(shout_t *self, const char *name, const char *value); 187 const char *shout_get_audio_info(shout_t *self, const char *name); 188 189 /* takes a SHOUT_META_xxxx argument */ 190 int shout_set_meta(shout_t *self, const char *name, const char *value); 191 const char *shout_get_meta(shout_t *self, const char *name); 192 193 int shout_set_public(shout_t *self, unsigned int make_public); 194 unsigned int shout_get_public(shout_t *self); 195 196 /* takes a SHOUT_FORMAT_xxxx argument */ 197 int shout_set_format(shout_t *self, unsigned int format); 198 unsigned int shout_get_format(shout_t *self); 199 200 /* takes a SHOUT_PROTOCOL_xxxxx argument */ 201 int shout_set_protocol(shout_t *self, unsigned int protocol); 202 unsigned int shout_get_protocol(shout_t *self); 203 204 /* Explicitly sets the mimetype. Set to NULL to revert back to the default. 205 The default value is dependent on the format setting. */ 206 int shout_set_mimetype(shout_t *self, const char *mimetype); 207 208 const char *shout_get_mimetype(shout_t *self); 209 210 /* Instructs libshout to use nonblocking I/O. Must be called before 211 * shout_open (no switching back and forth midstream at the moment). */ 212 int shout_set_nonblocking(shout_t* self, unsigned int nonblocking); 213 unsigned int shout_get_nonblocking(shout_t *self); 214 215 /* Opens a connection to the server. All parameters must already be set */ 216 int shout_open(shout_t *self); 217 218 /* Closes a connection to the server */ 219 int shout_close(shout_t *self); 220 221 /* Send data to the server, parsing it for format specific timing info */ 222 int shout_send(shout_t *self, const unsigned char *data, size_t len); 223 224 /* Send unparsed data to the server. Do not use this unless you know 225 * what you are doing. 226 * Returns the number of bytes written, or < 0 on error. 227 */ 228 ssize_t shout_send_raw(shout_t *self, const unsigned char *data, size_t len); 229 230 /* return the number of bytes currently on the write queue (only makes sense in 231 * nonblocking mode). */ 232 ssize_t shout_queuelen(shout_t *self); 233 234 /* Puts caller to sleep until it is time to send more data to the server */ 235 void shout_sync(shout_t *self); 236 237 /* Amount of time in ms caller should wait before sending again */ 238 int shout_delay(shout_t *self); 239 240 /* Sets MP3 metadata. 241 * Returns: 242 * SHOUTERR_SUCCESS 243 * SHOUTERR_UNSUPPORTED if format isn't MP3 244 * SHOUTERR_MALLOC 245 * SHOUTERR_INSANE 246 * SHOUTERR_NOCONNECT 247 * SHOUTERR_SOCKET 248 */ 249 int shout_set_metadata(shout_t *self, shout_metadata_t *metadata); 250 251 /* Allocates a new metadata structure. Must be freed by shout_metadata_free. */ 252 shout_metadata_t *shout_metadata_new(void); 253 254 /* Free resources allocated by shout_metadata_t */ 255 void shout_metadata_free(shout_metadata_t *self); 256 257 /* Add a parameter to the metadata structure. 258 * Returns: 259 * SHOUTERR_SUCCESS on success 260 * SHOUTERR_INSANE if self isn't a valid shout_metadata_t* or name is null 261 * SHOUTERR_MALLOC if memory can't be allocated */ 262 int shout_metadata_add(shout_metadata_t *self, const char *name, const char *value); 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 /* --- Compiled features --- */ 269 270 #define SHOUT_THREADSAFE 1 271 #define SHOUT_TLS 1 272 273 #endif /* __LIBSHOUT_SHOUT_H__ */ 274