doc/location-manager-doc.h

   1 /*
   2  * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__
  19 #define __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__
  20
  21 /**
  22  * @ingroup CAPI_LOCATION_FRAMEWORK
  23  * @defgroup CAPI_LOCATION_MANAGER_MODULE Location Manager
  24  * @brief This Location Manager API provides functions for obtaining information related to geographical location.
  25  * This API provides functions to acquire information related to the current position. Notifications on events like service becoming
  26  * enabled or disabled, new position data being available and others can also be acquired.
  27  *
  28  * @section CAPI_LOCATION_MANAGER_MODULE_HEADER Required Header
  29  *   \#include <locations.h>
  30  *
  31  * @section CAPI_LOCATION_MANAGER_MODULE_OVERVIEW Overview
  32  * The Location Manager API provides functions to acquire information about geographical location, including both as accurate a current position as possible,
  33  *  and receiving notification of changes in position, crossing boundary "fences", and velocity changes detected by the device.
  34  *
  35  * The related Geolocation API can be used to convert the location to a physical address.
  36  *
  37  * Notifications can be received about the following events:
  38  * - Change in service status (enabled / disabled)
  39  * - New position and velocity information becoming available
  40  * - Given area being entered or left (geofencing)
  41  *
  42  * Information on GPS satellites is provided by the GPS Status & Satellite API.
  43  *
  44  * The main component of the Location Service is the location manager. A location manager serves as a gateway so the application does not have
  45  * to manage the details of the back-end connection, which might be GPS, WiFi or others, although it may instruct the location manager
  46  * as to a preference. The location manager also manages the callback functions which it invokes when a given event takes place.
  47  *
  48  * The location manager has the following properties:
  49  * - Method
  50  * - Boundary
  51  * - 'Position updated' callback
  52  * - 'Service state change' callback
  53  * - 'Velocity updated' callback
  54  * - 'Boundary event' callback
  55  *
  56  * The method property of a location manager (#location_method_e) determines the source of location information. It can be set only
  57  * once - when the location manager is instantiated. The method can be one specific location method, or hybrid.
  58  *
  59  * A location manager set to the hybrid method will automatically choose
  60  * the best method available at the moment, choosing between GPS, WPS
  61  * and WPS. Note that the method may change any time, due to signals
  62  * coming in/out of range, and so on. If more than one method is available,
  63  * priorities are as follows:
  64  *
  65  * 1. GPS\n
  66  * 2. WPS\n
  67  *
  68  * If no methods are available, the service state is changed to disabled
  69  * and the appropriate callback is called. See location_manager_set_service_state_changed_cb() and location_service_state_changed_cb().
  70  *
  71  * The boundary property describes a border enclosing an area. The area
  72  * can be circular - defined by its center in geographic coordinates a radius, or rectangular - defined by the geographic coordinates of its
  73  * top left and bottom right corner.
  74  * The location manager will use the selected method to track if the area has been entered or exited.
  75  * The location manager will send asynchronous notifications by invoking
  76  * previously registered callback functions on such change events.
  77  *
  78  * There may be multiple location managers. Callback functions to receive
  79  * notifications are registered to a specific location manager, not to the location service as a whole.
  80  * So it is, for example, possible to define several different geographic areas or fences, using different location methods,
  81  * each being tracked by a different location manager and leading to distinct callbacks.
  82  *
  83  * Setting and unsetting callbacks for the manager can be done at any time, however before callbacks set for a given location manager can
  84  * be invoked, the location service must be started for that location manager. This constraint holds for managers with GPS, WPS and
  85  * Hybrid methods. See the Location manager life cycle section below. Note the start/stop functions apply only to
  86  * the individual location manager and do not affect any other location managers that may be running.
  87  *
  88  * Only one callback can be set for a given event within the scope of a single location manager. Successive callback setting will result in
  89  * the new callback replacing the old one. If an 'unset callback' function is called when there is no callback set, no error is returned.
  90  * Callbacks can be set and unset any number of times.
  91  *
  92  * @subsection CAPI_LOCATION_MANAGER_MODULE_MANAGER_LIFECYCLE Location manager life cycle
  93  *
  94  * 1. Create location manager ( location_manager_create() )\n
  95  * 2. Set callbacks and other required information\n
  96  * 3. Start service with location_manager_start()\n
  97  * 4. Wait until state change callback ( location_service_state_changed_cb() ) is called with #LOCATIONS_SERVICE_ENABLED as first argument\n
  98  * 5. Other callbacks are working now, wait for events and process\n
  99  * 6. Stop service with location_manager_stop()\n
 100  * 7. Wait until state change callback ( location_service_state_changed_cb() ) is called with #LOCATIONS_SERVICE_DISABLED as first argument\n
 101  * 8. Destroy location manager (location_manager_destroy())\n
 102  *
 103  * After stopping the location service for a given location manager,
 104  * the location manager can still be used. So some functions can be called if they do not require a location service running on your device.
 105  * The location service can be re-started later.
 106  *
 107  * If a location manager is no longer needed and is going to be destroyed, it is not mandatory to call location_manager_stop(),
 108  * as location_manager_destroy() will call it automatically.
 109  *
 110  * Note that after a location manager has been destroyed, the handle (#location_manager_h) can be reused - location_manager_create() can
 111  * be called again for this handle. In other words, the state before creation and after destruction can be treated as the same state.
 112  *
 113  * @section CAPI_LOCATION_MANAGER_MODULE_FEATURE Related Features
 114  * This API is related with the following features:\n
 115  *      - http://tizen.org/feature/location\n
 116  *      - http://tizen.org/feature/location.gps\n
 117  *      - http://tizen.org/feature/location.wps\n
 118  *
 119  * It is recommended to design feature related codes in your application for reliability.\n
 120  *
 121  * You can check if a devrice supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 122  *
 123  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
 124  *
 125  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 126  *
 127  */
 128
 129 /**
 130 * @ingroup CAPI_LOCATION_MANAGER_MODULE
 131 * @defgroup CAPI_LOCATION_GPS_STATUS_MODULE GPS Status & Satellite
 132 * @brief The GPS Status & Satellite API provides functions to acquire information about GPS satellites in range and in use.
 133 *
 134 * @section CAPI_LOCATION_GPS_STATUS_MODULE_HEADER Required Header
 135 *   \#include <locations.h>
 136 *
 137 * @section CAPI_LOCATION_GPS_STATUS_MODULE_OVERVIEW Overview
 138 *  The GPS Status & Satellite API provides functions to acquire data on satellites that are currently visible to the device. Information
 139 *  like azimuth and elevation of each satellite is available, along with number of satellites in range and in use.
 140 *
 141 * @par System Info note:
 142 * All of the functions require a started location manager with the #LOCATIONS_METHOD_GPS method set. See the Location Manager API for details.
 143 *
 144 * The gps_status_get_nmea() function gets NMEA data from the GPS system.  NMEA 0183 (or NMEA for short) is a combined electrical and data
 145 * specification for communication between electronic devices. NMEA standard uses a simple ASCII, serial communications protocol that
 146 * defines how data is transmitted in a "sentence" from one "talker"  to multiple "listeners" at a time. For more details, see <a href = "http://en.wikipedia.org/wiki/NMEA_0183">NMEA_0183</a>.
 147 *
 148 * The gps_status_get_satellite() method returns a count of satellites in view. The gps_status_foreach_satellites_in_view() method is an
 149 * iterator which will invoke a callback function for each satellite in view. The  gps_status_get_satellite() method returns a count of
 150 * satellites in use.
 151 *
 152  * @section CAPI_LOCATION_GPS_STATUS_MODULE_FEATURE Related Features
 153  * This API is related with the following features:\n
 154  *      - http://tizen.org/feature/location\n
 155  *      - http://tizen.org/feature/location.gps\n
 156  *      - http://tizen.org/feature/location.gps.satellite\n
 157  *
 158  * It is recommended to design feature related codes in your application for reliability.\n
 159  *
 160  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 161  *
 162  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
 163  *
 164  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 165  *
 166 */
 167
 168 /**
 169  * @ingroup CAPI_LOCATION_MANAGER_MODULE
 170  * @defgroup CAPI_LOCATION_BOUNDS_MODULE Location Bounds
 171  * @brief The Location Bounds APIs provides functions related to geographic bounds information.
 172  *
 173  *
 174  * @section CAPI_LOCATION_BOUNDS_MODULE_HEADER Required Header
 175  *   \#include <locations.h>
 176  *
 177  * @section CAPI_LOCATION_BOUNDS_MODULE_OVERVIEW Overview
 178  *
 179  * Boundary defines geographical boundary. It is same as geo-fence which is a virtual perimeter for a real-world geographic area.
 180  * If you create a boundary, you can trigger some activities when a device enters(or exits) the boundaries defined by you.
 181  *
 182  * @section CAPI_LOCATION_BOUNDS_MODULE_FEATURE Related Features
 183  * This API is related with the following features:\n
 184  *      - http://tizen.org/feature/location\n
 185  *      - http://tizen.org/feature/location.gps\n
 186  *      - http://tizen.org/feature/location.wps\n
 187  *
 188  * It is recommended to design feature related codes in your application for reliability.\n
 189  *
 190  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 191  *
 192  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
 193  *
 194  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 195  *
 196  */
 197
 198 /**
 199  * @internal
 200  * @{
 201  * @ingroup CAPI_LOCATION_FRAMEWORK
 202  * @defgroup CAPI_LOCATION_PREF_MODULE Location Preference
 203  * @brief The Location Preference APIs provides functions related to Maps
 204  * Service.
 205  *
 206  *
 207  * @section CAPI_LOCATION_PREF_MODULE_HEADER Required Header
 208  *   \#include <location_preference_product.h>
 209  *
 210  * @section CAPI_LOCATION_PREF_MODULE_OVERVIEW Overview
 211  *
 212  * You can set some options with Location Preference when you use Maps Service(geocoder, poi, and route) module.
 213  *
 214  * @section CAPI_LOCATION_PREF_MODULE_FEATURE Related Features
 215  * This API is related with the following features:\n
 216  *      - http://tizen.org/feature/location\n
 217  *
 218  * It is recommended to design feature related codes in your application for reliability.\n
 219  *
 220  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 221  *
 222  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
 223  *
 224  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 225  * @}
 226  *
 227  */
 228
 229 #endif  /* __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__ */