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  * @section CAPI_LOCATION_MANAGER_MODULE_HEADER Required Header
  28  *   \#include <locations.h>
  29  *
  30  * @section CAPI_LOCATION_MANAGER_MODULE_OVERVIEW Overview
  31  * The Location Manager API provides functions to acquire information about geographical location, including both as accurate a current position as possible,
  32  * and receiving notification of changes in position, crossing boundary "fences", and velocity changes detected by the device.
  33  * The related Geolocation API can be used to convert the location to a physical address.
  34  * Notifications can be received about the following events:
  35  * - Change in service status (enabled / disabled)
  36  * - New position and velocity information becoming available
  37  * - Given area being entered or left (geofencing)
  38  * Information on GPS satellites is provided by the GPS Status & Satellite API.
  39  * The main component of the Location Service is the location manager. A location manager serves as a gateway, so the application does not have
  40  * to manage the details of the back-end connection, which might be GPS, WiFi or others, although it may instruct the location manager
  41  * as to a preference. The location manager also manages the callback functions which it invokes when a given event takes place.
  42  * The location manager has the following properties:
  43  * - Method
  44  * - Boundary
  45  * - 'Position updated' callback
  46  * - 'Service state change' callback
  47  * - 'Velocity updated' callback
  48  * - 'Boundary event' callback
  49  * The method property of a location manager (#location_method_e) determines the source of location information. It can be set only
  50  * once - when the location manager is instantiated. The method can be one specific location method, or hybrid.
  51  * A location manager set to the hybrid method will automatically choose
  52  * the best method available at the moment, choosing between GPS, WPS
  53  * and WPS. Note that the method may change any time, due to signals
  54  * coming in/out of range, and so on. If more than one method is available,
  55  * priorities are as follows:
  56  * 1. GPS\n
  57  * 2. WPS\n
  58  * If no methods are available, the service state is changed to disabled and the appropriate callback is called.
  59  * See location_manager_set_service_state_changed_cb() and location_service_state_changed_cb().
  60  * The boundary property describes a border enclosing an area.
  61  * The area can be circular - defined by its center in geographic coordinates a radius, or rectangular - defined by the geographic coordinates of its
  62  * top-left and bottom-right corner.
  63  * The location manager will use the selected method to track if the area has been entered or exited.
  64  * The location manager will send asynchronous notifications by invoking previously registered callback functions on such change events.
  65  * There may be multiple location managers. Callback functions to receive
  66  * notifications are registered to a specific location manager, not to the location service as a whole.
  67  * So it is, for example, possible to define several different geographic areas or fences, using different location methods,
  68  * each being tracked by a different location manager and leading to distinct callbacks.
  69  * Setting and unsetting callbacks for the manager can be done at any time, however before callbacks set for a given location manager can
  70  * be invoked, the location service must be started for that location manager. This constraint holds for managers with GPS, WPS, and
  71  * Hybrid methods. See the Location manager life cycle section below. Note the start/stop functions apply only to
  72  * the individual location manager and do not affect any other location managers that may be running.
  73  * Only one callback can be set for a given event within the scope of a single location manager. Successive callback setting will result in
  74  * the new callback replacing the old one. If an 'unset callback' function is called when there is no callback set, no error is returned.
  75  * Callbacks can be set and unset any number of times.
  76  *
  77  * @subsection CAPI_LOCATION_MANAGER_MODULE_MANAGER_LIFECYCLE Location manager life cycle
  78  * 1. Create location manager ( location_manager_create() )\n
  79  * 2. Set callbacks and other required information\n
  80  * 3. Start service with location_manager_start()\n
  81  * 4. Wait until state change callback ( location_service_state_changed_cb() ) is called with #LOCATIONS_SERVICE_ENABLED as first argument\n
  82  * 5. Other callbacks are working now, wait for events and process\n
  83  * 6. Stop service with location_manager_stop()\n
  84  * 7. Wait until state change callback ( location_service_state_changed_cb() ) is called with #LOCATIONS_SERVICE_DISABLED as first argument\n
  85  * 8. Destroy location manager ( location_manager_destroy() )\n
  86  * After stopping the location service for a given location manager,
  87  * 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.
  88  * The location service can be re-started later.
  89  * If a location manager is no longer needed and is going to be destroyed, it is not mandatory to call location_manager_stop(),
  90  * as location_manager_destroy() will call it automatically.
  91  * Note that after a location manager has been destroyed, the handle (#location_manager_h) can be reused - location_manager_create() can
  92  * be called again for this handle. In other words, the state before creation and after destruction can be treated as the same state.
  93  *
  94  * @section CAPI_LOCATION_MANAGER_MODULE_FEATURE Related Features
  95  * This API is related with the following features:\n
  96  * - http://tizen.org/feature/location\n
  97  * - http://tizen.org/feature/location.gps\n
  98  * - http://tizen.org/feature/location.wps\n
  99  * It is recommended to design feature related codes in your application for reliability.\n
 100  * 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
 101  * 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
 102  * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
 103  */
 104
 105
 106 /**
 107  * @ingroup CAPI_LOCATION_MANAGER_MODULE
 108  * @defgroup CAPI_LOCATION_GPS_STATUS_MODULE GPS Status & Satellite
 109  * @brief The GPS Status & Satellite API provides functions to acquire information about GPS satellites in range and in use.
 110  * @section CAPI_LOCATION_GPS_STATUS_MODULE_HEADER Required Header
 111  *   \#include <locations.h>
 112  *
 113  * @section CAPI_LOCATION_GPS_STATUS_MODULE_OVERVIEW Overview
 114  *  The GPS Status & Satellite API provides functions to acquire data on satellites that are currently visible to the device.
 115  *  Information like azimuth and elevation of each satellite is available, along with number of satellites in range and in use.
 116  *
 117  * @par System Info note:
 118  * All of the functions require a started location manager with the #LOCATIONS_METHOD_GPS method set. See the Location Manager API for details.
 119  * 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
 120  * specification for communication between electronic devices. NMEA standard uses a simple ASCII, serial communications protocol that
 121  * 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>.
 122  * The gps_status_get_satellite() method returns a count of satellites in view. The gps_status_foreach_satellites_in_view() method is an
 123  * iterator which will invoke a callback function for each satellite in view. The gps_status_get_satellite() method returns a count of satellites in use.
 124  *
 125  * @section CAPI_LOCATION_GPS_STATUS_MODULE_FEATURE Related Features
 126  * This API is related with the following features:\n
 127  * - http://tizen.org/feature/location\n
 128  * - http://tizen.org/feature/location.gps\n
 129  * - http://tizen.org/feature/location.gps.satellite\n
 130  * It is recommended to design feature related codes in your application for reliability.\n
 131  * 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
 132  * 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
 133  * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
 134  */
 135
 136
 137 /**
 138  * @ingroup CAPI_LOCATION_MANAGER_MODULE
 139  * @defgroup CAPI_LOCATION_BOUNDS_MODULE Location Bounds
 140  * @brief The Location Bounds APIs provides functions related to geographic bounds information.
 141  * @section CAPI_LOCATION_BOUNDS_MODULE_HEADER Required Header
 142  *   \#include <locations.h>
 143  *
 144  * @section CAPI_LOCATION_BOUNDS_MODULE_OVERVIEW Overview
 145  * Boundary defines geographical boundary. It is same as geo-fence which is a virtual perimeter for a real-world geographic area.
 146  * If you create a boundary, you can trigger some activities when a device enters(or exits) the boundaries defined by you.
 147  *
 148  * @section CAPI_LOCATION_BOUNDS_MODULE_FEATURE Related Features
 149  * This API is related with the following features:\n
 150  * - http://tizen.org/feature/location\n
 151  * - http://tizen.org/feature/location.gps\n
 152  * - http://tizen.org/feature/location.wps\n
 153  * It is recommended to design feature related codes in your application for reliability.\n
 154  * 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
 155  * 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
 156  * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
 157  */
 158
 159
 160 /**
 161  * @internal
 162  * @{
 163  * @ingroup CAPI_LOCATION_FRAMEWORK
 164  * @defgroup CAPI_LOCATION_PREF_MODULE Location Preference
 165  * @brief The Location Preference APIs provides functions related to Maps Service.
 166  * @section CAPI_LOCATION_PREF_MODULE_HEADER Required Header
 167  *   \#include <location_preference_product.h>
 168  *
 169  * @section CAPI_LOCATION_PREF_MODULE_OVERVIEW Overview
 170  * You can set some options with Location Preference when you use Maps Service(geocoder, poi, and route) module.
 171  *
 172  * @section CAPI_LOCATION_PREF_MODULE_FEATURE Related Features
 173  * This API is related with the following features:\n
 174  * - http://tizen.org/feature/location\n
 175  * It is recommended to design feature related codes in your application for reliability.\n
 176  * 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
 177  * 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
 178  * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
 179  * @}
 180  */
 181
 182 #endif  /* __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__ */