From f7be6f0e53ec8167c2d9f6bf86cb99813169b4ae Mon Sep 17 00:00:00 2001 From: Micke Prag Date: Tue, 11 May 2010 13:55:35 +0000 Subject: [PATCH] Updated documentation by adding the section about events. Especially for TellStick Duo --- docs/telldus-core.dox | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/telldus-core.dox b/docs/telldus-core.dox index 335a477f..aa7ef668 100644 --- a/docs/telldus-core.dox +++ b/docs/telldus-core.dox @@ -186,6 +186,73 @@ * tdReleaseString(name); * \endcode * + * \section sec_events Events + * + * To get events from either a TellStick Duo or if another software changes the + * status of a device you have to register for a callback. + * + * \subsection sec_events_registering Registering for callbacks + * + * For each callback there is a corresponding register function: + * \li tdRegisterDeviceEvent() + * \li tdRegisterDeviceChangeEvent() + * \li tdRegisterRawDeviceEvent() + * + * These all work in the same way. The first parameter is a function-pointer to + * the callback function. The second parameter is an optional void pointer. This + * can be anything and is dependent on the implementation. This object will be + * sent back to each call to the callback function. The functions return an + * integer which is an id to the specific callback. This is is sent as a + * parameter in each call and should also be used for unregister the callback. + * + * Please note that the callback will be called by another thread than the + * thread used by the application and some measures must be taken to synchronize + * it with the main thread. + * + * \subsection sec_events_callbacks Callbacks + * + * telldus-core currently implements three different callback function for + * different purposes. + * + * \subsubsection sec_events_callbacks_deviceevent DeviceEvent + * + * This event is fired when the state of a device changes. This can either + * occur via a remote control, but can as well occur via another software on the + * computer. + * + * Parameters: + * - int deviceId - The device id of the device that changed. + * - int method - The new state. Can be TELLSTICK_TURNON, TELLSTICK_TURNOFF + * etc. + * - const char *data - For some methods this contains data. For TELLSTICK_DIM + * this hold the current value. + * + * \subsubsection sec_events_callbacks_devicechangeevent DeviceChangeEvent + * This event is fired when the data around a device is changed. It can only be + * triggered by another software. Use this callback to keep your list of devices + * in sync. + * + * Parameters: + * - int deviceId - The device id of the device that changed. + * - int changeEvent - What was changed. This can be: + * - TELLSTICK_DEVICE_ADDED - A new device was added. The parameter deviceId + * holds the id of the new device. + * - TELLSTICK_DEVICE_REMOVED - A device was removed, the parameter deviceId + * holds the id of the removed device. + * - TELLSTICK_DEVICE_CHANGED - The settings of a device changed. The next + * parameter holds what was changed. + * - int changeType - If changeEvent is TELLSTICK_DEVICE_CHANGED this parameter + * holds what was changed. It can be one of the following: + * - TELLSTICK_CHANGE_NAME - Use tdGetName() to read the new name. + * - TELLSTICK_CHANGE_PROTOCOL - Use tdGetProtocol() to read the new value. + * - TELLSTICK_CHANGE_MODEL - Use tdGetModel() to read the new value. + * + * \subsubsection sec_events_callbacks_rawdeviceevent RawDeviceEvent + * + * Use this callback with caution. It outputs everything from the Duo without + * any preprocessing. This can be used to get events from devices not already + * configured. + * * \section sec_other_languages Notes using other languages than C/C++ * * \subsection sec_ol_pyhon Python