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
80typedef struct shout shout_t;
81typedef struct _util_dict shout_metadata_t;
82
83#ifdef __cplusplus
84extern "C" {
85#endif
86
87/* initializes the shout library. Must be called before anything else */
88void shout_init(void);
89
90/* shuts down the shout library, deallocating any global storage. Don't call
91 * anything afterwards */
92void 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 */
96const 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. */
100shout_t *shout_new(void);
101
102/* Free all memory allocated by a shout_t */
103void 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 */
107const char *shout_get_error(shout_t *self);
108
109/* Return the error code (e.g. SHOUTERR_SOCKET) for this shout instance */
110int shout_get_errno(shout_t *self);
111
112/* returns SHOUTERR_CONNECTED or SHOUTERR_UNCONNECTED */
113int 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 */
120int shout_set_host(shout_t *self, const char *host);
121const char *shout_get_host(shout_t *self);
122
123int shout_set_port(shout_t *self, unsigned short port);
124unsigned short shout_get_port(shout_t *self);
125
126int shout_set_agent(shout_t *self, const char *agent);
127const char *shout_get_agent(shout_t *self);
128
129/* See SHOUT_TLS_* above */
130int shout_set_tls(shout_t *self, int mode);
131int shout_get_tls(shout_t *self);
132
133/* Set the directory for CA certs. Default: operating system's default */
134int shout_set_ca_directory(shout_t *self, const char *directory);
135const 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 */
140int shout_set_ca_file(shout_t *self, const char *file);
141const 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. */
150int shout_set_allowed_ciphers(shout_t *self, const char *ciphers);
151const char *shout_get_allowed_ciphers(shout_t *self);
152
153/* Authentication parameters */
154int shout_set_user(shout_t *self, const char *username);
155const char *shout_get_user(shout_t *self);
156
157int shout_set_password(shout_t *, const char *password);
158const 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. */
163int shout_set_client_certificate(shout_t *self, const char *certificate);
164const char *shout_get_client_certificate(shout_t *self);
165
166/* Mount parameters */
167int shout_set_mount(shout_t *self, const char *mount);
168const char *shout_get_mount(shout_t *self);
169
170/* Other parameters */
171int shout_set_name(shout_t *self, const char *name); // obsolete
172const char *shout_get_name(shout_t *self); // obsolete
173
174int shout_set_url(shout_t *self, const char *url); // obsolete
175const char *shout_get_url(shout_t *self); // obsolete
176
177int shout_set_genre(shout_t *self, const char *genre); // obsolete
178const char *shout_get_genre(shout_t *self); // obsolete
179
180int shout_set_description(shout_t *self, const char *description); // obsolete
181const char *shout_get_description(shout_t *self); // obsolete
182
183int shout_set_dumpfile(shout_t *self, const char *dumpfile);
184const char *shout_get_dumpfile(shout_t *self);
185
186int shout_set_audio_info(shout_t *self, const char *name, const char *value);
187const char *shout_get_audio_info(shout_t *self, const char *name);
188
189/* takes a SHOUT_META_xxxx argument */
190int shout_set_meta(shout_t *self, const char *name, const char *value);
191const char *shout_get_meta(shout_t *self, const char *name);
192
193int shout_set_public(shout_t *self, unsigned int make_public);
194unsigned int shout_get_public(shout_t *self);
195
196/* takes a SHOUT_FORMAT_xxxx argument */
197int shout_set_format(shout_t *self, unsigned int format);
198unsigned int shout_get_format(shout_t *self);
199
200/* takes a SHOUT_PROTOCOL_xxxxx argument */
201int shout_set_protocol(shout_t *self, unsigned int protocol);
202unsigned 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. */
206int shout_set_mimetype(shout_t *self, const char *mimetype);
207
208const 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). */
212int shout_set_nonblocking(shout_t* self, unsigned int nonblocking);
213unsigned int shout_get_nonblocking(shout_t *self);
214
215/* Opens a connection to the server.  All parameters must already be set */
216int shout_open(shout_t *self);
217
218/* Closes a connection to the server */
219int shout_close(shout_t *self);
220
221/* Send data to the server, parsing it for format specific timing info */
222int 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 */
228ssize_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). */
232ssize_t shout_queuelen(shout_t *self);
233
234/* Puts caller to sleep until it is time to send more data to the server */
235void shout_sync(shout_t *self);
236
237/* Amount of time in ms caller should wait before sending again */
238int 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 */
249int shout_set_metadata(shout_t *self, shout_metadata_t *metadata);
250
251/* Allocates a new metadata structure.  Must be freed by shout_metadata_free. */
252shout_metadata_t *shout_metadata_new(void);
253
254/* Free resources allocated by shout_metadata_t */
255void 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 */
262int 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 @SHOUT_THREADSAFE@
271#define SHOUT_TLS        @SHOUT_TLS@
272
273#endif /* __LIBSHOUT_SHOUT_H__ */
274