Added asynchronous event notification through the Xen-API. Added a new command,

xm event-monitor, a new test program for the C bindings, and new bindings
themselves.

Signed-off-by: Ewan Mellor <ewan@xensource.com>

8 files changed, 658 insertions, 0 deletions

diff --git a/tools/libxen/Makefile b/tools/libxen/Makefile
index 58db515a72..51062d7c5b 100644
--- a/tools/libxen/Makefile
+++ b/tools/libxen/Makefile
@@ -51,6 +51,9 @@ libxenapi.a: $(LIBXENAPI_OBJS)
 test/test_bindings: test/test_bindings.o libxenapi.so
 	$(CC) $(LDFLAGS) -o $@ $< -L . -lxenapi
 
+test/test_event_handling: test/test_event_handling.o libxenapi.so
+	$(CC) $(LDFLAGS) -o $@ $< -L . -lxenapi
+
 test/test_hvm_bindings: test/test_hvm_bindings.o libxenapi.so
 	$(CC) $(LDFLAGS) -o $@ $< -L . -lxenapi
 
diff --git a/tools/libxen/include/xen_event.h b/tools/libxen/include/xen_event.h
new file mode 100644
index 0000000000..1e171b8d26
--- /dev/null
+++ b/tools/libxen/include/xen_event.h
@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+#ifndef XEN_EVENT_H
+#define XEN_EVENT_H
+
+#include "xen_common.h"
+#include "xen_event_decl.h"
+#include "xen_event_operation.h"
+#include "xen_string_set.h"
+
+
+/*
+ * The event class.
+ * 
+ * Asynchronous event registration and handling.
+ */
+
+
+
+typedef struct xen_event_record
+{
+    int64_t id;
+    time_t timestamp;
+    char *class;
+    enum xen_event_operation operation;
+    char *ref;
+    char *obj_uuid;
+} xen_event_record;
+
+/**
+ * Allocate a xen_event_record.
+ */
+extern xen_event_record *
+xen_event_record_alloc(void);
+
+/**
+ * Free the given xen_event_record, and all referenced values.  The
+ * given record must have been allocated by this library.
+ */
+extern void
+xen_event_record_free(xen_event_record *record);
+
+
+typedef struct xen_event_record_set
+{
+    size_t size;
+    xen_event_record *contents[];
+} xen_event_record_set;
+
+/**
+ * Allocate a xen_event_record_set of the given size.
+ */
+extern xen_event_record_set *
+xen_event_record_set_alloc(size_t size);
+
+/**
+ * Free the given xen_event_record_set, and all referenced values.  The
+ * given set must have been allocated by this library.
+ */
+extern void
+xen_event_record_set_free(xen_event_record_set *set);
+
+
+/**
+ * Registers this session with the event system.  Specifying the empty
+ * list will register for all classes.
+ */
+extern bool
+xen_event_register(xen_session *session, struct xen_string_set *classes);
+
+
+/**
+ * Unregisters this session with the event system.
+ */
+extern bool
+xen_event_unregister(xen_session *session, struct xen_string_set *classes);
+
+
+/**
+ * Blocking call which returns a (possibly empty) batch of events.
+ */
+extern bool
+xen_event_next(xen_session *session, struct xen_event_record_set **result);
+
+
+#endif
diff --git a/tools/libxen/include/xen_event_decl.h b/tools/libxen/include/xen_event_decl.h
new file mode 100644
index 0000000000..856991fd09
--- /dev/null
+++ b/tools/libxen/include/xen_event_decl.h
@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+#ifndef XEN_EVENT_DECL_H
+#define XEN_EVENT_DECL_H
+
+struct xen_event_record;
+struct xen_event_record_set;
+
+#endif
diff --git a/tools/libxen/include/xen_event_operation.h b/tools/libxen/include/xen_event_operation.h
new file mode 100644
index 0000000000..05319ef58a
--- /dev/null
+++ b/tools/libxen/include/xen_event_operation.h
@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+#ifndef XEN_EVENT_OPERATION_H
+#define XEN_EVENT_OPERATION_H
+
+
+#include "xen_common.h"
+
+
+enum xen_event_operation
+{
+    /**
+     * An object has been created
+     */
+    XEN_EVENT_OPERATION_ADD,
+
+    /**
+     * An object has been deleted
+     */
+    XEN_EVENT_OPERATION_DEL,
+
+    /**
+     * An object has been modified
+     */
+    XEN_EVENT_OPERATION_MOD
+};
+
+
+typedef struct xen_event_operation_set
+{
+    size_t size;
+    enum xen_event_operation contents[];
+} xen_event_operation_set;
+
+/**
+ * Allocate a xen_event_operation_set of the given size.
+ */
+extern xen_event_operation_set *
+xen_event_operation_set_alloc(size_t size);
+
+/**
+ * Free the given xen_event_operation_set.  The given set must have
+ * been allocated by this library.
+ */
+extern void
+xen_event_operation_set_free(xen_event_operation_set *set);
+
+
+/**
+ * Return the name corresponding to the given code.  This string must
+ * not be modified or freed.
+ */
+extern const char *
+xen_event_operation_to_string(enum xen_event_operation val);
+
+
+/**
+ * Return the correct code for the given string, or set the session
+ * object to failure and return an undefined value if the given string does
+ * not match a known code.
+ */
+extern enum xen_event_operation
+xen_event_operation_from_string(xen_session *session, const char *str);
+
+
+#endif
diff --git a/tools/libxen/include/xen_event_operation_internal.h b/tools/libxen/include/xen_event_operation_internal.h
new file mode 100644
index 0000000000..3c4f70c7b8
--- /dev/null
+++ b/tools/libxen/include/xen_event_operation_internal.h
@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+
+/*
+ * Declarations of the abstract types used during demarshalling of enum
+ * xen_event_operation.  Internal to this library -- do not use from outside.
+ */
+
+
+#ifndef XEN_EVENT_OPERATION_INTERNAL_H
+#define XEN_EVENT_OPERATION_INTERNAL_H
+
+
+#include "xen_internal.h"
+
+
+extern const abstract_type xen_event_operation_abstract_type_;
+extern const abstract_type xen_event_operation_set_abstract_type_;
+
+
+#endif
diff --git a/tools/libxen/src/xen_event.c b/tools/libxen/src/xen_event.c
new file mode 100644
index 0000000000..3022caffed
--- /dev/null
+++ b/tools/libxen/src/xen_event.c
@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+
+#include <stddef.h>
+#include <stdlib.h>
+
+#include "xen_common.h"
+#include "xen_event.h"
+#include "xen_event_operation_internal.h"
+#include "xen_internal.h"
+
+
+XEN_ALLOC(xen_event_record)
+XEN_SET_ALLOC_FREE(xen_event_record)
+
+
+static const struct_member xen_event_record_struct_members[] =
+    {
+        { .key = "id",
+          .type = &abstract_type_int,
+          .offset = offsetof(xen_event_record, id) },
+        { .key = "timestamp",
+          .type = &abstract_type_datetime,
+          .offset = offsetof(xen_event_record, timestamp) },
+        { .key = "class",
+          .type = &abstract_type_string,
+          .offset = offsetof(xen_event_record, class) },
+        { .key = "operation",
+          .type = &xen_event_operation_abstract_type_,
+          .offset = offsetof(xen_event_record, operation) },
+        { .key = "ref",
+          .type = &abstract_type_string,
+          .offset = offsetof(xen_event_record, ref) },
+        { .key = "obj_uuid",
+          .type = &abstract_type_string,
+          .offset = offsetof(xen_event_record, obj_uuid) }
+    };
+
+const abstract_type xen_event_record_abstract_type_ =
+    {
+       .typename = STRUCT,
+       .struct_size = sizeof(xen_event_record),
+       .member_count =
+           sizeof(xen_event_record_struct_members) / sizeof(struct_member),
+       .members = xen_event_record_struct_members
+    };
+
+
+const abstract_type xen_event_record_set_abstract_type_ =
+    {
+       .typename = SET,
+        .child = &xen_event_record_abstract_type_
+    };
+
+
+void
+xen_event_record_free(xen_event_record *record)
+{
+    if (record == NULL)
+    {
+        return;
+    }
+    free(record->class);
+    free(record->ref);
+    free(record->obj_uuid);
+    free(record);
+}
+
+
+bool
+xen_event_register(xen_session *session, struct xen_string_set *classes)
+{
+    abstract_value param_values[] =
+        {
+            { .type = &abstract_type_string_set,
+              .u.set_val = (arbitrary_set *)classes }
+        };
+
+    xen_call_(session, "event.register", param_values, 1, NULL, NULL);
+    return session->ok;
+}
+
+
+bool
+xen_event_unregister(xen_session *session, struct xen_string_set *classes)
+{
+    abstract_value param_values[] =
+        {
+            { .type = &abstract_type_string_set,
+              .u.set_val = (arbitrary_set *)classes }
+        };
+
+    xen_call_(session, "event.unregister", param_values, 1, NULL, NULL);
+    return session->ok;
+}
+
+
+bool
+xen_event_next(xen_session *session, struct xen_event_record_set **result)
+{
+
+    abstract_type result_type = xen_event_record_set_abstract_type_;
+
+    *result = NULL;
+    xen_call_(session, "event.next", NULL, 0, &result_type, result);
+    return session->ok;
+}
diff --git a/tools/libxen/src/xen_event_operation.c b/tools/libxen/src/xen_event_operation.c
new file mode 100644
index 0000000000..c338af0930
--- /dev/null
+++ b/tools/libxen/src/xen_event_operation.c
@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2006-2007, XenSource Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+#include <string.h>
+
+#include "xen_internal.h"
+#include "xen_event_operation.h"
+#include "xen_event_operation_internal.h"
+
+
+/*
+ * Maintain this in the same order as the enum declaration!
+ */
+static const char *lookup_table[] =
+{
+    "add",
+    "del",
+    "mod"
+};
+
+
+extern xen_event_operation_set *
+xen_event_operation_set_alloc(size_t size)
+{
+    return calloc(1, sizeof(xen_event_operation_set) +
+                  size * sizeof(enum xen_event_operation));
+}
+
+
+extern void
+xen_event_operation_set_free(xen_event_operation_set *set)
+{
+    free(set);
+}
+
+
+const char *
+xen_event_operation_to_string(enum xen_event_operation val)
+{
+    return lookup_table[val];
+}
+
+
+extern enum xen_event_operation
+xen_event_operation_from_string(xen_session *session, const char *str)
+{
+    return ENUM_LOOKUP(session, str, lookup_table);
+}
+
+
+const abstract_type xen_event_operation_abstract_type_ =
+    {
+        .typename = ENUM,
+        .enum_marshaller =
+             (const char *(*)(int))&xen_event_operation_to_string,
+        .enum_demarshaller =
+             (int (*)(xen_session *, const char *))&xen_event_operation_from_string
+    };
+
+
diff --git a/tools/libxen/test/test_event_handling.c b/tools/libxen/test/test_event_handling.c
new file mode 100644
index 0000000000..52638949ae
--- /dev/null
+++ b/tools/libxen/test/test_event_handling.c
@@ -0,0 +1,211 @@
+/*
+ * Copyright (c) 2006-2007 XenSource, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+ */
+
+#define _GNU_SOURCE
+#include <assert.h>
+#include <inttypes.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <libxml/parser.h>
+#include <curl/curl.h>
+
+#include "xen_event.h"
+
+//#define PRINT_XML
+
+static void usage()
+{
+    fprintf(stderr,
+"Usage:\n"
+"\n"
+"    test_event_handling <server> <username> <password>\n"
+"\n"
+"where\n"
+"        <server>   is the server's host and port, e.g. localhost:9363;\n"
+"        <username> is the username to use at the server; and\n"
+"        <password> is the password.\n");
+
+    exit(EXIT_FAILURE);
+}
+
+
+static char *url;
+
+
+typedef struct
+{
+    xen_result_func func;
+    void *handle;
+} xen_comms;
+
+
+static size_t
+write_func(void *ptr, size_t size, size_t nmemb, xen_comms *comms)
+{
+    size_t n = size * nmemb;
+#ifdef PRINT_XML
+    printf("\n\n---Result from server -----------------------\n");
+    printf("%s\n",((char*) ptr));
+    fflush(stdout);
+#endif
+    return comms->func(ptr, n, comms->handle) ? n : 0;
+}
+
+
+static int
+call_func(const void *data, size_t len, void *user_handle,
+          void *result_handle, xen_result_func result_func)
+{
+    (void)user_handle;
+
+#ifdef PRINT_XML
+    printf("\n\n---Data to server: -----------------------\n");
+    printf("%s\n",((char*) data));
+    fflush(stdout);
+#endif
+
+    CURL *curl = curl_easy_init();
+    if (!curl) {
+        return -1;
+    }
+
+    xen_comms comms = {
+        .func = result_func,
+        .handle = result_handle
+    };
+
+    curl_easy_setopt(curl, CURLOPT_URL, url);
+    curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 1);
+    curl_easy_setopt(curl, CURLOPT_MUTE, 1);
+    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, &write_func);
+    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &comms);
+    curl_easy_setopt(curl, CURLOPT_POST, 1);
+    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
+    curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, len);
+
+    CURLcode result = curl_easy_perform(curl);
+
+    curl_easy_cleanup(curl);
+
+    return result;
+}
+
+
+static void print_error(xen_session *session)
+{
+    fprintf(stderr, "Error: %d", session->error_description_count);
+    for (int i = 0; i < session->error_description_count; i++)
+    {
+        fprintf(stderr, "%s ", session->error_description[i]);
+    }
+    fprintf(stderr, "\n");
+}
+
+
+/**
+ * Workaround for whinging GCCs, as suggested by strftime(3).
+ */
+static size_t my_strftime(char *s, size_t max, const char *fmt,
+                          const struct tm *tm)
+{
+    return strftime(s, max, fmt, tm);
+}
+
+
+int main(int argc, char **argv)
+{
+    if (argc != 4)
+    {
+        usage();
+    }
+
+    url = argv[1];
+    char *username = argv[2];
+    char *password = argv[3];
+
+    xmlInitParser();
+    xen_init();
+    curl_global_init(CURL_GLOBAL_ALL);
+
+#define CLEANUP                                 \
+    do {                                        \
+        xen_session_logout(session);            \
+        curl_global_cleanup();                  \
+        xen_fini();                             \
+        xmlCleanupParser();                     \
+    } while(0)                                  \
+
+    
+    xen_session *session =
+        xen_session_login_with_password(call_func, NULL, username, password);
+
+    struct xen_string_set *classes = xen_string_set_alloc(0);
+    xen_event_register(session, classes);
+    xen_string_set_free(classes);
+
+    if (!session->ok)
+    {
+        print_error(session);
+        CLEANUP;
+        return 1;
+    }
+
+    while (true)
+    {
+        struct xen_event_record_set *events;
+        if (!xen_event_next(session, &events))
+        {
+            print_error(session);
+            CLEANUP;
+            return 1;
+        }
+
+        for (size_t i = 0; i < events->size; i++)
+        {
+            xen_event_record *ev = events->contents[i];
+            char time[256];
+            struct tm *tm = localtime(&ev->timestamp);
+            my_strftime(time, 256, "%c, local time", tm);
+            printf("Event received: ID = %"PRId64", %s.\n", ev->id, time);
+            switch (ev->operation)
+            {
+            case XEN_EVENT_OPERATIONS_ADD:
+                printf("%s created with UUID %s.\n", ev->class, ev->obj_uuid);
+                break;
+
+            case XEN_EVENT_OPERATIONS_DEL:
+                printf("%s with UUID %s deleted.\n", ev->class, ev->obj_uuid);
+                break;
+
+            case XEN_EVENT_OPERATIONS_MOD:
+                printf("%s with UUID %s modified.\n", ev->class, ev->obj_uuid);
+                break;
+            default:
+                assert(false);
+            }
+        }
+
+        xen_event_record_set_free(events);
+    }
+
+    CLEANUP;
+
+    return 0;
+}