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. 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.

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_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 int port Sets the server port. The default is 8000. int 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_pass 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_pass 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_VORBIS. 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.

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_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. 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).