Design of XMMS2 pre DrEvil
Please note that XMMS2 is currently undergoing an overhaul of its internal structure - see Transforms for more information.
The server is the part of XMMS2 that outputs music and keeps track of the playlist, effects, visualisation and the music library. The server is divided into objects that intercommunicate using signals.
Block diagram showing the XMMS2 daemon's internals
http://people.xmms2.org/~tru/xmms2-core.png
A fancier block diagram showing the daemon's internals while playing an ogg file
Each object holds a very special functionality and these objects are exposed to the client for communication. The main objects are:
Controls the server. Creates the playlist and the output object.
The Output object is the one that "drives" XMMS2. It takes a playlist entry from the playlist and starts the transport and the decoder for that entry. The output then reads from the decoders and outputs the decoded data to the soundcard.
The playlist object is responsible for knowing which entries should be played and in which order. It also holds the media information for the entries within itself.
The playlist is basically 2 classes and 3 objects. A manager that interract with the rest of the object, and manage the 2 lists. One is the real playlist and the other one is the effective playlist. They are managing what is related to the GLists. The real is the playlist the user sees. The effective retain the order the tracks are played and the information lost on deletion.
When an entry is selected for playback, the output will create a transport object for the URL. The URL will be fed to the appropiate plugin, which will determine the mimetype for the entry.
Once the transport has told us which mimetype it holds, it will feed that to a decoder object. The decoder will read encoded data from the transport and decode it.
The plugins are, in a way, subclasses of the Objects. They inherit the objects' methods and are always paired with their respective parent objects.
Client-server communication is done in two ways. The first way is by doing a methodcall from the client to the server (i.e playlist_next or playlist_list). The server will respond to that command.
The other way is for continuous updates - like for how long we have played a song or the information for a song. This is called an onchange signal.
Each client holds a connection to the server - xmmsc_connection_t. Commands are sent and onchange signals are received on this connection struct. The Client library has the ability to do both synchronous and asynchronous operations.
Once a connection has been established, you can start calling methods in the server. This can be done as follows:
xmmsc_result_t *res;
res = xmmsc_playlist_next (connection);
xmmsc_result_wait (res);
xmmsc_result_unref (res);
or with arguments to some of the methods.
res = xmmsc_playlist_add (connection, "file://home/tru/test.ogg");
Every time you call a method on the server, an xmmsc_result_t will be returned - the results from this can be extracted and used (the data returned also says whether the methodcall was successful or not). You can use the resultset either sync or async.
When you have done your methodcall, you should set up a callback function for the resultset. This function will be called when the server has filled in the resultset with the result. Example:
res = xmmsc_playlist_add (connection, myfile);
xmmsc_result_notifier_set (res, callbackfunc, userdata);
xmmsc_result_unref (res);
The callback function could look something like this:
void myfunc (xmmsc_result_t *res, void *userdatata) {
if (xmmsc_result_iserror (res)) {
printf ("Error!\n");
} else {
printf ("Item added to playlist!\n");
}
}
The operation in the above example in sync mode will look something like this:
res = xmmsc_playlist_add (connection, myfile);
xmmsc_result_wait (res);
if (xmmsc_result_iserror (res)) {
print ("error!\n");
} else {
print ("item was added to playlist!\n");
}
xmmsc_result_unref (res);
The `xmmsc_result_wait` will block until the answer is ready.
As mentioned above, some methodcalls return data in resultsets. You can (after the resultset is filled) extract information from the resultset with different calls. You must know what data type is returned in the resultset to do so (see the doxygen manual for information about the different methodcalls).
The functions for value extractions are described in the ResultValueRetrieval section of the XMMS2 doxygen documentation