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