2 * Copyright (c) 2011-2013 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__
19 #define __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__
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>
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:
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:
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.
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.
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
100 * It is recommended to design feature related codes in your application for reliability.\n
101 * 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
102 * 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
103 * 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>
108 * @ingroup CAPI_LOCATION_MANAGER_MODULE
109 * @defgroup CAPI_LOCATION_GPS_STATUS_MODULE GPS Status & Satellite
110 * @brief The GPS Status & Satellite API provides functions to acquire information about GPS satellites in range and in use.
111 * @section CAPI_LOCATION_GPS_STATUS_MODULE_HEADER Required Header
112 * \#include <locations.h>
114 * @section CAPI_LOCATION_GPS_STATUS_MODULE_OVERVIEW Overview
115 * The GPS Status & Satellite API provides functions to acquire data on satellites that are currently visible to the device.
116 * Information like azimuth and elevation of each satellite is available, along with number of satellites in range and in use.
118 * @par System Info note:
119 * All of the functions require a started location manager with the #LOCATIONS_METHOD_GPS method set. See the Location Manager API for details.
120 * 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
121 * specification for communication between electronic devices. NMEA standard uses a simple ASCII, serial communications protocol that
122 * 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>.
123 * The gps_status_get_satellite() method returns a count of satellites in view. The gps_status_foreach_satellites_in_view() method is an
124 * 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.
126 * @section CAPI_LOCATION_GPS_STATUS_MODULE_FEATURE Related Features
127 * This API is related with the following features:\n
128 * - %http://tizen.org/feature/location\n
129 * - %http://tizen.org/feature/location.gps\n
130 * - %http://tizen.org/feature/location.gps.satellite\n
132 * It is recommended to design feature related codes in your application for reliability.\n
133 * 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
134 * 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
135 * 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>
140 * @ingroup CAPI_LOCATION_MANAGER_MODULE
141 * @defgroup CAPI_LOCATION_BOUNDS_MODULE Location Bounds
142 * @brief The Location Bounds APIs provides functions related to geographic bounds information.
143 * @section CAPI_LOCATION_BOUNDS_MODULE_HEADER Required Header
144 * \#include <locations.h>
146 * @section CAPI_LOCATION_BOUNDS_MODULE_OVERVIEW Overview
147 * Boundary defines geographical boundary. It is same as geo-fence which is a virtual perimeter for a real-world geographic area.
148 * If you create a boundary, you can trigger some activities when a device enters(or exits) the boundaries defined by you.
150 * @section CAPI_LOCATION_BOUNDS_MODULE_FEATURE Related Features
151 * This API is related with the following features:\n
152 * - %http://tizen.org/feature/location\n
153 * - %http://tizen.org/feature/location.gps\n
154 * - %http://tizen.org/feature/location.wps\n
156 * It is recommended to design feature related codes in your application for reliability.\n
157 * 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
158 * 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
159 * 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>
166 * @ingroup CAPI_LOCATION_FRAMEWORK
167 * @defgroup CAPI_LOCATION_PREF_MODULE Location Preference
168 * @brief The Location Preference APIs provides functions related to Maps Service.
169 * @section CAPI_LOCATION_PREF_MODULE_HEADER Required Header
170 * \#include <location_preference_product.h>
172 * @section CAPI_LOCATION_PREF_MODULE_OVERVIEW Overview
173 * You can set some options with Location Preference when you use Maps Service(geocoder, poi, and route) module.
175 * @section CAPI_LOCATION_PREF_MODULE_FEATURE Related Features
176 * This API is related with the following features:\n
177 * - %http://tizen.org/feature/location\n
179 * It is recommended to design feature related codes in your application for reliability.\n
180 * 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
181 * 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
182 * 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>
186 #endif /* __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__ */