|
Packit |
eed494 |
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
"http://docbook.org/xml/4.2/docbookx.dtd">
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<book><title>Programming With Libshout 2</title>
|
|
Packit |
eed494 |
<bookinfo>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<author>
|
|
Packit |
eed494 |
<firstname>Brendan</firstname><surname>Cully</surname>
|
|
Packit |
eed494 |
<email>brendan@xiph.org</email>
|
|
Packit |
eed494 |
</author>
|
|
Packit |
eed494 |
<copyright>
|
|
Packit |
eed494 |
<year>2003</year>
|
|
Packit |
eed494 |
<holder>Brendan Cully</holder>
|
|
Packit |
eed494 |
</copyright>
|
|
Packit |
eed494 |
-->
|
|
Packit |
eed494 |
<orgname><ulink url="http://xiph.org/">Xiph.org</ulink></orgname>
|
|
Packit |
eed494 |
<releaseinfo>$Id: libshout.xml 7019 2004-07-06 08:05:47Z brendan $</releaseinfo>
|
|
Packit |
eed494 |
<date> 3 Jul 2003</date>
|
|
Packit |
eed494 |
</bookinfo>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<chapter><title>Overview</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<para>
|
|
Packit |
eed494 |
libshout is a library for streaming audio to icecast or shoutcast-compatible
|
|
Packit |
eed494 |
servers. Currently it supports two audio formats and three protocols.
|
|
Packit |
eed494 |
</para>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<itemizedlist><title>Audio Formats</title>
|
|
Packit |
eed494 |
<listitem>Ogg Vorbis</listitem>
|
|
Packit |
eed494 |
<listitem>MP3</listitem>
|
|
Packit |
eed494 |
</itemizedlist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<itemizedlist><title>Protocols</title>
|
|
Packit |
eed494 |
<listitem>HTTP</listitem>
|
|
Packit |
eed494 |
<listitem>Audiocast</listitem>
|
|
Packit |
eed494 |
<listitem>ShoutCast</listitem>
|
|
Packit |
eed494 |
</itemizedlist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</chapter>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<chapter><title>Reference</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Functions</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Global functions</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_init">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>void <function>shout_init</function></funcdef>
|
|
Packit |
eed494 |
<void/>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Initializes the shout library. Currently this initializes the networking
|
|
Packit |
eed494 |
mutexes when the library is built with thread safety. This function must
|
|
Packit |
eed494 |
always be called before any other libshout function.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_shutdown">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>void <function>shout_shutdown</function></funcdef>
|
|
Packit |
eed494 |
<void/>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Releases any resources which may have been allocated by a call to
|
|
Packit |
eed494 |
<link linkend="shout_init"><function>shout_init</function></link>. An
|
|
Packit |
eed494 |
application should call this function after it has finished using libshout.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_version">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_version</function></funcdef>
|
|
Packit |
eed494 |
<paramdef>int *<parameter>major</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int *<parameter>minor</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int *<parameter>patch</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the version of the libshout library, both as a string via the
|
|
Packit |
eed494 |
return value, and as a set of integers corresponding to the major,
|
|
Packit |
eed494 |
minor and patch levels of the library. The application must allocate
|
|
Packit |
eed494 |
the integer parameters. If any parameter is NULL, libshout will not
|
|
Packit |
eed494 |
attempt to set it.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Managing connections</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_new">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef><type>shout_t</type> *<function>shout_new</function></funcdef>
|
|
Packit |
eed494 |
<void/>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Allocates a new <type>shout_t</type> structure. May return NULL if no memory
|
|
Packit |
eed494 |
is available. The result should be disposed of with
|
|
Packit |
eed494 |
<link linkend="shout_free"><function>shout_free</function></link> when you are
|
|
Packit |
eed494 |
finished with it.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_free">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>void <function>shout_free</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Frees a <type>shout_t</type> allocated by
|
|
Packit |
eed494 |
<link linkend="shout_new"><function>shout_new</function></link>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_open">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_open</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Opens a connection to a server. All connection parameters must have been
|
|
Packit |
eed494 |
set prior to this call.
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>The connection was successfully opened.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is corrupt or incorrect. Possible reasons
|
|
Packit |
eed494 |
include an unset host, port, or password.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_CONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem>The connection has already been opened.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNSUPPORTED</constant></term>
|
|
Packit |
eed494 |
<listitem>The protocol/format combination is unsupported. For instance,
|
|
Packit |
eed494 |
Ogg Vorbis may only be sent via the HTTP protocol.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOCONNECT</constant></term>
|
|
Packit |
eed494 |
<listitem>A connection to the server could not be established.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SOCKET</constant></term>
|
|
Packit |
eed494 |
<listitem>An error occured while talking to the server.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOLOGIN</constant></term>
|
|
Packit |
eed494 |
<listitem>The server refused login, probably because authentication
|
|
Packit |
eed494 |
failed.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_MALLOC</constant></term>
|
|
Packit |
eed494 |
<listitem>There wasn't enough memory to complete the operation.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_close">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_close</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Closes a connection to the server.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>The connection was successfully closed.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not a valid <type>shout_t</type>
|
|
Packit |
eed494 |
object.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNCONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not currently connected.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_error">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_error</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns a statically allocated string describing the last shout error
|
|
Packit |
eed494 |
that occured in this connection. Only valid until the next call affecting
|
|
Packit |
eed494 |
this connection.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_errno">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_get_errno</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the shout error code of the last error that occured in this connection.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Sending data</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_send">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_send</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const unsigned char *<parameter>data></parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef><type>size_t</type> <parameter>len</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sends <varname>len</varname> bytes of audio data from the buffer pointed to by
|
|
Packit |
eed494 |
<varname>data</varname> to the server. The connection must already have been
|
|
Packit |
eed494 |
established by a successful call to
|
|
Packit |
eed494 |
<link linkend="shout_open"><function>shout_open</function></link>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>The audio data was sent successfully.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not a valid <type>shout_t</type>
|
|
Packit |
eed494 |
object.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNCONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not currently connected.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_MALLOC</constant></term>
|
|
Packit |
eed494 |
<listitem>There wasn't enough memory to complete the operation.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SOCKET</constant></term>
|
|
Packit |
eed494 |
<listitem>An error occured while talking to the server.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_send_raw">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef><type>ssize_t</type> <function>shout_send_raw</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const unsigned char *<parameter>data></parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef><type>size_t</type> <parameter>len</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sends <varname>len</varname> bytes of audio data from the buffer pointed to by
|
|
Packit |
eed494 |
<varname>data</varname> to the server. The data is not parsed for timing
|
|
Packit |
eed494 |
or validity, but sent raw over the connection. The connection must already have been
|
|
Packit |
eed494 |
established by a successful call to
|
|
Packit |
eed494 |
<link linkend="shout_open"><function>shout_open</function></link>.
|
|
Packit |
eed494 |
<warning>This function should not be used unless you know exactly what you
|
|
Packit |
eed494 |
are doing. Its use is deprecated and it may be removed in a future version of
|
|
Packit |
eed494 |
the library.</warning>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term>>= 0</term>
|
|
Packit |
eed494 |
<listitem>The number of bytes written.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not a valid <type>shout_t</type>
|
|
Packit |
eed494 |
object.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNCONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not currently connected.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SOCKET</constant></term>
|
|
Packit |
eed494 |
<listitem>An error occured while talking to the server.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_sync">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>void <function>shout_sync</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Causes the caller to sleep for the amount of time necessary to play back
|
|
Packit |
eed494 |
audio sent since the last call to <function>shout_sync</function>. Should
|
|
Packit |
eed494 |
be called before every call to
|
|
Packit |
eed494 |
<link linkend="shout_send"><function>shout_send</function></link> to
|
|
Packit |
eed494 |
ensure that audio data is sent to the server at the correct speed.
|
|
Packit |
eed494 |
Alternatively, the caller may use
|
|
Packit |
eed494 |
<link linkend="shout_delay"><function>shout_delay</function></link> to
|
|
Packit |
eed494 |
determine the number of milliseconds to wait and delay itself.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_delay">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_delay</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the number of milliseconds the caller should wait before calling
|
|
Packit |
eed494 |
<link linkend="shout_send"><function>shout_send</function></link> again.
|
|
Packit |
eed494 |
This function is provided as an alternative to
|
|
Packit |
eed494 |
<link linkend="shout_sync"><function>shout_sync</function></link> for
|
|
Packit |
eed494 |
applications that may wish to do other processing in the meantime.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Connection parameters</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
The following functions are used to get or set attributes of the
|
|
Packit |
eed494 |
<type>shout_t</type> object before calling
|
|
Packit |
eed494 |
<link linkend="shout_open"><function>shout_open</function></link>. They all
|
|
Packit |
eed494 |
work the same way: they operate on one attribute of a
|
|
Packit |
eed494 |
<type>shout_t</type>*. The <function>shout_get_*</function> functions
|
|
Packit |
eed494 |
return the value of their associated parameter, or 0 on error (that's
|
|
Packit |
eed494 |
NULL for those functions that return strings). The
|
|
Packit |
eed494 |
<function>shout_set_*</function> functions will return either
|
|
Packit |
eed494 |
<constant>SHOUTERR_SUCCESS</constant> on success, or one of:
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<itemizedlist>
|
|
Packit |
eed494 |
<listitem><constant>SHOUTERR_INSANE</constant> - <type>shout_t</type>
|
|
Packit |
eed494 |
is invalid.</listitem>
|
|
Packit |
eed494 |
<listitem><constant>SHOUTERR_MALLOC</constant> - libshout could not
|
|
Packit |
eed494 |
allocate enough memory to assign the parameter.</listitem>
|
|
Packit |
eed494 |
<listitem><constant>SHOUTERR_CONNECTED</constant> - you are attempting
|
|
Packit |
eed494 |
to change a connection attribute while the connection is open. Since these
|
|
Packit |
eed494 |
parameters are only used when first opening the connection, this operation
|
|
Packit |
eed494 |
would be useless.</listitem>
|
|
Packit |
eed494 |
</itemizedlist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_host">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_host</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>host</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the server hostname or IP address. The default is <constant>localhost</constant>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_host">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_host</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the server hostname or IP address.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_port">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_port</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int <parameter>port</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the server port. The default is <constant>8000</constant>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_port">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_get_port</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the server port.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_user">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_user</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>user</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the user to authenticate as, for protocols that can use this parameter.
|
|
Packit |
eed494 |
The default is <constant>source</constant>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_user">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_user</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the user name.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_pass">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_pass</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>pass</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the password to authenticate to the server with. This parameter
|
|
Packit |
eed494 |
<emphasis>must</emphasis> be set. There is no default.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_pass">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_pass</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the password.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_protocol">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_protocol</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int <parameter>protocol</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Set the protocol with which to connect to the server. Supported protocols
|
|
Packit |
eed494 |
are listed in <link linkend="protocol_constants">Protocol Constants</link>.
|
|
Packit |
eed494 |
The default is <constant>SHOUT_PROTOCOL_HTTP</constant> (compatible with
|
|
Packit |
eed494 |
Icecast 2).
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_protocol">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_get_protocol</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the protocol used to connect to the server.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_format">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_format</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int <parameter>format</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the audio format of this stream. The currently supported formats
|
|
Packit |
eed494 |
are listed in <link linkend="format_constants">Format Constants</link>.
|
|
Packit |
eed494 |
The default is <constant>SHOUT_FORMAT_VORBIS</constant>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_format">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_get_format</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the audio format used by this stream.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_mount">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_mount</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>mount</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the mount point for this stream, for protocols that support this option
|
|
Packit |
eed494 |
(<constant>SHOUT_PROTOCOL_ICY</constant> doesn't).
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_mount">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_mount</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the stream mount point.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_dumpfile">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_dumpfile</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>dumpfile</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
If the server supports it, you can request that your stream be archived
|
|
Packit |
eed494 |
on the server under the name <varname>dumpfile</varname>. This can quickly
|
|
Packit |
eed494 |
eat a lot of disk space, so think twice before setting it.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_dumpfile">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_dumpfile</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the dump file, if specified.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_agent">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_agent</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>agent</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the user agent header. This is <constant>libshout/VERSION</constant>
|
|
Packit |
eed494 |
by default. If you don't know what this function is for, don't use it.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_agent">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_agent</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the user agent.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Directory parameters</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
The following parameters are optional. They are used to control whether
|
|
Packit |
eed494 |
and how your stream will be listed in the server's stream directory (if available).
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_public">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_public</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>int <parameter>makepublic</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Setting this to <constant>1</constant> asks the server to list the stream in
|
|
Packit |
eed494 |
any directories it knows about. To suppress listing, set this to
|
|
Packit |
eed494 |
<constant>0</constant>. The default is <constant>0</constant>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_public">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_get_public</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns whether or not this stream is public.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_name">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_name</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>name</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the name of the stream.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_name">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_name</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the stream name.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_url">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_url</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>url</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the URL of a site about this stream.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_url">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_url</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the stream URL.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_genre">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_genre</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>genre</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the genre (or genres) of the stream. This is usually a keyword list,
|
|
Packit |
eed494 |
eg "pop rock rap".
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_genre">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_genre</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the stream genre.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_description">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_description</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>description</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets the description of this stream.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_description">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_description</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the stream description.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_audio_info">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_audio_info</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>name</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>value</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets a stream audio parameter (eg bitrate, samplerate, channels or quality).
|
|
Packit |
eed494 |
The currently defined parameters are listed in the
|
|
Packit |
eed494 |
<link linkend="audio_info_constants">Audio Info Constants</link> section, but
|
|
Packit |
eed494 |
you are free to add additional fields if your directory server understands them.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_get_audio_info">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>const char *<function>shout_get_audio_info</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>name</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Returns the value of the audio info field <varname>name</varname>, if defined.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Metadata</title>
|
|
Packit |
eed494 |
These functions currently only make sense for MP3 streams. Vorbis streams are expected
|
|
Packit |
eed494 |
to embed metadata as vorbis comments in the audio stream.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_metadata_new">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef><type>shout_metadata_t</type> *<function>shout_metadata_new</function></funcdef>
|
|
Packit |
eed494 |
<void/>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Allocates a new metadata structure, or returns NULL if no memory is available. The
|
|
Packit |
eed494 |
returned structure should be freed with
|
|
Packit |
eed494 |
<link linkend="shout_metadata_free">shout_metadata_free</link> when you are done with
|
|
Packit |
eed494 |
it.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_metadata_free">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>void <function>shout_metadata_free</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_metadata_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Frees any resources associated with <varname>self</varname>.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_metadata_add">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_metadata_add</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_metadata_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>name</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef>const char *<parameter>value</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Add metadata value <varname>value</varname> to <varname>self</varname>, under the
|
|
Packit |
eed494 |
key <varname>name</varname>. You'll probably want to set <varname>name</varname>
|
|
Packit |
eed494 |
to <constant>"song"</constant>, though <constant>"url"</constant> may also be
|
|
Packit |
eed494 |
useful.
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>The metadata was copied into <varname>self</varname>.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> is not a valid <type>shout_metadata_t</type> object.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_MALLOC</constant></term>
|
|
Packit |
eed494 |
<listitem>Couldn't allocate enough memory to copy the metadata.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<funcsynopsis id="shout_set_metadata">
|
|
Packit |
eed494 |
<funcprototype>
|
|
Packit |
eed494 |
<funcdef>int <function>shout_set_metadata</function></funcdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_t</type> *<parameter>self</parameter></paramdef>
|
|
Packit |
eed494 |
<paramdef><type>shout_metadata_t</type> *<parameter>metadata</parameter></paramdef>
|
|
Packit |
eed494 |
</funcprototype>
|
|
Packit |
eed494 |
</funcsynopsis>
|
|
Packit |
eed494 |
Sets metadata on the connection <varname>self</varname> to <varname>metadata</varname>.
|
|
Packit |
eed494 |
Only MP3 streams support this type of metadata update. You may use this function
|
|
Packit |
eed494 |
on defined but closed connections (this is useful if you simply want to set the
|
|
Packit |
eed494 |
metadata for a stream provided by another process).
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist><title>Return Values</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>Metadata was updated successfully.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem><varname>self</varname> and/or <varname>metadata</varname> is invalid.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_MALLOC</constant></term>
|
|
Packit |
eed494 |
<listitem>Couldn't allocate enough memory to complete the operation.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOCONNECT</constant></term>
|
|
Packit |
eed494 |
<listitem>The server refused the connection attempt.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOLOGIN</constant></term>
|
|
Packit |
eed494 |
<listitem>The server did not accept your authorization credentials.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SOCKET</constant></term>
|
|
Packit |
eed494 |
<listitem>An error occured talking to the server.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_METADATA</constant></term>
|
|
Packit |
eed494 |
<listitem>The server returned any other error (eg bad mount point).</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Data Types</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist id="data_types">
|
|
Packit |
eed494 |
<varlistentry id="shout_t">
|
|
Packit |
eed494 |
<term><type>shout_t</type></term>
|
|
Packit |
eed494 |
<listitem>Opaque data type that refers to a single server connection.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry id="shout_metadata_t">
|
|
Packit |
eed494 |
<term><type>shout_metadata_t</type></term>
|
|
Packit |
eed494 |
<listitem>Opaque data type that refers to a set of metadata attributes. Currently
|
|
Packit |
eed494 |
the only defined attribute is <constant>song</constant>.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<section><title>Constants</title>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist id="error_constants"><title>Error Codes</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SUCCESS</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates success.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_INSANE</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates bad parameters, either nonsense or not applicable due to the current
|
|
Packit |
eed494 |
state of the connection.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_MALLOC</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates the function could not allocate the memory it required.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOCONNECT</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates a connection with the server could not be established.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_NOLOGIN</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates the server refused to accept a login attempt. This could be caused
|
|
Packit |
eed494 |
by a bad user name or password.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_SOCKET</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates an error sending or receiving data.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_METADATA</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates an error updating metadata on the server.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_CONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates that, while connected, you attempted to call a function which only makes
|
|
Packit |
eed494 |
sense before connection (eg you attempted to set the user name or stream name).</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNCONNECTED</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates that you attempted to use a function that requires an open connection
|
|
Packit |
eed494 |
(for example, <function>shout_send</function>) while you were not connected.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUTERR_UNSUPPORTED</constant></term>
|
|
Packit |
eed494 |
<listitem>Indicates that you attempted to use a function which is unsupported in the
|
|
Packit |
eed494 |
state of your connection. For example, attempting to set metadata while using the
|
|
Packit |
eed494 |
Ogg Vorbis format is unsupported.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist id="format_constants"><title>Formats</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_FORMAT_VORBIS</constant></term>
|
|
Packit |
eed494 |
<listitem>The Ogg Vorbis format. This is the default format.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_FORMAT_MP3</constant></term>
|
|
Packit |
eed494 |
<listitem>The MP3 format.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist id="protocol_constants"><title>Protocols</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_PROTOCOL_HTTP</constant></term>
|
|
Packit |
eed494 |
<listitem>The HTTP protocol. This is the native protocol of the
|
|
Packit |
eed494 |
<application>icecast 2</application> server, and is the default.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_PROTOCOL_XAUDIOCAST</constant></term>
|
|
Packit |
eed494 |
<listitem>The Audiocast format. This is the native protocol of
|
|
Packit |
eed494 |
<application>icecast 1</application>.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_PROTOCOL_ICY</constant></term>
|
|
Packit |
eed494 |
<listitem>The ShoutCast format. This is the native protocol of
|
|
Packit |
eed494 |
<application>ShoutCast</application>.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<variablelist id="audio_info_constants"><title>Audio Parameters</title>
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_AI_BITRATE</constant></term>
|
|
Packit |
eed494 |
<listitem>Used to specify the nominal bitrate of the stream.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_AI_SAMPLERATE</constant></term>
|
|
Packit |
eed494 |
<listitem>Used to specify the samplerate of the stream.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_AI_CHANNELS</constant></term>
|
|
Packit |
eed494 |
<listitem>Used to specify the number of channels (usually one or two).</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
<varlistentry>
|
|
Packit |
eed494 |
<term><constant>SHOUT_AI_QUALITY</constant></term>
|
|
Packit |
eed494 |
<listitem>Used to specify the Ogg Vorbis encoding quality of the stream.</listitem>
|
|
Packit |
eed494 |
</varlistentry>
|
|
Packit |
eed494 |
</variablelist>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</section>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</chapter>
|
|
Packit |
eed494 |
|
|
Packit |
eed494 |
</book>
|