Merge lp:~oif-team/geis/geis2-add-device into lp:geis

[Stephen M. Webb]

Added GEIS v2.0 device module

[Henrik Rydberg (rydberg)]

Are the region defines untouched in this branch? It seems like it from the logs, but there is quite a bit of diff touching the region header.

review: Needs Information

[Stephen M. Webb (bregma)]

I think you mean the geis.h header.

I had to rearrange a chunk of stuff in include/geis/geis.h to move the GeisEvent declarations before the GeisDevice declarations. It looks like a big diff because the diff machine saw this as moving everything else but the GeisEvent section around. the GeisRegion and GeisSubscriptions chunks are in fact unchanged.

[Henrik Rydberg (rydberg)]

Ok.

review: Approve

=== modified file 'ChangeLog'
--- ChangeLog	2010-12-20 18:06:36 +0000
+++ ChangeLog	2010-12-21 14:03:26 +0000
@@ -1,5 +1,41 @@
 2010-12-20  Stephen M. Webb  <[e-mail]>
 
+  Added GEIS v2.0 input device implementation.
+
+  * libutouch-geis/geis_device.h (GeisDeviceBag): new type
+    (geis_device_bag_new): new function
+    (geis_device_bag_delete): new function
+    (geis_device_bag_count): new function
+    (geis_device_bag_device): new function
+    (geis_device_bag_insert): new function
+    (geis_device_bag_remove): new function
+  * libutouch-geis/geis_device.c: implemented new functions
+  * testsuite/libutouch-geis/check_device.c: new test suite
+  * testsuite/libutouch-geis/Makefile.am: added new test suite
+  * testsuite/libutouch-geis/check_geis2_internals.c: added new test suite
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added GEIS v2.0 input device API
+
+  * libutouch-geis/geis_device.c: new file
+  * libutouch-geis/geis_device.h: new file
+  * testsuite/geis2/check_device.c: new test suite
+  * include/geis/geis.h (GeisDevice): new type
+    (geis_register_device_callback): new function
+    (geis_device_ref): new function
+    (geis_device_unref): new function
+    (geis_device_name): new function
+    (geis_device_id): new function
+    (geis_device_attr_count): new function
+    (geis_device_attr): new function
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/libutouch-geis.ver: added new API symbols
+  * testsuite/geis2/Makefile.am: added new test suite
+  * testsuite/geis2/check_geis2_api.c: added new test suite
+
[phone]  Stephen M. Webb  <[e-mail]>
+
   Updates to match new GEIS v2.0 spec release of 2010.12.20.
   - added a pointer type to the GEIS attr module
   - added additional required GEIS initialization arguments
 
=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2010-12-20 18:06:36 +0000
+++ include/geis/geis.h	2010-12-21 14:03:26 +0000
@@ -658,166 +658,6 @@
 /* @} */
 
 /**
- * @defgroup geis2_region Gesture Regions (GEIS v2.0)
- * @{
- */
-
-typedef struct _GeisRegion *GeisRegion;
-
-/**
- * @defgroup geis2_region_init_args Gesture Region Initialization Arguments
- *
- * Gesture regions are created to describe a particular display/feedback region.
- * The type of the region can not be changed after creation (just create a new
- * region for that).  The types of regions are platform specific and each type
- * may require addition arguments.
- *
- * The following region initialization argument names are required by the
- * GEIS v2.0 specification.
- *
- * @{
- */
-#define GEIS_REGION_X11_ROOT       "org.libgeis.region.x11.root"
-#define GEIS_REGION_X11_WINDOWID   "org.libgeis.region.x11.windowid"
-
-/* @} */
-
-/**
- * Creates a new GEIS v2.0 region.
- *
- * @param[in] geis           The GEIS API instance.
- * @param[in] name           A name.  Used for diagnostics.
- * @param[in] init_arg_name  The name of the first initialization argument.
- *
- * The initialization argument list must be terminated by a NULL.
- *
- * @returns a newly created region, or NULL on failure.
- */
-GEIS_API GeisRegion geis_region_new(Geis       geis,
-                                    GeisString name,
-                                    GeisString init_arg_name, ...);
-
-/**
- * Destroys a GEIS v2.0 region.
- *
- * @param[in] region  The region.
- */
-GEIS_API GeisStatus geis_region_delete(GeisRegion region);
-
-/**
- * Gets the name of a GEIS v2.0 region.
- *
- * @param[in] region  The region.
- *
- * Returns the @p name value used when creating the region.
- */
-GEIS_API GeisString geis_region_name(GeisRegion region);
-
-/* @} */
-
-/**
- * @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);
-
-/**
- * Activates a subscription.
- *
- * @param[in] subscription  The subscription.
- *
- * Puts the subscription into the active state.  Gesture events will be
- * delivered for this subscription.
- */
-GEIS_API GeisStatus geis_subscription_activate(GeisSubscription subscription);
-
-/**
- * Deactivates a subscription.
- *
- * @param[in] subscription  The subscription.
- *
- * Puts the subscription into the inactive state.  Gesture events will not be
- * delivered for this subscription.
- */
-GEIS_API GeisStatus geis_subscription_deactivate(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);
-
-/* @} */
-
-/**
  * @defgroup geis2_event_control Event Control (GEIS v2.0)
  *
  * These functions are used to dispatch events generated from the various other
@@ -978,6 +818,236 @@
 
 /* @} */
 
+/**
+ * @defgroup geis2_device Gesture Input Devices (GEIS v2.0)
+ * @{
+ */
+
+/**
+ * An opaque pointer type representing a gesture-capable input device.
+ *
+ * GeisDevice objects are created by the GEIS API and are reference counted.
+ */
+typedef struct _GeisDevice *GeisDevice;
+
+GEIS_API void geis_register_device_callback(Geis               geis,
+                                            GeisEventCallback  event_callback,
+                                            void              *context);
+
+/**
+ * Adds a reference count to a device.
+ *
+ * @param[in] device The device.
+ *
+ * An application that wishes to guarantee the device object remains valid
+ * should add a reference using this call, and unref when the object is no
+ * longer needed.
+ */
+GEIS_API void geis_device_ref(GeisDevice device);
+
+/**
+ * Removes a reference count from a device.
+ *
+ * @param[in] device The device.
+ *
+ * This function decrements the number of references to the device and, if the
+ * number of references hits zero, deletes the device.
+ */
+GEIS_API void geis_device_unref(GeisDevice device);
+
+/**
+ * Gets the name of teh input device.
+ *
+ * @param[in] device The device.
+ */
+GEIS_API GeisString geis_device_name(GeisDevice device);
+
+/**
+ * Gets the system identifier of the iput device.
+ *
+ * @param[in] device The device.
+ *
+ * The system-defined device identifier is system- and possibly
+ * device-dependent.
+ */
+GEIS_API GeisInteger geis_device_id(GeisDevice device);
+
+/**
+ * Gets the number of attributes of the device.
+ *
+ * @param[in] device The device.
+ */
+GEIS_API GeisSize geis_device_attr_count(GeisDevice device);
+
+/**
+ * Gets the indicated attribute of the device.
+ *
+ * @param[in] device The device.
+ */
+GEIS_API GeisAttr geis_device_attr(GeisDevice device, GeisSize index);
+
+/* @} */
+
+/**
+ * @defgroup geis2_region Gesture Regions (GEIS v2.0)
+ * @{
+ */
+
+typedef struct _GeisRegion *GeisRegion;
+
+/**
+ * @defgroup geis2_region_init_args Gesture Region Initialization Arguments
+ *
+ * Gesture regions are created to describe a particular display/feedback region.
+ * The type of the region can not be changed after creation (just create a new
+ * region for that).  The types of regions are platform specific and each type
+ * may require addition arguments.
+ *
+ * The following region initialization argument names are required by the
+ * GEIS v2.0 specification.
+ *
+ * @{
+ */
+#define GEIS_REGION_X11_ROOT       "org.libgeis.region.x11.root"
+#define GEIS_REGION_X11_WINDOWID   "org.libgeis.region.x11.windowid"
+
+/* @} */
+
+/**
+ * Creates a new GEIS v2.0 region.
+ *
+ * @param[in] geis           The GEIS API instance.
+ * @param[in] name           A name.  Used for diagnostics.
+ * @param[in] init_arg_name  The name of the first initialization argument.
+ *
+ * The initialization argument list must be terminated by a NULL.
+ *
+ * @returns a newly created region, or NULL on failure.
+ */
+GEIS_API GeisRegion geis_region_new(Geis       geis,
+                                    GeisString name,
+                                    GeisString init_arg_name, ...);
+
+/**
+ * Destroys a GEIS v2.0 region.
+ *
+ * @param[in] region  The region.
+ */
+GEIS_API GeisStatus geis_region_delete(GeisRegion region);
+
+/**
+ * Gets the name of a GEIS v2.0 region.
+ *
+ * @param[in] region  The region.
+ *
+ * Returns the @p name value used when creating the region.
+ */
+GEIS_API GeisString geis_region_name(GeisRegion region);
+
+/* @} */
+
+/**
+ * @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);
+
+/**
+ * Activates a subscription.
+ *
+ * @param[in] subscription  The subscription.
+ *
+ * Puts the subscription into the active state.  Gesture events will be
+ * delivered for this subscription.
+ */
+GEIS_API GeisStatus geis_subscription_activate(GeisSubscription subscription);
+
+/**
+ * Deactivates a subscription.
+ *
+ * @param[in] subscription  The subscription.
+ *
+ * Puts the subscription into the inactive state.  Gesture events will not be
+ * delivered for this subscription.
+ */
+GEIS_API GeisStatus geis_subscription_deactivate(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-12-20 18:06:36 +0000
+++ libutouch-geis/Makefile.am	2010-12-21 14:03:26 +0000
@@ -28,6 +28,7 @@
 	geis_backend_protected.h \
 	geis_backend_multiplexor.h  geis_backend_multiplexor.c \
 	geis_backend_test_fixture.h geis_backend_test_fixture.c \
+	geis_device.h               geis_device.c \
 	geis_error.h                geis_error.c \
 	geis_event.h                geis_event.c \
 	geis_event_queue.h          geis_event_queue.c \
 
=== added file 'libutouch-geis/geis_device.c'
--- libutouch-geis/geis_device.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_device.c	2010-12-21 14:03:26 +0000
@@ -0,0 +1,273 @@
+/**
+ * @file libutouch-geis/geis_region.c
+ * @brief implementation of the uTouch GEIS v2.0 API Input Device 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_device.h"
+
+#include "geis_attr.h"
+#include "geis_logging.h"
+#include <stdlib.h>
+#include <string.h>
+
+
+struct _GeisDevice
+{
+  GeisSize    ref_count;
+  GeisString  name;
+  GeisInteger id;
+  GeisAttrBag attr_bag;
+};
+
+struct _GeisDeviceBag
+{
+  GeisDevice *device_store;
+  GeisSize    device_store_size;
+  GeisSize    device_count;
+};
+
+static const int device_bag_growth_constant = 2;
+
+
+GeisDeviceBag
+geis_device_bag_new()
+{
+  GeisDeviceBag bag = calloc(1, sizeof(struct _GeisDeviceBag));
+  if (!bag)
+  {
+    geis_error("error allocating device bag");
+    goto final_exit;
+  }
+
+  bag->device_store = calloc(1, sizeof(struct _GeisDevice));
+  if (!bag->device_store)
+  {
+    geis_error("error allocating device bag store");
+    goto unwind_bag;
+  }
+
+  bag->device_store_size = 1;
+  bag->device_count = 0;
+  goto final_exit;
+
+unwind_bag:
+  free(bag);
+  bag = NULL;
+final_exit:
+  return bag;
+}
+
+
+void
+geis_device_bag_delete(GeisDeviceBag bag)
+{
+  GeisSize i;
+  for (i = bag->device_count; i > 0; --i)
+  {
+    geis_device_unref(bag->device_store[i-1]);
+  }
+  free(bag->device_store);
+  free(bag);
+}
+
+
+GeisSize
+geis_device_bag_count(GeisDeviceBag bag)
+{
+  return bag->device_count;
+}
+
+
+GeisDevice
+geis_device_bag_device(GeisDeviceBag bag, GeisSize index)
+{
+  GeisDevice device = NULL;
+  if (index >= bag->device_count)
+  {
+    geis_warning("device bag index out of range");
+  }
+  else
+  {
+    device = bag->device_store[index];
+  }
+  return device;
+}
+
+
+GeisStatus
+geis_device_bag_insert(GeisDeviceBag bag, GeisDevice device)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  if (bag->device_count >= bag->device_store_size)
+  {
+    GeisSize new_store_size = bag->device_store_size * device_bag_growth_constant;
+    GeisDevice *new_store = realloc(bag->device_store,
+             new_store_size * sizeof(struct _GeisDevice));
+    if (!new_store)
+    {
+      geis_error("failed to reallocate device bag");
+      goto error_exit;
+    }
+    bag->device_store = new_store;
+    bag->device_store_size = new_store_size;
+  }
+  bag->device_store[bag->device_count++] = device;
+  status = GEIS_STATUS_SUCCESS;
+
+error_exit:
+  return status;
+}
+
+GeisStatus
+geis_device_bag_remove(GeisDeviceBag bag, GeisDevice device)
+{
+  GeisSize i;
+  GeisStatus status = GEIS_STATUS_SUCCESS;
+  for (i = 0; i < bag->device_count; ++i)
+  {
+    if (bag->device_store[i] == device)
+    {
+      GeisSize j;
+      geis_device_unref(bag->device_store[i]);
+      --bag->device_count;
+      for (j = i; j < bag->device_count; ++j)
+      {
+	bag->device_store[j] = bag->device_store[j+1];
+      }
+      break;
+    }
+  }
+  return status;
+}
+
+
+/*
+ * Creates a new, empty device.
+ */
+GeisDevice
+geis_device_new(GeisString name, GeisInteger id)
+{
+  GeisDevice device = calloc(1, sizeof(struct _GeisDevice));
+  if (!device)
+  {
+    geis_error("error allocating input device");
+    goto final_exit;
+  }
+
+  device->attr_bag = geis_attr_bag_new(4);
+  if (!device->attr_bag)
+  {
+    geis_debug("error allocating attr bag");
+    goto unwind_device;
+  }
+
+  device->name = strdup(name);
+  if (!device->name)
+  {
+    geis_debug("error allocating device name");
+    goto unwind_attrs;
+  }
+
+  device->id = id;
+  geis_device_ref(device);
+  goto final_exit;
+
+unwind_attrs:
+  geis_attr_bag_delete(device->attr_bag);
+unwind_device:
+  free(device);
+  device = NULL;
+final_exit:
+  return device;
+}
+
+
+/*
+ * Destroys a device.
+ */
+static void
+_device_delete(GeisDevice device)
+{
+  free((char *)device->name);
+  free(device);
+}
+
+
+/*
+ * Adds a reference count to a device.
+ */
+void
+geis_device_ref(GeisDevice device)
+{
+  __sync_add_and_fetch(&device->ref_count, 1);
+}
+
+
+/*
+ * Removes a reference count from a device.
+ */
+void
+geis_device_unref(GeisDevice device)
+{
+  if (0 ==  __sync_sub_and_fetch(&device->ref_count, 1))
+  {
+    _device_delete(device);
+  }
+}
+
+
+/*
+ * Gets the name of teh input device.
+ */
+GeisString
+geis_device_name(GeisDevice device)
+{
+  return device->name;
+}
+
+
+/*
+ * Gets the system identifier of the iput device.
+ */
+GeisInteger
+geis_device_id(GeisDevice device)
+{
+  return device->id;
+}
+
+
+/*
+ * Gets the number of attributes of the device.
+ */
+GeisSize
+geis_device_attr_count(GeisDevice device)
+{
+  return geis_attr_bag_count(device->attr_bag);
+}
+
+
+/*
+ * Gets the indicated attribute of the device.
+ */
+GeisAttr
+geis_device_attr(GeisDevice device, GeisSize index)
+{
+  return geis_attr_bag_attr(device->attr_bag, index);
+}
+
 
=== added file 'libutouch-geis/geis_device.h'
--- libutouch-geis/geis_device.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_device.h	2010-12-21 14:03:26 +0000
@@ -0,0 +1,104 @@
+/**
+ * @file geis_device.h
+ * @brief internal uTouch Geis Input Device module 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_DEVICE_H_
+#define GEIS_DEVICE_H_
+
+#include "geis/geis.h"
+
+/**
+ * @defgroup utouch_geis_device_container A Device Container
+ * @{
+ */
+
+/**
+ * An unsorted container for holding devices.
+ */
+typedef struct _GeisDeviceBag *GeisDeviceBag;
+
+/**
+ * Creates a new device bag,
+ */
+GeisDeviceBag geis_device_bag_new();
+
+/**
+ * Destroys a device bag.
+ *
+ * @param[in] bag The device bag,
+ */
+void geis_device_bag_delete(GeisDeviceBag bag);
+
+/**
+ * Gets the number of devices in the bag.
+ *
+ * @param[in] bag The device bag,
+ */
+GeisSize geis_device_bag_count(GeisDeviceBag bag);
+
+/**
+ * Gets an indicated device from a bag.
+ *
+ * @param[in] bag   The device bag.
+ * @param[in] index The index.
+ */
+GeisDevice geis_device_bag_device(GeisDeviceBag bag, GeisSize index);
+
+/**
+ * Inserts a device in teh bag.
+ *
+ * @param[in] bag    The device bag.
+ * @param[in] device The device to insert.
+ */
+GeisStatus geis_device_bag_insert(GeisDeviceBag bag, GeisDevice device);
+
+/**
+ * Remoes a device from the bag.
+ *
+ * @param[in] bag    The device bag.
+ * @param[in] device The device to remove.
+ */
+GeisStatus geis_device_bag_remove(GeisDeviceBag bag, GeisDevice device);
+
+/** @} */
+
+/**
+ * @defgroup utouch_geis_device Internal Device Functions
+ * @{
+ */
+
+/**
+ * Creates a new device.
+ *
+ * @param[in] name A system-specific device name.
+ * @param[in] id   A system-specific device identifier.
+ */
+GeisDevice geis_device_new(GeisString name, GeisInteger id);
+
+/**
+ * Inserts an attr into a device.
+ *
+ * @param[in] device  A device.
+ * @param[in] attr    An attr.
+ */
+void geis_device_add_attr(GeisDevice device, GeisAttr attr);
+
+/* @} */
+
+#endif /* GEIS_DEVICE_H_ */
 
=== modified file 'libutouch-geis/libutouch-geis.ver'
--- libutouch-geis/libutouch-geis.ver	2010-12-20 18:06:36 +0000
+++ libutouch-geis/libutouch-geis.ver	2010-12-21 14:03:26 +0000
@@ -21,6 +21,12 @@
     geis_attr_value_to_pointer;
     geis_attr_value_to_string;
     geis_delete;
+    geis_device_attr;
+    geis_device_attr_count;
+    geis_device_id;
+    geis_device_name;
+    geis_device_ref;
+    geis_device_unref;
     geis_dispatch_events;
     geis_error_code;
     geis_error_count;
@@ -31,6 +37,7 @@
     geis_region_delete;
     geis_region_name;
     geis_region_new;
+    geis_register_device_callback;
     geis_register_event_callback;
     geis_set_configuration;
     geis_subscription_activate;
 
=== modified file 'testsuite/geis2/Makefile.am'
--- testsuite/geis2/Makefile.am	2010-12-20 18:06:36 +0000
+++ testsuite/geis2/Makefile.am	2010-12-21 14:03:26 +0000
@@ -16,6 +16,7 @@
 check_geis2_api_SOURCES = \
 	check_attr.c \
 	check_config.c \
+	check_device.c \
 	check_error_codes.c \
 	check_event.c \
 	check_geis_new.c \
 
=== added file 'testsuite/geis2/check_device.c'
--- testsuite/geis2/check_device.c	1970-01-01 00:00:00 +0000
+++ testsuite/geis2/check_device.c	2010-12-21 14:03:26 +0000
@@ -0,0 +1,45 @@
+/**
+ * Unit tests for GEIS v2.0 Input Device Module.
+ */
+#include <check.h>
+
+#include <geis/geis.h>
+
+/* Compile-time test to ensure types are defined */
+START_TEST(geis_device_types)
+{
+  GeisEventType      type;
+}
+END_TEST
+
+/* Compile-and-link-time test to verify required functions exist */
+START_TEST(geis_device_functions)
+{
+  Geis geis;
+  GeisEventCallback callback;
+  GeisDevice device;
+  geis_register_device_callback(geis, callback, NULL);
+
+  geis_device_ref(device);
+  geis_device_unref(device);
+  GeisString n = geis_device_name(device);
+  GeisInteger i = geis_device_id(device);
+  GeisSize s = geis_device_attr_count(device);
+  GeisAttr a = geis_device_attr(device, 0);
+}
+END_TEST
+
+
+/* boilerplate */
+Suite *
+geis2_device_suite_new()
+{
+  Suite *s = suite_create("geis2_device");
+
+  TCase *device = tcase_create("geis2_device");
+  tcase_add_test(device, geis_device_types);
+  suite_add_tcase(s, device);
+
+  return s;
+}
+
 
=== modified file 'testsuite/geis2/check_geis2_api.c'
--- testsuite/geis2/check_geis2_api.c	2010-12-20 18:06:36 +0000
+++ testsuite/geis2/check_geis2_api.c	2010-12-21 14:03:26 +0000
@@ -7,6 +7,7 @@
 extern Suite *make_version_macro_suite();
 extern Suite *geis2_general_types_suite_new();
 extern Suite *geis2_error_codes_suite_new();
+extern Suite *geis2_device_suite_new();
 extern Suite *geis2_geis_new_suite_new();
 extern Suite *geis2_config_suite_new();
 extern Suite *geis2_attr_suite_new();
@@ -29,6 +30,7 @@
   srunner_add_suite(sr, geis2_config_suite_new());
   srunner_add_suite(sr, geis2_attr_suite_new()); 
   srunner_add_suite(sr, geis2_region_suite_new()); 
+  srunner_add_suite(sr, geis2_device_suite_new()); 
   srunner_add_suite(sr, geis2_subscription_suite_new()); 
   srunner_add_suite(sr, geis2_event_suite_new()); 
 
 
=== modified file 'testsuite/libutouch-geis/Makefile.am'
--- testsuite/libutouch-geis/Makefile.am	2010-12-20 18:06:36 +0000
+++ testsuite/libutouch-geis/Makefile.am	2010-12-21 14:03:26 +0000
@@ -32,10 +32,11 @@
 
 check_geis2_internals_SOURCES = \
 	check_attr.c \
-	check_geis_private.c \
 	check_backend_multiplexor.c \
+	check_device.c \
 	check_error_reporting.c \
 	check_event_queue.c \
+	check_geis_private.c \
 	check_region.c \
 	check_subscription.c \
 	check_geis2_internals.c
 
=== added file 'testsuite/libutouch-geis/check_device.c'
--- testsuite/libutouch-geis/check_device.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_device.c	2010-12-21 14:03:26 +0000
@@ -0,0 +1,99 @@
+/**
+ * unit tests for the geis device module
+ */
+#include <check.h>
+
+#include "libutouch-geis/geis_device.h"
+
+
+/* fixtures */
+static GeisDeviceBag g_device_bag;
+static GeisString    g_device_name = "device";
+static GeisInteger   g_device_id   = 12;
+
+/* fixture setup */
+static void
+construct_bag()
+{
+  g_device_bag = geis_device_bag_new();
+}
+
+/* fixture teardown */
+static void
+destroy_bag()
+{
+  geis_device_bag_delete(g_device_bag);
+}
+
+/* verify bag construction/destruction */
+START_TEST(construct)
+{
+  GeisDeviceBag bag = geis_device_bag_new();
+  fail_unless(bag != NULL, "failed to create device bag");
+  geis_device_bag_delete(bag);
+}
+END_TEST
+
+/* verify bag insertion */
+START_TEST(insert)
+{
+  GeisDevice device = geis_device_new(g_device_name, g_device_id);
+  geis_device_bag_insert(g_device_bag, device);
+  fail_unless(geis_device_bag_count(g_device_bag) == 1,
+              "unexpected bag size after insertion");
+}
+END_TEST
+
+/* verify bag removal */
+START_TEST(remove)
+{
+  GeisDevice device = geis_device_new(g_device_name, g_device_id);
+  geis_device_bag_insert(g_device_bag, device);
+  fail_unless(geis_device_bag_count(g_device_bag) == 1,
+              "unexpected bag size after insertion");
+  geis_device_bag_remove(g_device_bag, device);
+  fail_unless(geis_device_bag_count(g_device_bag) == 0,
+              "unexpected bag size after removal");
+}
+END_TEST
+
+START_TEST(expand)
+{
+  int i;
+  for (i = 0; i < 24; ++i)
+  {
+    GeisSize count;
+    char name[32];
+    sprintf(name, "%04d", i);
+    GeisDevice device = geis_device_new(name, i);
+    geis_device_bag_insert(g_device_bag, device);
+    count = geis_device_bag_count(g_device_bag);
+    fail_unless(count == (i+1),
+                "unexpected bag size %ld after insertion, expected %d",
+                count, i+1);
+  }
+}
+END_TEST
+
+
+
+/* boilerplate */
+Suite *
+make_device_suite()
+{
+  Suite *s = suite_create("utouch-geis2-device");
+
+  TCase *create = tcase_create("device-bag-creation");
+  tcase_add_test(create, construct);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("device-bag-usage");
+  tcase_add_checked_fixture(usage, construct_bag, destroy_bag);
+  tcase_add_test(usage, insert);
+  tcase_add_test(usage, remove);
+  tcase_add_test(usage, expand);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+
 
=== modified file 'testsuite/libutouch-geis/check_geis2_internals.c'
--- testsuite/libutouch-geis/check_geis2_internals.c	2010-12-17 02:56:43 +0000
+++ testsuite/libutouch-geis/check_geis2_internals.c	2010-12-21 14:03:26 +0000
@@ -8,6 +8,7 @@
 extern Suite *make_attr_suite();
 extern Suite *make_backend_event_posting_suite();
 extern Suite *make_backend_multiplexor_suite();
+extern Suite *make_device_suite();
 extern Suite *make_error_reporting_suite();
 extern Suite *make_event_queue_suite();
 extern Suite *make_region_suite();
@@ -27,6 +28,7 @@
   srunner_add_suite(sr, make_event_queue_suite());
   srunner_add_suite(sr, make_backend_multiplexor_suite());
   srunner_add_suite(sr, make_backend_event_posting_suite());
+  srunner_add_suite(sr, make_device_suite());
   srunner_add_suite(sr, make_region_suite());
   srunner_add_suite(sr, make_subscription_suite());