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#include <stdarg.h> 31 32#ifdef __cplusplus 33extern "C" { 34#endif 35 36#define SHOUTERR_SUCCESS ( 0) /* No error */ 37#define SHOUTERR_INSANE ( -1) /* Nonsensical arguments e.g. self being NULL */ 38#define SHOUTERR_NOCONNECT ( -2) /* Couldn't connect */ 39#define SHOUTERR_NOLOGIN ( -3) /* Login failed */ 40#define SHOUTERR_SOCKET ( -4) /* Socket error */ 41#define SHOUTERR_MALLOC ( -5) /* Out of memory */ 42#define SHOUTERR_METADATA ( -6) 43#define SHOUTERR_CONNECTED ( -7) /* Cannot set parameter while connected */ 44#define SHOUTERR_UNCONNECTED ( -8) /* Not connected */ 45#define SHOUTERR_UNSUPPORTED ( -9) /* This libshout doesn't support the requested option */ 46#define SHOUTERR_BUSY (-10) /* Socket is busy */ 47#define SHOUTERR_NOTLS (-11) /* TLS requested but not supported by peer */ 48#define SHOUTERR_TLSBADCERT (-12) /* TLS connection can not be established because of bad certificate */ 49#define SHOUTERR_RETRY (-13) /* Retry last operation. */ 50 51#define SHOUT_FORMAT_OGG ( 0) /* Ogg */ 52#define SHOUT_FORMAT_MP3 ( 1) /* MP3 */ 53#define SHOUT_FORMAT_WEBM ( 2) /* WebM */ 54#define SHOUT_FORMAT_WEBMAUDIO ( 3) /* WebM, audio only, obsolete. Only used by shout_set_format() */ 55#define SHOUT_FORMAT_MATROSKA ( 4) /* Matroska */ 56 57/* backward-compatibility alias */ 58#define SHOUT_FORMAT_VORBIS SHOUT_FORMAT_OGG 59 60/* Usages */ 61#define SHOUT_USAGE_AUDIO (0x0001U) /* Audio substreams*/ 62#define SHOUT_USAGE_VISUAL (0x0002U) /* Picture/Video substreams (most often combined with SHOUT_USAGE_AUDIO) */ 63#define SHOUT_USAGE_TEXT (0x0004U) /* Text substreams that are not subtitles */ 64#define SHOUT_USAGE_SUBTITLE (0x0008U) /* Subtitle substreams */ 65#define SHOUT_USAGE_LIGHT (0x0010U) /* Light control substreams */ 66#define SHOUT_USAGE_UI (0x0020U) /* User interface data, such as DVD menus or buttons */ 67#define SHOUT_USAGE_METADATA (0x0040U) /* Substreams that include metadata for the stream */ 68#define SHOUT_USAGE_APPLICATION (0x0080U) /* Application specific data substreams */ 69#define SHOUT_USAGE_CONTROL (0x0100U) /* Substreams that control the infrastructure */ 70#define SHOUT_USAGE_COMPLEX (0x0200U) /* Substreams that are themself a mixture of other types */ 71#define SHOUT_USAGE_OTHER (0x0400U) /* Substream of types not listed here */ 72#define SHOUT_USAGE_UNKNOWN (0x0800U) /* The stream MAY contain additional substreams of unknown nature */ 73#define SHOUT_USAGE_3D (0x1000U) /* The Stream contains information for 3D playback */ 74#define SHOUT_USAGE_4D (0x2000U) /* The Stream contains information for 4D/XD playback */ 75 76#define SHOUT_PROTOCOL_HTTP ( 0) 77#define SHOUT_PROTOCOL_XAUDIOCAST ( 1) /* Deprecated. May be removed in future versions. Do not use. */ 78#define SHOUT_PROTOCOL_ICY ( 2) 79#define SHOUT_PROTOCOL_ROARAUDIO ( 3) 80 81/* Possible TLS modes */ 82#define SHOUT_TLS_DISABLED ( 0) /* Do not use TLS at all */ 83#define SHOUT_TLS_AUTO ( 1) /* Autodetect which TLS mode to use if any */ 84#define SHOUT_TLS_AUTO_NO_PLAIN ( 2) /* Like SHOUT_TLS_AUTO_NO_PLAIN but does not allow plain connections */ 85#define SHOUT_TLS_RFC2818 ( 11) /* Use TLS for transport layer like HTTPS [RFC2818] does. */ 86#define SHOUT_TLS_RFC2817 ( 12) /* Use TLS via HTTP Upgrade:-header [RFC2817]. */ 87 88/* Possible values for blocking */ 89#define SHOUT_BLOCKING_DEFAULT (255) /* Use the default blocking setting. */ 90#define SHOUT_BLOCKING_FULL ( 0) /* Block in all I/O related functions */ 91#define SHOUT_BLOCKING_NONE ( 1) /* Do not block in I/O related functions */ 92 93#define SHOUT_AI_BITRATE "bitrate" 94#define SHOUT_AI_SAMPLERATE "samplerate" 95#define SHOUT_AI_CHANNELS "channels" 96#define SHOUT_AI_QUALITY "quality" 97 98#define SHOUT_META_NAME "name" 99#define SHOUT_META_URL "url" 100#define SHOUT_META_GENRE "genre" 101#define SHOUT_META_DESCRIPTION "description" 102#define SHOUT_META_IRC "irc" 103#define SHOUT_META_AIM "aim" 104#define SHOUT_META_ICQ "icq" 105 106#define SHOUT_CALLBACK_PASS ( 1) /* Pass the event to the next handler */ 107 108typedef enum { 109 SHOUT_CONTROL__MIN = 0, 110 SHOUT_CONTROL_GET_SERVER_CERTIFICATE_AS_PEM, 111 SHOUT_CONTROL_GET_SERVER_CERTIFICATE_CHAIN_AS_PEM, 112 SHOUT_CONTROL__MAX = 32767 113} shout_control_t; 114 115typedef enum { 116 SHOUT_EVENT__MIN = 0, 117 SHOUT_EVENT_TLS_CHECK_PEER_CERTIFICATE, 118 SHOUT_EVENT__MAX = 32767 119} shout_event_t; 120 121typedef struct shout shout_t; 122typedef struct _util_dict shout_metadata_t; 123 124typedef int (*shout_callback_t)(shout_t *shout, shout_event_t event, void *userdata, va_list ap); 125 126 127/* ----------------[ Generic ]---------------- */ 128 129/* initializes the shout library. Must be called before anything else */ 130void shout_init(void); 131 132/* shuts down the shout library, deallocating any global storage. Don't call 133 * anything afterwards */ 134void shout_shutdown(void); 135 136/* returns a static version string. Non-null parameters will be set to the 137 * value of the library major, minor, and patch levels, respectively */ 138const char *shout_version(int *major, int *minor, int *patch); 139 140/* Allocates and sets up a new shout_t. Returns NULL if it can't get enough 141 * memory. The returns shout_t must be disposed of with shout_free. */ 142shout_t *shout_new(void); 143 144/* Free all memory allocated by a shout_t */ 145void shout_free(shout_t *self); 146 147/* Returns a statically allocated string describing the last shout error 148 * to occur. Only valid until the next libshout call on this shout_t */ 149const char *shout_get_error(shout_t *self); 150 151/* Return the error code (e.g. SHOUTERR_SOCKET) for this shout instance */ 152int shout_get_errno(shout_t *self); 153 154/* returns SHOUTERR_CONNECTED or SHOUTERR_UNCONNECTED */ 155int shout_get_connected(shout_t *self); 156 157 158/* ----------------[ Configuration ]---------------- */ 159/* Parameter manipulation functions. libshout makes copies of all parameters, 160 * the caller may free its copies after giving them to libshout. May return 161 * SHOUTERR_MALLOC */ 162 163/* Connection parameters */ 164int shout_set_host(shout_t *self, const char *host); 165const char *shout_get_host(shout_t *self); 166 167int shout_set_port(shout_t *self, unsigned short port); 168unsigned short shout_get_port(shout_t *self); 169 170int shout_set_agent(shout_t *self, const char *agent); 171const char *shout_get_agent(shout_t *self); 172 173/* See SHOUT_TLS_* above */ 174int shout_set_tls(shout_t *self, int mode); 175int shout_get_tls(shout_t *self); 176 177/* Set the directory for CA certs. Default: operating system's default */ 178int shout_set_ca_directory(shout_t *self, const char *directory); 179const char *shout_get_ca_directory(shout_t *self); 180 181/* Set a CA cert file for checking. If you use a self signed server cert 182 * you can pass this cert using this function for verification. 183 * Default: operating system's default */ 184int shout_set_ca_file(shout_t *self, const char *file); 185const char *shout_get_ca_file(shout_t *self); 186 187/* Set list of allowed ciphers. 188 * This function should only be used in case of using an old libshout 189 * after some attacks got known. Watch the icecast mailinglist for 190 * known problems. 191 * DO NOT SET THIS TO ANY FIXED VALUE. IF YOU USE THIS FUNCTION 192 * EXPOSE IT TO THE USER. OTHERWISE YOU WILL HARM SECURITY. 193 * Default: internal list of secure ciphers. */ 194int shout_set_allowed_ciphers(shout_t *self, const char *ciphers); 195const char *shout_get_allowed_ciphers(shout_t *self); 196 197/* Authentication parameters */ 198int shout_set_user(shout_t *self, const char *username); 199const char *shout_get_user(shout_t *self); 200 201int shout_set_password(shout_t *, const char *password); 202const char *shout_get_password(shout_t *self); 203 204/* Set a client certificate for TLS connections. 205 * This must be in PEM format with both cert and private key in the same file. 206 * Default: none. */ 207int shout_set_client_certificate(shout_t *self, const char *certificate); 208const char *shout_get_client_certificate(shout_t *self); 209 210/* Mount parameters */ 211int shout_set_mount(shout_t *self, const char *mount); 212const char *shout_get_mount(shout_t *self); 213 214/* Other parameters */ 215/* takes a SHOUT_AI_xxxx argument */ 216int shout_set_audio_info(shout_t *self, const char *name, const char *value); 217const char *shout_get_audio_info(shout_t *self, const char *name); 218 219/* takes a SHOUT_META_xxxx argument */ 220int shout_set_meta(shout_t *self, const char *name, const char *value); 221const char *shout_get_meta(shout_t *self, const char *name); 222 223int shout_set_public(shout_t *self, unsigned int make_public); 224unsigned int shout_get_public(shout_t *self); 225 226/* Set the content language. 227 * Values as per RFC5646 Section 2.1. 228 * This lists the target audiance language(s), not the language of songs 229 * (unless the station has a focus on songs in a specific language). 230 * The value of NULL is allowed if the content language is not known or is expected to change. 231 * 232 * Examples: 233 * A German station with moderations and news in German and Gamern and international songs 234 * would generally set this to "de-DE". 235 * A similar station in Switzerland would set this to "de-CH". 236 * A station with content in Portuguese, and Klingon should set this to "pt, tlh". 237 */ 238int shout_set_content_language(shout_t *self, const char *content_language); 239const char *shout_get_content_language(shout_t *self); 240 241/* Set the format of the content to send. 242 * * format is one of SHOUT_FORMAT_xxxx. 243 * * usage is a bit vector composed of SHOUT_USAGE_xxxx. 244 * * codecs is NULL as of this version. Future versions will also support NULL. 245 */ 246int shout_set_content_format(shout_t *self, unsigned int format, unsigned int usage, const char *codecs); 247int shout_get_content_format(shout_t *self, unsigned int *format, unsigned int *usage, const char **codecs); 248 249/* takes a SHOUT_PROTOCOL_xxxxx argument */ 250int shout_set_protocol(shout_t *self, unsigned int protocol); 251unsigned int shout_get_protocol(shout_t *self); 252 253/* Instructs libshout to use nonblocking I/O. Must be called before 254 * shout_open (no switching back and forth midstream at the moment). 255 * nonblocking is one of SHOUT_BLOCKING_xxx. */ 256int shout_set_nonblocking(shout_t* self, unsigned int nonblocking); 257unsigned int shout_get_nonblocking(shout_t *self); 258 259 260/* ----------------[ Actions ]---------------- */ 261 262/* Opens a connection to the server. All parameters must already be set */ 263int shout_open(shout_t *self); 264 265/* Closes a connection to the server */ 266int shout_close(shout_t *self); 267 268/* Send data to the server, parsing it for format specific timing info */ 269int shout_send(shout_t *self, const unsigned char *data, size_t len); 270 271/* Send unparsed data to the server. Do not use this unless you know 272 * what you are doing. 273 * Returns the number of bytes written, or < 0 on error. 274 */ 275ssize_t shout_send_raw(shout_t *self, const unsigned char *data, size_t len); 276 277/* return the number of bytes currently on the write queue (only makes sense in 278 * nonblocking mode). */ 279ssize_t shout_queuelen(shout_t *self); 280 281/* Puts caller to sleep until it is time to send more data to the server */ 282void shout_sync(shout_t *self); 283 284/* Amount of time in ms caller should wait before sending again */ 285int shout_delay(shout_t *self); 286 287 288/* ----------------[ MP3/AAC ONLY ]---------------- */ 289/* Functions in this block are for use with MP3, and AAC streams only */ 290 291/* Sets MP3 metadata. 292 * Returns: 293 * SHOUTERR_SUCCESS 294 * SHOUTERR_UNSUPPORTED if format isn't MP3 295 * SHOUTERR_MALLOC 296 * SHOUTERR_INSANE 297 * SHOUTERR_NOCONNECT 298 * SHOUTERR_SOCKET 299 */ 300int shout_set_metadata(shout_t *self, shout_metadata_t *metadata); 301 302/* Allocates a new metadata structure. Must be freed by shout_metadata_free. */ 303shout_metadata_t *shout_metadata_new(void); 304 305/* Free resources allocated by shout_metadata_t */ 306void shout_metadata_free(shout_metadata_t *self); 307 308/* Add a parameter to the metadata structure. 309 * Returns: 310 * SHOUTERR_SUCCESS on success 311 * SHOUTERR_INSANE if self isn't a valid shout_metadata_t* or name is null 312 * SHOUTERR_MALLOC if memory can't be allocated */ 313int shout_metadata_add(shout_metadata_t *self, const char *name, const char *value); 314 315 316/* ----------------[ Advanced ]---------------- */ 317/* Advanced. Do not use. */ 318 319int shout_control(shout_t *self, shout_control_t control, ...); 320int shout_set_callback(shout_t *self, shout_callback_t callback, void *userdata); 321 322 323/* ----------------[ Obsolete ]---------------- */ 324/* Those functions are obsolete and MUST NOT be used in newer software. 325 * They may be removed with any future version. 326 */ 327 328int shout_set_name(shout_t *self, const char *name); // obsolete 329const char *shout_get_name(shout_t *self); // obsolete 330 331int shout_set_url(shout_t *self, const char *url); // obsolete 332const char *shout_get_url(shout_t *self); // obsolete 333 334int shout_set_genre(shout_t *self, const char *genre); // obsolete 335const char *shout_get_genre(shout_t *self); // obsolete 336 337int shout_set_description(shout_t *self, const char *description); // obsolete 338const char *shout_get_description(shout_t *self); // obsolete 339 340/* takes a SHOUT_FORMAT_xxxx argument */ 341int shout_set_format(shout_t *self, unsigned int format); // obsolete 342unsigned int shout_get_format(shout_t *self); // obsolete 343 344int shout_set_dumpfile(shout_t *self, const char *dumpfile); // obsolete 345const char *shout_get_dumpfile(shout_t *self); // obsolete 346 347#ifdef __cplusplus 348} 349#endif 350 351/* --- Compiled features --- */ 352 353#define SHOUT_THREADSAFE @SHOUT_THREADSAFE@ 354#define SHOUT_TLS @SHOUT_TLS@ 355 356#endif /* __LIBSHOUT_SHOUT_H__ */ 357