Programming With Libshout 2

Functions

Global functions void shout_init Initializes the shout library. Currently this initializes the networking mutexes when the library is built with thread safety. This function must always be called before any other libshout function. void shout_shutdown Releases any resources which may have been allocated by a call to shout_init. An application should call this function after it has finished using libshout. const char *shout_version int *major int *minor int *patch Returns the version of the libshout library, both as a string via the return value, and as a set of integers corresponding to the major, minor and patch levels of the library. The application must allocate the integer parameters. If any parameter is NULL, libshout will not attempt to set it.

Managing connections shout_t *shout_new Allocates a new shout_t structure. May return NULL if no memory is available. The result should be disposed of with shout_free when you are finished with it. void shout_free shout_t *self Frees a shout_t allocated by shout_new. int shout_open shout_t *self Opens a connection to a server. All connection parameters must have been set prior to this call. Return Values SHOUTERR_SUCCESS The connection was successfully opened. SHOUTERR_INSANE self is corrupt or incorrect. Possible reasons include an unset host, port, or password. SHOUTERR_CONNECTED The connection has already been opened. SHOUTERR_UNSUPPORTED The protocol/format combination is unsupported. For instance, Ogg Vorbis may only be sent via the HTTP protocol. SHOUTERR_NOCONNECT A connection to the server could not be established. SHOUTERR_SOCKET An error occured while talking to the server. SHOUTERR_NOLOGIN The server refused login, probably because authentication failed. SHOUTERR_MALLOC There wasn't enough memory to complete the operation. int shout_close shout_t *self Closes a connection to the server. Return Values SHOUTERR_SUCCESS The connection was successfully closed. SHOUTERR_INSANE self is not a valid shout_t object. SHOUTERR_UNCONNECTED self is not currently connected. int shout_get_connected shout_t *self Returns the connection status of the given shout_t object. Return Values SHOUTERR_INSANE self is not a valid shout_t object. SHOUTERR_UNCONNECTED self is not currently connected. SHOUTERR_CONNECTED self is currently connected. const char *shout_get_error shout_t *self Returns a statically allocated string describing the last shout error that occured in this connection. Only valid until the next call affecting this connection. int shout_get_errno shout_t *self Returns the shout error code of the last error that occured in this connection.

Sending data int shout_send shout_t *self const unsigned char *data> size_t len Sends len bytes of audio data from the buffer pointed to by data to the server. The connection must already have been established by a successful call to shout_open. Return Values SHOUTERR_SUCCESS The audio data was sent successfully. SHOUTERR_INSANE self is not a valid shout_t object. SHOUTERR_UNCONNECTED self is not currently connected. SHOUTERR_MALLOC There wasn't enough memory to complete the operation. SHOUTERR_SOCKET An error occured while talking to the server. ssize_t shout_send_raw shout_t *self const unsigned char *data> size_t len Sends len bytes of audio data from the buffer pointed to by data to the server. The data is not parsed for timing or validity, but sent raw over the connection. The connection must already have been established by a successful call to shout_open. This function should not be used unless you know exactly what you are doing. Its use is deprecated and it may be removed in a future version of the library. Return Values >= 0 The number of bytes written. SHOUTERR_INSANE self is not a valid shout_t object. SHOUTERR_UNCONNECTED self is not currently connected. SHOUTERR_SOCKET An error occured while talking to the server. void shout_sync shout_t *self Causes the caller to sleep for the amount of time necessary to play back audio sent since the last call to shout_sync. Should be called before every call to shout_send to ensure that audio data is sent to the server at the correct speed. Alternatively, the caller may use shout_delay to determine the number of milliseconds to wait and delay itself. int shout_delay shout_t *self Returns the number of milliseconds the caller should wait before calling shout_send again. This function is provided as an alternative to shout_sync for applications that may wish to do other processing in the meantime. ssize_t shout_queuelen shout_t *self Returns the number of bytes currently on the write queue. This is only useful in non-blocking mode.

Connection parameters The following functions are used to get or set attributes of the shout_t object before calling shout_open. They all work the same way: they operate on one attribute of a shout_t*. The shout_get_* functions return the value of their associated parameter, or 0 on error (that's NULL for those functions that return strings). The shout_set_* functions will return either SHOUTERR_SUCCESS on success, or one of: SHOUTERR_INSANE - shout_t is invalid. SHOUTERR_MALLOC - libshout could not allocate enough memory to assign the parameter. SHOUTERR_CONNECTED - you are attempting to change a connection attribute while the connection is open. Since these parameters are only used when first opening the connection, this operation would be useless. int shout_set_nonblocking shout_t *self unsigned int nonblocking Sets non-blocking mode. The default is 0. unsigned int shout_get_nonblocking shout_t *self Returns non-blocking mode or 0 in case of error. int shout_set_host shout_t *self const char *host Sets the server hostname or IP address. The default is localhost. const char *shout_get_host shout_t *self Returns the server hostname or IP address. int shout_set_port shout_t *self unsigned short port Sets the server port. The default is 8000. unsigned short shout_get_port shout_t *self Returns the server port. int shout_set_user shout_t *self const char *user Sets the user to authenticate as, for protocols that can use this parameter. The default is source. const char *shout_get_user shout_t *self Returns the user name. int shout_set_password shout_t *self const char *pass Sets the password to authenticate to the server with. This parameter must be set. There is no default. const char *shout_get_password shout_t *self Returns the password. int shout_set_protocol shout_t *self int protocol Set the protocol with which to connect to the server. Supported protocols are listed in Protocol Constants. The default is SHOUT_PROTOCOL_HTTP (compatible with Icecast 2). int shout_get_protocol shout_t *self Returns the protocol used to connect to the server. int shout_set_format shout_t *self int format Sets the audio format of this stream. The currently supported formats are listed in Format Constants. The default is SHOUT_FORMAT_OGG. int shout_get_format shout_t *self Returns the audio format used by this stream. int shout_set_mount shout_t *self const char *mount Sets the mount point for this stream, for protocols that support this option (SHOUT_PROTOCOL_ICY doesn't). const char *shout_get_mount shout_t *self Returns the stream mount point. int shout_set_dumpfile shout_t *self const char *dumpfile If the server supports it, you can request that your stream be archived on the server under the name dumpfile. This can quickly eat a lot of disk space, so think twice before setting it. const char *shout_get_dumpfile shout_t *self Returns the dump file, if specified. int shout_set_agent shout_t *self const char *agent Sets the user agent header. This is libshout/VERSION by default. If you don't know what this function is for, don't use it. const char *shout_get_agent shout_t *self Returns the user agent. int shout_set_tls shout_t *self int mode This function sets the TLS (Transport Layer Security) mode to use. mode is a TLS mode. This is SHOUT_TLS_AUTO by default. To force TLS on you should use SHOUT_TLS_AUTO_NO_PLAIN and SHOUT_TLS_DISABLED to force TLS off. While SHOUT_TLS_AUTO may connect via TLS this is not a secure mode as everybody can do a man in the middle kind of attack and downgrade the connection to plain. int shout_get_tls shout_t *self Returns the currently used TLS mode. int shout_set_ca_directory shout_t *self const char *directory This sets the CA directory used by libshout to verify server certificates. Defaults to system defaults. const char *shout_get_ca_directory shout_t *self Returns the currently used CA directory. int shout_set_ca_file shout_t *self const char *file Sets a file with CA certificates used to verify server certificates. Defaults to system defaults. The file must be in PEM format. You can use this for self signed server certificates. In this case you point this to the server certificate in PEM format. Keep in mind that this will allow self-signed certificates but other checks such as hostname still needs to verify correctly. const char *shout_get_ca_file shout_t *self Returns the currently used CA file. int shout_set_allowed_ciphers shout_t *self const char *ciphers This sets the list of currently allowed ciphers in OpenSSL format. Defaults to a list of ciphers considerd secure as of day of release. Setting this to a insecure list may render encryption and authentication useless. Any application using this call must expose this list to the user. If the user can not alter this list your application will harm security badly by preventing the user to get to a save value by setting it manually or upgrading libshout. Do not use this call if you don't know what you are doing. const char *shout_get_allowed_ciphers shout_t *self Returns the currently used list of allowed ciphers. int shout_set_client_certificate shout_t *self const char *certificate This sets the client certificate to be used. Defaults to none. The file must be in PEM format and must contain both the certificate as well as the private key for that certificate. const char *shout_get_client_certificate shout_t *self Returns the currently used client certificate.

Directory parameters The following parameters are optional. They are used to control whether and how your stream will be listed in the server's stream directory (if available). int shout_set_public shout_t *self int makepublic Setting this to 1 asks the server to list the stream in any directories it knows about. To suppress listing, set this to 0. The default is 0. int shout_get_public shout_t *self Returns whether or not this stream is public. int shout_set_meta shout_t *self const char *name const char *value This function sets the meta data for the stream. const char *shout_get_meta shout_t *self const char *name This function gets the meta data for the stream. int shout_set_audio_info shout_t *self const char *name const char *value Sets a stream audio parameter (eg bitrate, samplerate, channels or quality). The currently defined parameters are listed in the Audio Info Constants section, but you are free to add additional fields if your directory server understands them. const char *shout_get_audio_info shout_t *self const char *name Returns the value of the audio info field name, if defined.

Metadata These functions currently only make sense for MP3 streams. Vorbis streams are expected to embed metadata as vorbis comments in the audio stream. shout_metadata_t *shout_metadata_new Allocates a new metadata structure, or returns NULL if no memory is available. The returned structure should be freed with shout_metadata_free when you are done with it. void shout_metadata_free shout_metadata_t *self Frees any resources associated with self. int shout_metadata_add shout_metadata_t *self const char *name const char *value Add metadata value value to self, under the key name. You'll probably want to set name to "song", though "url" may also be useful. Return Values SHOUTERR_SUCCESS The metadata was copied into self. SHOUTERR_INSANE self is not a valid shout_metadata_t object. SHOUTERR_MALLOC Couldn't allocate enough memory to copy the metadata. int shout_set_metadata shout_t *self shout_metadata_t *metadata Sets metadata on the connection self to metadata. Only MP3 streams support this type of metadata update. You may use this function on defined but closed connections (this is useful if you simply want to set the metadata for a stream provided by another process). Return Values SHOUTERR_SUCCESS Metadata was updated successfully. SHOUTERR_INSANE self and/or metadata is invalid. SHOUTERR_MALLOC Couldn't allocate enough memory to complete the operation. SHOUTERR_NOCONNECT The server refused the connection attempt. SHOUTERR_NOLOGIN The server did not accept your authorization credentials. SHOUTERR_SOCKET An error occured talking to the server. SHOUTERR_METADATA The server returned any other error (eg bad mount point).

Obsolate metadata Interface All those functions have been replaced by shout_set_meta and shout_get_meta. They may be removed by newer versions of this library. int shout_set_name shout_t *self const char *name Sets the name of the stream. const char *shout_get_name shout_t *self Returns the stream name. int shout_set_url shout_t *self const char *url Sets the URL of a site about this stream. const char *shout_get_url shout_t *self Returns the stream URL. int shout_set_genre shout_t *self const char *genre Sets the genre (or genres) of the stream. This is usually a keyword list, eg "pop rock rap". const char *shout_get_genre shout_t *self Returns the stream genre. int shout_set_description shout_t *self const char *description Sets the description of this stream. const char *shout_get_description shout_t *self Returns the stream description.

Constants Error Codes SHOUTERR_SUCCESS Indicates success. SHOUTERR_INSANE Indicates bad parameters, either nonsense or not applicable due to the current state of the connection. SHOUTERR_MALLOC Indicates the function could not allocate the memory it required. SHOUTERR_NOCONNECT Indicates a connection with the server could not be established. SHOUTERR_NOLOGIN Indicates the server refused to accept a login attempt. This could be caused by a bad user name or password. SHOUTERR_SOCKET Indicates an error sending or receiving data. SHOUTERR_METADATA Indicates an error updating metadata on the server. SHOUTERR_CONNECTED Indicates that, while connected, you attempted to call a function which only makes sense before connection (eg you attempted to set the user name or stream name). SHOUTERR_UNCONNECTED Indicates that you attempted to use a function that requires an open connection (for example, shout_send) while you were not connected. SHOUTERR_UNSUPPORTED Indicates that you attempted to use a function which is unsupported in the state of your connection. For example, attempting to set metadata while using the Ogg Vorbis format is unsupported. SHOUTERR_BUSY Indicates that the socket is busy. The funtion returning this should be called again later. This is likely to happen in non-blocking mode but may also happen in blocking mode. SHOUTERR_NOTLS TLS (Transport Layer Security) was requested via shout_set_tls but is not supported by the server. SHOUTERR_TLSBADCERT A TLS (Transport Layer Security) connection has been established but the server returned a certificate which failed the check. The certificate may be invalid or is not signed by a trusted CA. See shout_set_tls. SHOUTERR_RETRY The caller should retry this call later. Formats SHOUT_FORMAT_OGG The Ogg Format. Vorbis or any codec may be used. This is the default format. SHOUT_FORMAT_WEBM The WebM format. SHOUT_FORMAT_WEBMAUDIO The WebM format, audio only streams. SHOUT_FORMAT_VORBIS This is deprecated. It is an alias to SHOUT_FORMAT_OGG. Please migrate your code. SHOUT_FORMAT_MP3 The MP3 format. Protocols SHOUT_PROTOCOL_HTTP The HTTP protocol. This is the native protocol of the Icecast 2 server, and is the default. SHOUT_PROTOCOL_ROARAUDIO The RoarAudio protocol. This is the native protocol for RoarAudio servers. SHOUT_PROTOCOL_XAUDIOCAST The Audiocast format. This is the native protocol of Icecast 1. SHOUT_PROTOCOL_ICY The ShoutCast format. This is the native protocol of ShoutCast. Audio Parameters SHOUT_AI_BITRATE Used to specify the nominal bitrate of the stream. SHOUT_AI_SAMPLERATE Used to specify the samplerate of the stream. SHOUT_AI_CHANNELS Used to specify the number of channels (usually one or two). SHOUT_AI_QUALITY Used to specify the Ogg Vorbis encoding quality of the stream. Stream Metadata Parameters SHOUT_META_NAME Sets stream name. SHOUT_META_URL Sets stream URL. SHOUT_META_GENRE Sets stream genre. SHOUT_META_DESCRIPTION Sets stream description. SHOUT_META_IRC Sets IRC contact information for stream. SHOUT_META_AIM Sets AIM contact information for stream. SHOUT_META_ICQ Sets ICQ contact information for stream. TLS modes SHOUT_TLS_DISABLED TLS (Transport Layer Security) is disabled. Passwords and data will be sent unencrypted. SHOUT_TLS_AUTO TLS (Transport Layer Security) support by the server will be autodetected. This is the default. In this mode TLS is used if supported by the server. Please note that this is not a secure mode as it will not prevent any downgrade attacks. SHOUT_TLS_AUTO_NO_PLAIN is a more secure version of this mode. SHOUT_TLS_AUTO_NO_PLAIN TLS (Transport Layer Security) is used. Autodetection is used to find out about which modes are supported by the server. This mode should be used for secure connections. SHOUT_TLS_RFC2818 TLS (Transport Layer Security) is used as defined by RFC2818. In this mode libshout expects a TLS socket on the server side and will begin with a TLS handshake prior to any other communication. SHOUT_TLS_RFC2817 TLS (Transport Layer Security) is used as defined by RFC2817. In this mode libshout will use HTTP/1.1's Upgrade:-process to switch to TLS. This allows to use TLS on a non-TLS socket of the server.