It means that all C clients are broken now, and possibly clients in other languages too. Yes, yours too. It needs fixing, and I’m going to explain how.

But, you ask, what is rv-split in the first place?

The result/value-split, AKA “rv-split” or sometimes just “rv”, is a change in the XMMS2 clientlib. Up until now, values returned by the server were kept inside the xmmsc_result_t structure that you got back from the call. The data was to be fetched directly from the result.

In sync mode, it went something like this:

[code lang="c"]
xmmsc_result_t *result;
const char *name;

result = xmmsc_playlist_current_active (conn);
xmmsc_result_wait (result);

if (xmmsc_result_iserror (result)) {
printf ("Server error: %s\n", xmmsc_result_get_error (result));
exit (1);
}

// The name is retrieved from the result
if (xmmsc_result_get_string (result, &name)) {
printf ("Active playlist is %s\n", name);
}

// We free the result, which also frees all the data it referenced,
// i.e. the 'name' string
xmmsc_result_unref (result);
[/code]

The goal of rv-split was to isolate values outside of the result structure (for reasons that will become more obvious when we talk about the async calls). To do that, we introduced a new structure called xmmsv_t (for “xmms value”), that can contain any type of value. Accessor functions are used to extract each type from it, in a similar way to how it was done with result structures.

Let’s show the sync example again:
[code lang="c"]
xmmsc_result_t *result;
xmmsv_t *value;
const char *name, *errbuf;

result = xmmsc_playlist_current_active (conn);
xmmsc_result_wait (result);
value = xmmsc_result_get_value (result);

if (xmmsv_get_error (value, &errbuf)) {
printf ("Server error: %s\n", errbuf);
exit (1);
}

if (xmmsv_get_string (value, &name)) {
printf ("Active playlist is %s\n", name);
}

// We free the result, which also frees the value it contained,
// i.e. the 'value' variable, and the 'name' string
xmmsc_result_unref (result);
[/code]

All we have to do is extract the xmmsv_t from the xmmsc_result_t. No raw data is stored in the result structure anymore.

Note that it also affects the error handling: if the server returns an error, it’s not a special state; it just returns an xmmsv_t of type ERROR. xmmsv_get_error is used to retrieve the error message, or the function will return FALSE if the value was not an error. Just like before, the value is freed automatically, so no need to worry about anything, just free the result structure.

Now, let’s move to the async case. In async, we don’t wait on results, we register one (or more) callback (AKA notifier) that will be called when the answer comes back from the server. Up until now, callbacks received the original result structure in argument (plus a userdata pointer). Like before, the result contained the value returned by the server. It could also be used to restart signals or disconnect broadcasts (more on that later).

In code:
[code lang="c"]
void
callback (xmmsc_result_t *result, void *udata)
{
const char *name;

if (xmmsc_result_iserror (result)) {
printf ("Server error: %s\n", xmmsc_result_get_error (result));
exit (1);
}

// The name is retrieved from the result
if (xmmsc_result_get_string (result, &name)) {
printf ("Active playlist is %s\n", name);
}

// Each notifier holds a reference to the result
xmmsc_result_unref (result);
}

int
main ()
{
// [...]

xmmsc_result *result;

result = xmmsc_playlist_current_active (conn);
xmmsc_result_notifier_set (result, callback, NULL);
xmmsc_result_unref (result);
}
[/code]

One of the arguments for the rv-split refactoring was that the result structure is meant to handle the command and how we treat it, but we don’t really need it to be passed to the callback. It allows developers to do weird stuff (wait on the result in the callback, restart a non-signal, etc — don’t try this at home).

All we need really is the value that the server returned. That is, the xmmsv_t!

Which gives:
[code lang="c"]
int
callback (xmmsv_t *value, void *udata)
{
const char *name, *errbuf;

if (xmmsv_get_error (value, &errbuf)) {
printf ("Server error: %s\n", errbuf);
exit (1);
}

// The name is retrieved from the value
if (xmmsv_get_string (value, &name)) {
printf ("Active playlist is %s\n", name);
}

// Note that we do not need to unref anything here!
// The value will be freed automagically after this!

// I will explain this in a minute...
return FALSE;
}

int
main ()
{
// [...]

xmmsc_result *result;

result = xmmsc_playlist_current_active (conn);
xmmsc_result_notifier_set (result, callback, NULL);
xmmsc_result_unref (result);
}
[/code]

Easy and safer!

But maybe you noticed a hitch: hey, how do I restart my signals or disconnect my broadcasts from the callback now?

Well, it’s even easier than before. Previously, here is how you restarted signals:
[code lang="c"]
void
signal_callback (xmmsc_result_t *result, void *udata)
{
xmmsc_result_t *newres;

// [...]

newres = xmmsc_result_restart (result);
xmmsc_unref (result);
xmmsc_unref (newres);
}
[/code]

This simply becomes:
[code lang="c"]
int
signal_callback (xmmsv_t *value, void *udata)
{
// [...]

return TRUE;
}
[/code]

That’s right, it’s that simple! The return value of a callback is some sort of “keep alive” flag. If a callback returns TRUE, the signal will be restarted or the broadcast will keep going. If it returns FALSE, the signal will die off (not restarted) or the broadcast will be disconnected.

Note that the return value has no meaning in the case of regular commands, like the earlier example.

Here are a couple of other things you might need to know about the new API:

• By default, the xmmsv_t is freed automatically (since it’s owned by the xmmsc_result_t). If you want to keep it around for some reason, you can ref it using xmmsv_ref, but don’t forget to unref it again when you’re done with xmmsv_unref, else your client will leak!
• Dict and List accessors have been made more generic and sexy, so check the documentation to learn how to access these types!
• PropDicts (returned by xmmsc_medialib_get_info) have been replaced by dict-in-dicts, but you can convert them back to regular Dicts using the xmmsv_propdict_to_dict helper function. Again, use the Doc, Luke!
• Check how your favorite bindings handled the upgrade, the upgrade path might be softer depending on the language.
• The tutorials have been updated (or will be shortly as soon as my patch for #2018 is merged — you can check it in the meantime). It features some code working with propdicts and list iterators, and other things in general.

I think you should now be ready to upgrade your clients to rv-split! It’s been fun hacking on the new code this summer, and getting help from everyone to improve it and get it into -devel!

Feel free to ask questions on IRC or in the comments!

The contest page on the official website isn’t quite as verbose as one would have hoped, though, and the link to the rules points to a missing webpage. Some more intel is however available in a blog post on Michael Robertson’s blog. Yes, Michael MP3.Com/Linspire Robertson, who is also Michael MP3Tunes Robertson, obviously.

The deal: you have until November 5th, 2007, to submit an interface to MP3Tunes in one of the ten predefined categories (Desktop Player, Game Console, WebUI, PDA, etc). The winner in each category will receive a cosy $1000. I haven’t determined whether it’s a public vote, a closed jury, or some other semi-random algorithm involving car-driving girafes.

I haven’t yet checked what the API offers, either, but I sure wonder whether we could hack something together with XMMS2. If it could be hooked into the daemon, and apart from the obvious ever satisfying benefit of being neat and fun, it might allow using any of our interfaces (AKA clients) to play music from MP3Tunes.

From what I see, MP3Tunes isn’t much more than an online storage for music files, that you either upload or retrieve from wherever on the web. (Let’s leave the obvious legal issues to Michael’s lawyers, shall we?) This means that you have a whole medialib on their server, apparently indexed and searchable and, naturally, playable. If I’m not mistaken, the “streaming” seems to be nothing more than retrieving the music file (original or transcoded to mp3) over HTTP, which XMMS2 already supports.

In the current scheme, our medialib assumes to contain all the media and their metadata, so unless this is extended to support distributed media libraries (hello, Summer of Code 2008?), it means we would have to sync the remote MP3Tunes medialib to the local XMMS2 medialib. Sounds a bit tedious and expensive and ugly, so suggestions are welcome with better solutions!

These are the few implementation considerations I can think of off the top of my head, but overall it doesn’t sound so complicated, unless we want the support to be very smart (async, allow upload/download media, etc).

Of course, the whole contest looks like a call for devs to code cool interfaces to a money-making online service (mostly) for free, more than anything else, but let’s just consider the idea for a minute and whether it could justify spending some energy on writing one or several polished clients (which I think most of us agree we need).

And transparently sharing music through a (currently) free, password protected, remote service can’t be such a useless idea, can it?