/**
 * @page telldus_core Telldus Core API
 *
 * \section Introduction
 *
 * This is the guide to Telldus TellStick SDK. Even though all examples are
 * written in C/C++ most of the code has an direct eqvivalent function in the
 * other languages. See \ref sec_other_languages how to use the library in one
 * of the supported languages by Telldus.
 *
 * \section Idea
 * 
 * All of the devices used by TellStick must be predefined before they can be
 * used in any software. Under all platforms this can be done with the
 * software TelldusSetup but under Linux this can also be done by editing the
 * file <tt>/etc/tellstick.conf</tt> with your favorite text editor.
 *
 * Having the devices preconfigured is an advantage to both the developer and
 * the end user.
 *
 * \li The end user might use more then one program for controling his/hers
 * TellStick. By having the devices preconfigured he/she doesn't have to
 * reconfigure the same devices twice. If some settings changes in one of the
 * devices, this change will affect all softwares using Telldus TellStick SDK.
 * \li Telldus is adding support for new devices constantly. If every software
 * defines it's own devices it will also mean that the developer has to keep
 * it's software up to date with all the new devices and settings Telldus
 * implements. By querying Telldus Tellstick SDK all the new devices will be
 * available automaticly to the end user.
 *
 * \section sec_basic_usage Basic usage (telldus-core)
 * 
 * Telldus provides a non-gui library to list, query and control the devices
 * called telldus-core.
 * To initiate the library a call to tdInit() must be made. This call will
 * open up all controllers (e.g. a TellStick) and start listen for events from
 * them.
 * When you are done with telldus-core, call tdClose() to allow the library to
 * clean up after itself.
 *
 * \subsection sec_bu_listing Listing devices
 *
 * To list all of the configured devices, look at the following example:
 * \code
 * int intNumberOfDevices = tdGetNumberOfDevices();
 * for (int i = 0; i < intNumberOfDevices; i++) {
 *   int id = tdGetDeviceId( index );
 *   char *name = tdGetName( id );
 *   printf("%d\t%s\n", id, name);
 *   free(name);
 * }
 * \endcode
 *
 * First, we call tdGetNumberOfDevices(). This returnes the total number of
 * devices configured. We then iterate over all of the devices with the index
 * in the variable \c i.
 * Since the devices could change between run of the program we could not be
 * sure that the index points to the same device between two run of the
 * program. That is why every device has an own unique id that is safe to
 * store in a configuration file. Two different devices could never share the
 * same device id.
 *
 * The call to tdGetDeviceId() returns the id for a specific index. This
 * function should only be called in a loop iterating over all of the devices.
 * After we have found the id for a device it is safe to store this or use it
 * the rest of the program.
 *
 * The next two lines of code queries the device for it's name with a call to
 * tdGetName() and then displays it to stdout. Since telldus-core gives up the
 * ownership of the string we must manualy free up the resource after we are
 * done with it. 
 *
 * \subsection sec_bu_sending Sending commands to TellStick
 *
 * \subsubsection sec_bu_sending_features Device features
 *
 * TellStick can control many different types of devices and they
 * all support different features. For example, a bell doesn't support turning
 * on and not all lamp switches support dimming.
 * To find out what a specific device support call tdMethods():
 * \code
 * function checkFeatures( int id ) {
 *   int methods = tdMethods( id );
 *   if ( methods & TELLSTICK_TURNON ) {
 *     printf( "The device %d support tdTurnOn()\n", id );
 *   }
 *   if ( methods & TELLSTICK_TURNOFF ) {
 *     printf( "The device %d support tdTurnOff()\n", id );
 *   }
 *   if ( methods & TELLSTICK_BELL ) {
 *     printf( "The device %d support tdBell()\n", id );
 *   }
 * }
 * \endcode
 * 
 * When you know which fetures a device support it is safe to call the
 * controlling functions described in \ref sec_bu_controlling_functions.
 *
 * \subsubsection sec_bu_controlling_functions Controlling functions
 *
 * TellStick has a couple of functions for controlling the devices. Each of
 * them should only be called if the device support the feature.
 *
 * These functions all returns zero if the call was successfull and non-zero
 * otherwise.
 *
 * \paragraph tdTurnOn tdTurnOn()
 * Devices supporting \c TELLSTICK_TURNON. Most of the normal switches (for lamp
 * etc.) support this.
 * \paragraph tdTurnOff tdTurnOff()
 * Devices supporting \c TELLSTICK_TURNOFF. Almost all of the devices supporting
 * \c TELLSTICK_TURNON also support this.
 * \paragraph tdDim tdDim()
 * Devices supporting \c TELLSTICK_DIM. This is a quite unusual feature for
 * dimmers. Many dimmers on the market that are dimmable have no way for sending
 * a specific level which means it doesn't support this feature.
 * \paragraph tdBell tdBell()
 * Devices supporting \c TELLSTICK_BELL. This is mostly wireless doorbells.
 *
 * \subsubsection sec_bu_error_codes Error codes
 * 
 * If any of the calls in \ref sec_bu_controlling_functions fails it returns
 * a non-zero error code. This values is one of the \c TELLSTICK_ERROR_* defines.
 * To translate the error code to a human readable string call the function
 * tdGetErrorString(). Example:
 * \code
 * printf("Error: %s\n", tdGetErrorString( TELLSTICK_METHOD_NOT_SUPPORTED ) );
 * //Error: The method you tried to use is not supported by the device
 *
 * int retval = tdTurnOn( deviceID );
 * if (retval != TELLSTICK_SUCCESS ) {
 *   printf("Error: %s\n", tdGetErrorString( retval ) );
 * }
 * \endcode
 *
 * \section sec_other_languages Notes using other languages than C/C++
 *
 * \subsection sec_ol_java Java
 * \subsection sec_ol_net .Net
 * \subsection sec_ol_php PHP
 * \subsection sec_ol_pyhon Python
 *
 * There is no native Python support for TellStick yet. If you are developing in
 * Windows you can load the TellStick ActiveX and then access the Telldus
 * TellStick SDK.
 *
 * \subsection sec_ol_visualbasic Visual Basic
 * 
 * Include the file \c TellStick.bas to your project and all of the functions
 * will be available.
 */