summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPeter Hutterer <peter@cs.unisa.edu.au>2007-06-19 15:31:56 +0930
committerPeter Hutterer <peter@cs.unisa.edu.au>2007-06-25 09:35:30 +0930
commit24ee89fd60f489f2d3af0399e0d667057df74d02 (patch)
tree7c40e32f52df4a9297f7e355558c8d74851950c8
parent93ca526892c0d22afa05cce6496198c652043a19 (diff)
Add a few comments to devices.c
-rw-r--r--dix/devices.c76
1 files changed, 76 insertions, 0 deletions
diff --git a/dix/devices.c b/dix/devices.c
index 6c694547b..57e93bb4b 100644
--- a/dix/devices.c
+++ b/dix/devices.c
@@ -80,9 +80,20 @@ SOFTWARE.
#include "exglobals.h"
#include "exevents.h"
+/** @file
+ * This file handles input device-related stuff.
+ */
+
int CoreDevicePrivatesIndex = 0;
static int CoreDevicePrivatesGeneration = -1;
+/**
+ * Create a new input device and init it to sane values. The device is added
+ * to the server's off_devices list.
+ *
+ * @param deviceProc Callback for device control function (switch dev on/off).
+ * @return The newly created device.
+ */
DeviceIntPtr
AddInputDevice(DeviceProc deviceProc, Bool autoStart)
{
@@ -153,6 +164,15 @@ AddInputDevice(DeviceProc deviceProc, Bool autoStart)
return dev;
}
+/**
+ * Switch device ON through the driver and push it onto the global device
+ * list. All clients are notified about the device being enabled.
+ *
+ * A device will send events once enabled.
+ *
+ * @param The device to be enabled.
+ * @return TRUE on success or FALSE otherwise.
+ */
Bool
EnableDevice(DeviceIntPtr dev)
{
@@ -189,6 +209,13 @@ EnableDevice(DeviceIntPtr dev)
return TRUE;
}
+/**
+ * Switch a device off through the driver and push it onto the off_devices
+ * list. A device will not send events while disabled. All clients are
+ * notified about the device being disabled.
+ *
+ * @return TRUE on success or FALSE otherwise.
+ */
Bool
DisableDevice(DeviceIntPtr dev)
{
@@ -219,6 +246,14 @@ DisableDevice(DeviceIntPtr dev)
return TRUE;
}
+/**
+ * Initialise a new device through the driver and tell all clients about the
+ * new device.
+ *
+ * The device will NOT send events until it is enabled!
+ *
+ * @return Success or an error code on failure.
+ */
int
ActivateDevice(DeviceIntPtr dev)
{
@@ -243,6 +278,10 @@ ActivateDevice(DeviceIntPtr dev)
return ret;
}
+/**
+ * Ring the bell.
+ * The actual task of ringing the bell is the job of the DDX.
+ */
static void
CoreKeyboardBell(int volume, DeviceIntPtr pDev, pointer arg, int something)
{
@@ -257,6 +296,9 @@ CoreKeyboardCtl(DeviceIntPtr pDev, KeybdCtrl *ctrl)
return;
}
+/**
+ * Device control function for the Virtual Core Keyboard.
+ */
static int
CoreKeyboardProc(DeviceIntPtr pDev, int what)
{
@@ -317,6 +359,9 @@ CoreKeyboardProc(DeviceIntPtr pDev, int what)
return Success;
}
+/**
+ * Device control function for the Virtual Core Pointer.
+ */
static int
CorePointerProc(DeviceIntPtr pDev, int what)
{
@@ -347,6 +392,12 @@ CorePointerProc(DeviceIntPtr pDev, int what)
return Success;
}
+/**
+ * Initialise the two core devices, VCP and VCK (see events.c).
+ * The devices are activated but not enabled.
+ * Note that the server MUST have two core devices at all times, even if there
+ * is no physical device connected.
+ */
void
InitCoreDevices(void)
{
@@ -406,6 +457,14 @@ InitCoreDevices(void)
}
}
+/**
+ * Activate all switched-off devices and then enable all those devices.
+ *
+ * Will return an error if no core keyboard or core pointer is present.
+ * In theory this should never happen if you call InitCoreDevices() first.
+ *
+ * @return Success or error code on failure.
+ */
int
InitAndStartDevices(void)
{
@@ -441,6 +500,13 @@ InitAndStartDevices(void)
return Success;
}
+/**
+ * Close down a device and free all resources.
+ * Once closed down, the driver will probably not expect you that you'll ever
+ * enable it again and free associated structs. If you want the device to just
+ * be disabled, DisableDevice().
+ * Don't call this function directly, use RemoveDevice() instead.
+ */
static void
CloseDevice(DeviceIntPtr dev)
{
@@ -542,6 +608,10 @@ CloseDevice(DeviceIntPtr dev)
xfree(dev);
}
+/**
+ * Shut down all devices, free all resources, etc.
+ * Only useful if you're shutting down the server!
+ */
void
CloseDownDevices(void)
{
@@ -563,6 +633,12 @@ CloseDownDevices(void)
inputInfo.pointer = NULL;
}
+/**
+ * Remove a device from the device list, closes it and thus frees all
+ * resources.
+ * Removes both enabled and disabled devices and notifies all devices about
+ * the removal of the device.
+ */
int
RemoveDevice(DeviceIntPtr dev)
{