Very first sc sketch

/* Service client sketch using libxmmsclient-sc.
 * Queries the server for all available clients and prints their names.
 *
 * Illustrates some of the concepts discussed in the comments of my proposal
 * as well as a few other ideas of my own.
 */

#include <stdio.h>
#include <assert.h>
#include <string.h>

#include <xmmsclient/xmmsclient.h>

/* Header for Service Clients
 * Since libxmmsclient-sc and libxmmsclient would be so closely
 * related, it might make more sense to implement service client
 * functionality directly in the latter.
 */
#include <xmmsclient/xmmsclient-sc.h>

/* Metadata for this client */
static const char *name = "scsketch";
static int id;

static void
print_clients (xmmsc_connection_t *conn)
{
    int client_id;
    char *client_name;
    xmmsc_result_t *clients_res, *name_res;
    xmmsv_t *connected_clients, *client_list_entry;
    xmmsv_list_iter_t *it;
    xmmsv_t *client_name_v;

    /* This lists all clients that also registered for messages using
     * xmmsc_sc_register.
     * This information can be kept by the server, so this doesn't actually
     * involve conversation between clients.
     */
    clients_res = xmmsc_sc_list_clients (conn);
    xmmsc_result_wait (clients_res);

    /* The return value could be a list of ids. */
    connected_clients = xmmsc_result_get_value (clients_res);

    /* So we can loop through the list and query for client names. */
    xmmsv_get_list_iter (connected_clients, &it);
    while (xmmsv_list_iter_valid (it)) {
        xmmsv_list_iter_entry (it, &client_list_entry);
        xmmsv_get_int (client_list_entry, &client_id);

        /* This illustrates an introspection call for libxmmsclient-sc.
         * The call to xmmsc_sc_get_name results in a message being sent
         * to the queried client (identified by client_id) via
         * xmmsc_broadcast_client_to_client_message.
         * This broadcast reaches the callback set up by libxmmsclient-sc
         * on the other client, which answers with its name.
         * All other clients get the message as well, since this is a
         * broadcast. However, their libxmmsclient-sc callback will simply
         * fail to match their id with the destiny id in the message and
         * ignore the broadcast.
         */
        name_res = xmmsc_sc_get_name (connection, client_id);
        xmmsc_result_wait (name_res);

        /* Each message is identified by a random message id generated by
         * the sender and passed along by the server to the receiver.
         * The sender id and the random message id, thus, uniquely
         * identify a message in the recipient side.
         * The answer is expected to contain the same message id.
         */

        client_name_v = xmmsc_result_get_value (name_res);
        xmmsv_get_string (client_name_v, &client_name);

        printf ("%s", client_name);

        /* The client itself is listed too.
         * Since there may be other clients with the same name, an id
         * match implies name match, but not the other way around.
         */
        if (client_id == id) {
            assert (!strcmp (name, client_name));
            printf (" (hey, that's me!)");
        }

        printf ("\n");

        xmmsc_result_unref (name_res);
        xmmsv_list_iter_next (it);
    }

    xmmsc_result_unref (clients_res);
    return;
}

int
main (int argc, char **argv)
{
    xmmsc_connection_t *connection;
    xmmsc_result_t *res;
    xmmsv_t *my_id;

    /* Connect as usual.
     * Error checking omitted for this example
     */
    connection = xmmsc_init (name);
    xmmsc_connect (connection, getenv ("XMMS_PATH"));

    /* Register for communication with other clients.
     * Under the hood, libxmmsclient-sc sets up its callback for
     * xmmsc_broadcast_client_to_client_message, which is responsible both
     * for answering to introspection calls (such as get_version) and for
     * forwarding method calls to the corresponding functions provided by
     * the client.
     */
    res = xmmsc_sc_register (connection);
    xmmsc_result_wait (res);

    /* xmmsc_sc_register could either return NONE or the id assigned to
     * this client by the server.
     */
    my_id = xmmsc_result_get_value (res);

    /* As for the other metadata (such as version or category), they could
     * be registered separately and kept by libxmmsclient-sc, using
     * functions like xmmsc_sc_set_version. Using this approach,
     * introspection calls could be answered directly by libxmmsclient-sc.
     * An alternative would be for the client to register accessor methods,
     * so that libxmmsclient-sc can dispatch introspection calls to them.
     * Either way, it should probably be possible for a client to not
     * register any metadata other than its name, since it doesn't make
     * sense for a client that doesn't offer services (such as this one)
     * to register them.
     */
    xmmsv_get_int (my_id, &id);
    xmmsc_result_unref (res);

    /* Print the names of all connected clients. */
    print_names (connection);

    xmmsc_unref (connection);

    return EXIT_SUCCESS;
}