[Xen-API] Xen Management API C Bindings

[Ewan Mellor <ewan@xxxxxxxxxxxxx>]

Hi all,

Attached is my idea for C bindings for the Xen Management API.  These aren't
in any way finished, but I thought that I would rush them out to get them out
in front of you so that we could talk about them on the call in less than 2
hours' time.

This binding is the library that we would offer for people to use to talk to
Xend from their C programs, and in particular would sit at the bottom end of
one of libvirt's backends.

What I've done is taken libxml2 (written by one Daniel Veillard, Esq., I
notice ;-) and xmlrpc-c, and then written a very thin binding on top of that
for the Xen calls themselves.  All that behind-the-scenes stuff is of course
something that we can change in the future.


To use this API, you would do something like this (see test_bindings.c):

#include "xen_vm.h"


static char *call_func(const char *data, size_t len, void *handle)
{
  /* Query the server, return the result */
}


int main(int argc, char **argv)
{
    xen_session *session =
        xen_session_login_with_password(call_func, NULL, "ewan", "letmein");

    xen_vm vm = xen_vm_get_by_uuid(session, "0000");
    char *uuid = xen_vm_get_uuid(session, vm);

    if (!session->ok)
    {
        print_error(session);
        xen_session_logout(session);
        return 1;
    }

    printf("%s.\n", uuid);

    xen_session_logout(session);
    return 0;
}


The API that users of the binding would see looks like this (xen_vm.h and
xen_common.h):

/**
 * The caller will free the result.
 *
 * len does not include a terminating \0.
 */
typedef char *(*xen_call_func)(const char *, size_t len, void *);


typedef struct
{
    xen_call_func call_func;
    void *handle;
    const char *session_id;
    bool ok;
    char **error_description;
    int error_description_count;
} xen_session;


extern xen_session *
xen_session_login_with_password(xen_call_func call_func, void *handle,
                                const char *uname, const char *pwd);


extern void
xen_session_logout(xen_session *session);


/**
 * The VM class.
 *
 * A virtual machine (or 'guest')
 */


typedef char *xen_vm;


typedef struct
{
  int size;
  xen_vm *contents;
} xen_vm_set;


extern xen_vm_set
xen_vm_get_all(xen_session *s);


extern xen_vm
xen_vm_get_by_uuid(xen_session *s, char *uuid);


/**
 * VM constructor.
 */
extern xen_vm
xen_vm_create(xen_session *s, char * name_label, char * name_description,
              bool is_a_template, uint64_t memory_static_max);


/**
 * VM destructor.
 */
extern void
xen_vm_destroy(xen_session *s, xen_vm vm);


/**
 * Get the VM.uuid field: unique identifier/object reference.
 */
extern char *
xen_vm_get_uuid(xen_session *s, xen_vm vm);


There are a number of features here that are interesting and open to
discussion -- using a session object to hold status and error information,
separating the transport layer from the message construction, use of C99,
handling of sets through explicit individual typedefs, choice of XML and
XML-RPC libraries, etc.  I'd like to discuss all these things on the call
today.

The intention is that this code would go into the Xen tree as the "official" C
binding.  This would not force C programs to use the binding -- the XML-RPC
layer will still be the One True Standard -- the intention is just to have
something in the tree and stable that people can rely upon.

Let's discuss this in the call today, and here on the list, make sure that
we're happy with the style and the intention, and then I'll start the (oh so
tedious ;-) task of mapping each of the API functions through to the C code.
We'll hopefully be in a position to test these APIs (both the C one and the
XML-RPC one) in time to discuss our experiences at the Xen mini-summit.

Cheers,

Ewan.

Attachment: xen-c-bindings.tar.gz
Description: Binary data

_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-api