Merge lp:geis/2.x into lp:geis

[Stephen M. Webb]

Added GEIS v2.0 subscription module (construction and accessors only).

Fixed a typo in the Doxygen comments in geis.h.

[Chase Douglas (chasedouglas)]

Commit 105 highlights that GeisSize is implemented as an unsigned long. This size varies between architectures on Linux. Although I would have liked a static size, I think this is ok. However, we need to be very careful. We are going to be sending data between clients and a grail service. When we encode data we cannot use GeisSize. We will need to use set bit-width elements. A 32-bit client could be running on a 64-bit machine where grail is 64-bit.

I have questions about the subscription and filter usage, I'll track down Stephen to have a conversation about it. I may just need some more information.

commits 105 and 107 seem fine to me as is.

[Chase Douglas (chasedouglas)]

After reviewing the spec some more, I think the subscription and filter functions are fine.

We're getting closer to specifying the form of the filters, and I feel this is the greatest challenge of geis. We have to take into account gesture types and numbers of fingers, including the ability to specify ranges of changes of numbers of fingers for gesture continuation. However, that discussion will come after this merge proposal.

review: Approve

[Henrik Rydberg (rydberg)]

+ geis_error("creation of subscroption bag failed");

I cannot help to think it is quite a bit of code, but it does serve its purpose.

review: Approve

[Mohamed IKBEL Boulabiar (boulabiar)]

The patch looks nice.

(I'm just thinking gotos can be avoided but that's not important in our case here)

review: Approve

[lp:geis/2.x]

108. By Stephen M. Webb on 2010-11-29

Improved internal data encapsulation.

109. By Stephen M. Webb on 2010-11-30

Fixed a sig11 in a test case

=== modified file 'ChangeLog'
--- ChangeLog	2010-11-26 18:22:53 +0000
+++ ChangeLog	2010-11-29 17:52:57 +0000
@@ -1,3 +1,38 @@
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Fixed a typo in the Doxygen comments in geis.h.
+
+  * include/geis/geis.h: fixed typo in documentation
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added Geis Subscription creation and accessors.
+
+  * libutouch-geis/geis_subscription.c: new file
+  * libutouch-geis/geis_subscription.h: new file
+  * testsuite/geis2/check_subscription.c: new API test suite
+  * testsuite/libutouch-geis/check_subscription.c: new internals test suite
+  * include/geis/geis.h (GeisFilter): new type
+    (GeisSubscription): new type
+    (GeisSubscriptionFlags): new type
+    (geis_subscription_new): new function
+    (geis_subscription_delete): new function
+    (geis_subscription_name): new function
+    (geis_subscription_id): new function
+    (geis_subscription_add_filter): new function
+    (geis_subscription_remove_filter): new function
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/geis_private.h (geis_subscription_bag): new function
+    (struct _Geis): added subscription_bag field
+  * libutouch-geis/geis.c (geis_subscription_bag): implemented it
+    (geis_new_empty): created an empty subscription bag
+  * libutouch-geis/libutouch-geis.ver: added new geis_subscription_* symbols
+  * testsuite/geis2/Makefile.am: added new test suite source
+  * testsuite/geis2/check_geis2_api.c: added new test suite
+  * testsuite/libutouch-geis/Makefile.am: added new test suite source
+  * testsuite/libutouch-geis/check_geis2_internals.c: added new test suite
+
+
 2010-11-26  Stephen M. Webb  <[e-mail]>
 
   Added Geis Attr functions.

=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2010-11-26 18:22:53 +0000
+++ include/geis/geis.h	2010-11-29 17:52:57 +0000
@@ -344,9 +344,9 @@
  *                                      depends on the
  *                                      @p configuration_value_name.
  *
- * @retval GEIS_STATUS_BAD_ARGUMENT  an invalid argument value was passed
- * @retval GEIS_STATUS_NO_SUPPORTED  the configuration value is not supported
- * @retval GEIS_STATUS_SUCCESS       normal successful completion
+ * @retval GEIS_STATUS_BAD_ARGUMENT   an invalid argument value was passed
+ * @retval GEIS_STATUS_NOT_SUPPORTED  the configuration value is not supported
+ * @retval GEIS_STATUS_SUCCESS        normal successful completion
  */
 GEIS_API GeisStatus geis_get_configuration(Geis        geis, 
                                            GeisString  configuration_item_name,
@@ -363,9 +363,9 @@
  *                                     this buffer depends on the
  *                                     @p configuration_value_name.
  *
- * @retval GEIS_STATUS_BAD_ARGUMENT  an invalid argument value was passed
- * @retval GEIS_STATUS_NO_SUPPORTED  the configuration value is not supported
- * @retval GEIS_STATUS_SUCCESS       normal successful completion
+ * @retval GEIS_STATUS_BAD_ARGUMENT   an invalid argument value was passed
+ * @retval GEIS_STATUS_NOT_SUPPORTED  the configuration value is not supported
+ * @retval GEIS_STATUS_SUCCESS        normal successful completion
  */
 GEIS_API GeisStatus geis_set_configuration(Geis        geis,
                                            GeisString  configuration_item_name, 
@@ -494,7 +494,7 @@
 /* @} */
 
 /**
- * @defgroup geis_subscription Gesture Subscription
+ * @defgroup geis1_subscription Gesture Subscription (GEIS v1.0)
  * @{
  */
 typedef unsigned int GeisGestureType;
@@ -580,6 +580,88 @@
 
 /* @} */
 
+/**
+ * @defgroup geis2_subscription Gesture Subscription (GEIS v2.0)
+ * @{
+ */
+
+typedef struct _GeisFilter *GeisFilter;
+typedef struct _GeisSubscription *GeisSubscription;
+
+/**
+ * Flags to refine the behaviour of the gesture subscription.
+ */
+typedef enum _GeisSubscriptionFlags
+{
+  GEIS_SUBSCRIPTION_NONE = 0x0000,
+  GEIS_SUBSCRIPTION_GRAB = 0x0001,
+  GEIS_SUBSCRIPTION_CONT = 0x0002
+} GeisSubscriptionFlags;
+
+/**
+ * Creates a new subscription.
+ *
+ * @param[in] geis  The GEIS API instance.
+ * @param[in] name  A name.
+ * @param[in] flags Some flags.
+ *
+ * @returns a GeisSubscription object or NULL on failure.
+ *
+ * A gesture subscription is required for any gesture events to be delivered
+ * from the GEIS API.
+ */
+GEIS_API GeisSubscription geis_subscription_new(Geis                  geis,
+                                                GeisString            name,
+                                                GeisSubscriptionFlags flags);
+
+/**
+ * Destroys a GEIS v2.0 subscription object.
+ *
+ * @param[in] subscription  The subscription.
+ */
+GEIS_API GeisStatus geis_subscription_delete(GeisSubscription subscription);
+
+/**
+ * Gets the name given to a subscription when it was created.
+ *
+ * @param[in] subscription  The subscription.
+ */
+GEIS_API GeisString geis_subscription_name(GeisSubscription subscription);
+
+/**
+ * Gets the ID assigned to a subscription when it was created.
+ *
+ * @param[in] subscription  The subscription.
+ */
+GEIS_API GeisInteger geis_subscription_id(GeisSubscription subscription);
+
+/**
+ * Adds a filter to a subscription.
+ *
+ * @param[in] subscription  The subscription.
+ * @param[in] filter        The filter to be added to the subscription.
+ *
+ * Thye effect of filters are ANDed together so that, for example, a
+ * subscription that has a filter for 3-finger gestures and drag gestures will
+ * produce events only for 3-finger drag gestures.
+ *
+ * The default is no filters:  that is, all possible gesture events will be
+ * reported.
+ */
+GEIS_API GeisStatus geis_subscription_add_filter(GeisSubscription subscription,
+                                                 GeisFilter       filter);
+
+/**
+ * Removes a filter from a subscription.
+ *
+ * @param[in] subscription  The subscription.
+ * @param[in] filter        The filter to be removed from the subscription.
+ */
+GEIS_API GeisStatus geis_subscription_remove_filter(GeisSubscription subscription,
+                                                    GeisFilter       filter);
+
+/* @} */
+
 #ifdef __cplusplus
 } // extern "C"
 #endif

=== modified file 'libutouch-geis/Makefile.am'
--- libutouch-geis/Makefile.am	2010-11-26 18:22:53 +0000
+++ libutouch-geis/Makefile.am	2010-11-29 17:52:57 +0000
@@ -23,10 +23,11 @@
 lib_LTLIBRARIES = libutouch-geis.la
 
 libutouch_geis_la_SOURCES = \
-	geis_attr.h     geis_attr.c \
-	geis_error.h    geis_error.c \
-	geis_logging.h  geis_logging.c \
-	geis_private.h  geis.c
+	geis_attr.h         geis_attr.c \
+	geis_error.h        geis_error.c \
+	geis_logging.h      geis_logging.c \
+	geis_subscription.h geis_subscription.c \
+	geis_private.h      geis.c
 
 libutouch_geis_la_CPPFLAGS = \
 	-Wall -Wextra \

=== modified file 'libutouch-geis/geis.c'
--- libutouch-geis/geis.c	2010-11-25 03:14:17 +0000
+++ libutouch-geis/geis.c	2010-11-29 17:52:57 +0000
@@ -40,7 +40,20 @@
   {
     geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
     geis_error("calloc failed");
-  }
+    goto error_exit;
+  }
+
+  geis->subscription_bag = geis_subscription_bag_new(1);
+  if (!geis->subscription_bag)
+  {
+    geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("creation of subscroption bag failed");
+    free(geis);
+    geis = NULL;
+    goto error_exit;
+  }
+
+error_exit:
   return geis;
 }
 
@@ -132,3 +145,11 @@
   return GEIS_STATUS_UNKNOWN_ERROR;
 }
 
+
+GeisSubBag
+geis_subscription_bag(Geis geis)
+{
+  return geis->subscription_bag;
+}
+
+

=== modified file 'libutouch-geis/geis_error.c'
--- libutouch-geis/geis_error.c	2010-11-23 23:33:37 +0000
+++ libutouch-geis/geis_error.c	2010-11-29 17:52:57 +0000
@@ -49,7 +49,7 @@
     error_stack->store = realloc(error_stack->store, error_stack->store_size);
     if (!error_stack->store)
     {
-      geis_error("error_stack realloc failed for size %d",
+      geis_error("error_stack realloc failed for size %lu",
                  error_stack->store_size);
       return;
     }
@@ -128,7 +128,7 @@
 
 
 GeisString
-geis_error_message(Geis geis, GeisSize index)
+geis_error_message(Geis geis, GeisSize index __attribute__((unused)))
 {
   GeisString message = "";
   if (geis)

=== modified file 'libutouch-geis/geis_private.h'
--- libutouch-geis/geis_private.h	2010-11-23 23:33:37 +0000
+++ libutouch-geis/geis_private.h	2010-11-29 17:52:57 +0000
@@ -24,13 +24,21 @@
 #include <geis/geis.h>
 
 #include "geis_error.h"
+#include "geis_subscription.h"
 
 
 struct _Geis
 {
   GeisBoolean    is_test_fixture;
   GeisErrorStack error_stack;
+  GeisSubBag     subscription_bag;
 };
 
 
+/**
+ * Gets the subscription container from the geis object.
+ */
+GeisSubBag geis_subscription_bag(Geis geis);
+
+
 #endif /* GEIS_PRIVATE_H_ */

=== added file 'libutouch-geis/geis_subscription.c'
--- libutouch-geis/geis_subscription.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_subscription.c	2010-11-29 17:52:57 +0000
@@ -0,0 +1,306 @@
+/**
+ * @file libutouch-geis/geis_subscription.c
+ * @brief implementation of the uTouch GEIS v2.0 API subscription module
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#include "geis_config.h"
+#include "geis_subscription.h"
+
+#include "geis/geis.h"
+#include "geis_private.h"
+#include "geis_logging.h"
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+
+struct _GeisSubscription
+{
+  Geis                  sub_geis;
+  GeisInteger           sub_id;
+  GeisString            sub_name;
+  GeisSubscriptionFlags sub_flags;
+};
+
+struct _GeisSubBag
+{
+  GeisSubscription *sub_store;
+  GeisSize          sub_store_size;
+};
+
+static const float sub_bag_growth_constant = 1.5f;
+
+
+/**
+ * Creates a new subsciption container.
+ */
+GeisSubBag
+geis_subscription_bag_new(GeisSize size_hint)
+{
+  GeisSubBag bag = calloc(1, sizeof(struct _GeisSubBag));
+  if (!bag)
+  {
+    geis_error("failed to allocate subscription container");
+    goto error_exit;
+  }
+
+  bag->sub_store_size = size_hint > 2 ? size_hint : 2;
+  bag->sub_store = calloc(bag->sub_store_size, sizeof(GeisSubscription));
+  if (!bag->sub_store)
+  {
+    geis_error("failed to allocate subscription container store");
+    free(bag);
+    bag = NULL;
+  }
+
+error_exit:
+  return bag;
+}
+
+
+/**
+ * Destroys a subsciption container and free any associated resources.
+ *
+ * Any contained subsciptions that are still valid are also destroyed.
+ */
+void
+geis_subscription_bag_delete(GeisSubBag bag)
+{
+  GeisSize i;
+  for (i = 0; i < bag->sub_store_size; ++i)
+  {
+    if (bag->sub_store[i])
+      geis_subscription_delete(bag->sub_store[i]);
+  }
+  free(bag);
+}
+
+
+/**
+ * Gets the number of (valid) subsciptions in the subsciption container.
+ */
+GeisSize
+geis_subscription_bag_count(GeisSubBag bag)
+{
+  GeisSize count = 0;
+  GeisSize i;
+  for (i = 0; i < bag->sub_store_size; ++i)
+  {
+    if (bag->sub_store[i])
+      ++count;
+  }
+  return count;
+}
+
+
+/**
+ * Inserts a subscription in the subscription container.
+ */
+GeisSize
+geis_subscription_bag_insert(GeisSubBag       bag,
+                             GeisSubscription sub)
+{
+  GeisSize index = -1;
+  for (index = 0; index <  bag->sub_store_size; ++index)
+  {
+    if (!bag->sub_store[index])
+    {
+      bag->sub_store[index] = sub;
+      geis_debug("subscription \"%s\" inserted at index %lu",
+                 sub->sub_name, index);
+      goto final_exit;
+    }
+  }
+
+  GeisSize new_store_size = ceilf(bag->sub_store_size
+                                * sub_bag_growth_constant);
+  GeisSubscription *new_store = realloc(bag->sub_store, new_store_size);
+  if (!new_store)
+  {
+    geis_error("failed to reallocate sub bag");
+    goto final_exit;
+  }
+  index = bag->sub_store_size;
+  bag->sub_store = new_store;
+  bag->sub_store_size = new_store_size;
+  bag->sub_store[index] = sub;
+  geis_debug("subscription \"%s\" inserted at index %lu",
+             sub->sub_name, index);
+
+final_exit:
+  return index;
+}
+
+
+void
+geis_subscription_bag_remove(GeisSubBag       bag,
+                             GeisSubscription sub)
+{
+  bag->sub_store[sub->sub_id] = NULL;
+  geis_debug("subscription \"%s\" removed", sub->sub_name);
+}
+
+
+/**
+ * Finds a subsciption by ID.
+ */
+GeisSubscription
+geis_subscription_bag_find(GeisSubBag bag, GeisInteger sub_id)
+{
+  GeisSubscription sub = NULL;
+  GeisSize i;
+  for (i = 0; i < bag->sub_store_size; ++i)
+  {
+    if (bag->sub_store[i] && bag->sub_store[i]->sub_id == sub_id)
+    {
+      sub = bag->sub_store[i];
+      break;
+    }
+  }
+  return sub;
+}
+
+
+/**
+ * Creates a new subsciption on an API instance.
+ */
+GeisSubscription
+geis_subscription_new(Geis                  geis,
+                      GeisString            sub_name,
+                      GeisSubscriptionFlags sub_flags)
+{
+  GeisSubscription sub = calloc(1, sizeof(struct _GeisSubscription));
+  if (!sub)
+  {
+    geis_error_push(geis, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("calloc failed");
+    goto error_exit;
+  }
+  else
+  {
+    if (sub_name)
+    {
+      sub->sub_name = strdup(sub_name);
+    }
+    else
+    {
+      sub->sub_name = strdup("");
+    }
+    sub->sub_geis = geis;
+    sub->sub_id = geis_subscription_bag_insert(geis_subscription_bag(geis), sub);
+    sub->sub_flags = sub_flags;
+    geis_debug("creating subscription \"%s\" id %d", sub->sub_name, sub->sub_id);
+  }
+
+error_exit:
+  return sub;
+}
+
+
+/**
+ * Frees all resources allocated for the subscription and destroys the
+ * subscription.  Use of the subscription oject after this call will result in
+ * undefined behaviour.
+ */
+GeisStatus
+geis_subscription_delete(GeisSubscription sub)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  if (!sub)
+  {
+    status = GEIS_STATUS_BAD_ARGUMENT;
+    goto error_exit;
+  }
+
+  geis_debug("destroying subscription \"%s\" id %d", sub->sub_name, sub->sub_id);
+
+  geis_subscription_bag_remove(geis_subscription_bag(sub->sub_geis), sub);
+
+  free((char *)sub->sub_name);
+  free(sub);
+  status = GEIS_STATUS_SUCCESS;
+
+error_exit:
+  return status;
+}
+
+
+/**
+ * Retrieves the name used on creation of the subscrition.
+ */
+GeisString
+geis_subscription_name(GeisSubscription subscription)
+{
+  return subscription->sub_name;
+}
+
+
+/**
+ * Retrieves the identifier assigned to the subscrition on creation.
+ * The identifier is only unique for a given API instance and identifiers may be
+ * reused after the subscription they identify has been deleted.
+ */
+GeisInteger
+geis_subscription_id(GeisSubscription subscription)
+{
+  return subscription->sub_id;
+}
+
+
+/**
+ * Adds a filter to a subscription.
+ *
+ * @todo implement this function after the filter module is implemented
+ */
+GeisStatus
+geis_subscription_add_filter(GeisSubscription sub,
+                             GeisFilter       filter __attribute__((unused)))
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  if (!sub)
+  {
+    status = GEIS_STATUS_BAD_ARGUMENT;
+    goto error_exit;
+  }
+
+error_exit:
+  return status;
+}
+
+
+/**
+ * Removes a filter from a subscription.
+ *
+ * @todo implement this function after the filter module is implemented
+ */
+GeisStatus
+geis_subscription_remove_filter(GeisSubscription sub,
+                                GeisFilter       filter __attribute__((unused)))
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  if (!sub)
+  {
+    status = GEIS_STATUS_BAD_ARGUMENT;
+    goto error_exit;
+  }
+
+error_exit:
+  return status;
+}
+
+

=== added file 'libutouch-geis/geis_subscription.h'
--- libutouch-geis/geis_subscription.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_subscription.h	2010-11-29 17:52:57 +0000
@@ -0,0 +1,76 @@
+/**
+ * @file geis_subscription.h
+ * @brief internal uTouch Geis subscription modul private interface
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#ifndef GEIS_SUBSCRIPTION_H_
+#define GEIS_SUBSCRIPTION_H_
+
+#include <geis/geis.h>
+
+
+/**
+ * A container for subscriptions.
+ */
+typedef struct _GeisSubBag *GeisSubBag;
+
+
+/**
+ * Creates a new Geis Subscription container.
+ *
+ * @param[in] hint A hint as to how many subscriptions to initially allocate in
+ *                 the new container.
+ */
+GeisSubBag geis_subscription_bag_new(GeisSize size_hint);
+
+/**
+ * Destroys a Geis Subscription container.
+ *
+ * @param[in] bag The bag.
+ */
+void geis_subscription_bag_delete(GeisSubBag bag);
+
+/**
+ * Tells how any entires in a Geis Subscription container.
+ *
+ * @param[in] bag The bag.
+ */
+GeisSize geis_subscription_bag_count(GeisSubBag bag);
+
+/**
+ * Creates a new subscription object in a subscription container.
+ *
+ * @param[in] bag The bag.
+ *
+ * @returns the index of the newly inserted subscription
+ */
+GeisSize geis_subscription_bag_insert(GeisSubBag       bag,
+                                      GeisSubscription sub);
+
+void geis_subscription_bag_removed(GeisSubBag       bag,
+                                       GeisSubscription sub);
+
+/**
+ * Looks for an subscription in an subscription container.
+ *
+ * @param[in] bag The bag.
+ */
+GeisSubscription geis_subscription_bag_find(GeisSubBag bag, GeisInteger sub_id);
+
+
+#endif /* GEIS_SUBSCRIPTION_H_ */

=== modified file 'libutouch-geis/libutouch-geis.ver'
--- libutouch-geis/libutouch-geis.ver	2010-11-26 18:22:53 +0000
+++ libutouch-geis/libutouch-geis.ver	2010-11-29 17:52:57 +0000
@@ -20,12 +20,18 @@
     geis_attr_value_to_integer;
     geis_attr_value_to_string;
     geis_delete;
+    geis_error_code;
     geis_error_count;
-    geis_error_code;
     geis_error_message;
     geis_get_configuration;
     geis_new;
     geis_set_configuration;
+    geis_subscription_add_filter;
+    geis_subscription_delete;
+    geis_subscription_id;
+    geis_subscription_name;
+    geis_subscription_new;
+    geis_subscription_remove_filter;
 
   local:
     *;

=== modified file 'testsuite/geis2/Makefile.am'
--- testsuite/geis2/Makefile.am	2010-11-25 03:14:17 +0000
+++ testsuite/geis2/Makefile.am	2010-11-29 17:52:57 +0000
@@ -18,6 +18,7 @@
 	check_error_codes.c \
 	check_geis_new.c \
 	check_general_types.c \
+	check_subscription.c \
 	check_version_macro.c \
 	check_geis2_api.c
 

=== modified file 'testsuite/geis2/check_geis2_api.c'
--- testsuite/geis2/check_geis2_api.c	2010-11-25 03:14:17 +0000
+++ testsuite/geis2/check_geis2_api.c	2010-11-29 17:52:57 +0000
@@ -9,6 +9,7 @@
 extern Suite *geis2_error_codes_suite_new();
 extern Suite *geis2_geis_new_suite_new();
 extern Suite *geis2_config_suite_new();
+extern Suite *geis2_subscription_suite_new();
 
 int
 main(int argc, char* argv[])
@@ -23,6 +24,7 @@
   srunner_add_suite(sr, geis2_error_codes_suite_new());
   srunner_add_suite(sr, geis2_geis_new_suite_new());
   srunner_add_suite(sr, geis2_config_suite_new());
+  srunner_add_suite(sr, geis2_subscription_suite_new()); 
 
   srunner_set_log(sr, "geis2_api.log");
   srunner_run_all(sr, CK_NORMAL);

=== added file 'testsuite/geis2/check_subscription.c'
--- testsuite/geis2/check_subscription.c	1970-01-01 00:00:00 +0000
+++ testsuite/geis2/check_subscription.c	2010-11-29 17:52:57 +0000
@@ -0,0 +1,67 @@
+/**
+ * Unit tests for GEIS v2.0 subsciption module
+ */
+#include <check.h>
+
+#include <geis/geis.h>
+#include <string.h>
+
+
+/* fixtures */
+static Geis g_geis;
+
+/* fixture setup */
+static void
+construct_geis()
+{
+  g_geis = geis_new("geis-test-fixture", NULL);
+}
+
+/* fixture teardown */
+static void
+destroy_geis()
+{
+  geis_delete(g_geis);
+}
+
+
+/* compile-time test to ensure required types are defined */
+START_TEST(subscription_constants)
+{
+  GeisSubscriptionFlags f = GEIS_SUBSCRIPTION_NONE
+   | GEIS_SUBSCRIPTION_GRAB
+   | GEIS_SUBSCRIPTION_CONT;
+}
+END_TEST
+
+START_TEST(construction)
+{
+  GeisSubscription sub = geis_subscription_new(g_geis,
+						"name",
+						GEIS_SUBSCRIPTION_NONE);
+  fail_unless(sub != NULL,
+              "failed to create subscription");
+  fail_unless(0 == strcmp(geis_subscription_name(sub), "name"),
+  	      "unexpected subscription name returned");
+  geis_subscription_delete(sub);
+}
+END_TEST
+
+/* boilerplate */
+Suite *
+geis2_subscription_suite_new()
+{
+  Suite *s = suite_create("geis2_subscriptions");
+
+  TCase *create = tcase_create("subscription-constants");
+  tcase_add_test(create, subscription_constants);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("subscription-usage");
+  tcase_add_checked_fixture(usage, construct_geis, destroy_geis);
+  tcase_add_test(usage, construction);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+

=== modified file 'testsuite/libutouch-geis/Makefile.am'
--- testsuite/libutouch-geis/Makefile.am	2010-11-26 18:22:53 +0000
+++ testsuite/libutouch-geis/Makefile.am	2010-11-29 17:52:57 +0000
@@ -33,6 +33,7 @@
 check_geis2_internals_SOURCES = \
 	check_attr.c \
 	check_error_reporting.c \
+	check_subscription.c \
 	check_geis2_internals.c
 
 check_geis2_internals_CFLAGS = \

=== modified file 'testsuite/libutouch-geis/check_geis2_internals.c'
--- testsuite/libutouch-geis/check_geis2_internals.c	2010-11-26 18:22:53 +0000
+++ testsuite/libutouch-geis/check_geis2_internals.c	2010-11-29 17:52:57 +0000
@@ -5,6 +5,7 @@
 
 extern Suite *make_error_reporting_suite();
 extern Suite *make_attr_suite();
+extern Suite *make_subscription_suite();
 
 
 int
@@ -17,6 +18,7 @@
   SRunner *sr = srunner_create(s);
   srunner_add_suite(sr, make_error_reporting_suite());
   srunner_add_suite(sr, make_attr_suite());
+  srunner_add_suite(sr, make_subscription_suite());
 
   srunner_set_log(sr, "geis2_internals.log");
   srunner_run_all(sr, CK_NORMAL);

=== added file 'testsuite/libutouch-geis/check_subscription.c'
--- testsuite/libutouch-geis/check_subscription.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_subscription.c	2010-11-29 17:52:57 +0000
@@ -0,0 +1,103 @@
+/**
+ * internal unit tests for the uTouch GEIS v2.0 subscription module
+ */
+#include <check.h>
+
+#include "geis/geis.h"
+#include "libutouch-geis/geis_subscription.h"
+
+
+/* fixtures */
+static Geis g_geis;
+static GeisSubBag g_sub_bag;
+static const GeisString test_sub_string = "zot!";
+
+/* fixture setup */
+static void
+construct_bag()
+{
+  g_geis = geis_new("geis-test-fixture", NULL);
+  g_sub_bag = geis_subscription_bag_new(1);
+}
+
+/* fixture teardown */
+static void
+destroy_bag()
+{
+  geis_subscription_bag_delete(g_sub_bag);
+  geis_delete(g_geis);
+}
+
+
+/* verify bag construction/destruction */
+START_TEST(construction)
+{
+  GeisSubBag bag = geis_subscription_bag_new(1);
+  fail_unless(bag != NULL,
+              "failed to create subscription bag");
+  fail_unless(geis_subscription_bag_count(bag) == 0,
+              "unexpected size");
+  geis_subscription_bag_delete(bag);
+}
+END_TEST
+
+
+/* verify bag insertion */
+START_TEST(insertion)
+{
+  GeisSubscription sub = geis_subscription_new(g_geis,
+                                               "test-sub",
+                                               GEIS_SUBSCRIPTION_NONE);
+  geis_subscription_bag_insert(g_sub_bag, sub);
+  fail_unless(geis_subscription_bag_count(g_sub_bag) == 1,
+  	      "unexpected bag size after insertion");
+}
+END_TEST
+
+
+/* verify bag find operation (positive results) */
+START_TEST(find_success)
+{
+  GeisSubscription sub2;
+  GeisSubscription sub1 = geis_subscription_new(g_geis,
+                                                "test-sub",
+                                                GEIS_SUBSCRIPTION_NONE);
+  GeisSize id = geis_subscription_bag_insert(g_sub_bag, sub1);
+  sub2 = geis_subscription_bag_find(g_sub_bag, id);
+  fail_if(sub2 == NULL, "expected instance not found");
+  fail_unless(0 == strcmp(geis_subscription_name(sub1),
+  			  geis_subscription_name(sub2)),
+  	      "unexpected subscription name returned");
+}
+END_TEST
+
+
+/* verify bag find operation (negative results) */
+START_TEST(find_fail)
+{
+  GeisSubscription sub = geis_subscription_bag_find(g_sub_bag, 999);
+  fail_unless(sub == NULL, "unexpected instance found");
+}
+END_TEST
+
+
+/* boilerplate */
+Suite *
+make_subscription_suite()
+{
+  Suite *s = suite_create("utouch-geis2-subscriptions");
+
+  TCase *create = tcase_create("sub-bag-creation");
+  tcase_add_test(create, construction);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("sub-bag-usage");
+  tcase_add_checked_fixture(usage, construct_bag, destroy_bag);
+  tcase_add_test(usage, insertion);
+  tcase_add_test(usage, find_success);
+  tcase_add_test(usage, find_fail);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+