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.
28 * @section CAPI_LOCATION_MANAGER_MODULE_HEADER Required Header
29 * \#include <locations.h>
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.
35 * The related Geolocation API can be used to convert the location to a physical address.
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)
42 * Information on GPS satellites is provided by the GPS Status & Satellite API.
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.
48 * The location manager has the following properties:
51 * - 'Position updated' callback
52 * - 'Service state change' callback
53 * - 'Velocity updated' callback
54 * - 'Boundary event' callback
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.
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:
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().
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.
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.
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.
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.
92 * @subsection CAPI_LOCATION_MANAGER_MODULE_MANAGER_LIFECYCLE Location manager life cycle
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
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.
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.
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.
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
119 * It is recommended to design feature related codes in your application for reliability.\n
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
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
125 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
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.
134 * @section CAPI_LOCATION_GPS_STATUS_MODULE_HEADER Required Header
135 * \#include <locations.h>
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.
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.
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>.
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 satellites in use.
151 * @section CAPI_LOCATION_GPS_STATUS_MODULE_FEATURE Related Features
152 * This API is related with the following features:\n
153 * - http://tizen.org/feature/location\n
154 * - http://tizen.org/feature/location.gps\n
155 * - http://tizen.org/feature/location.gps.satellite\n
157 * It is recommended to design feature related codes in your application for reliability.\n
159 * 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 * 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 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
168 * @ingroup CAPI_LOCATION_MANAGER_MODULE
169 * @defgroup CAPI_LOCATION_BOUNDS_MODULE Location Bounds
170 * @brief The Location Bounds APIs provides functions related to geographic bounds information.
173 * @section CAPI_LOCATION_BOUNDS_MODULE_HEADER Required Header
174 * \#include <locations.h>
176 * @section CAPI_LOCATION_BOUNDS_MODULE_OVERVIEW Overview
178 * Boundary defines geographical boundary. It is same as geo-fence which is a virtual perimeter for a real-world geographic area.
179 * If you create a boundary, you can trigger some activities when a device enters(or exits) the boundaries defined by you.
181 * @section CAPI_LOCATION_BOUNDS_MODULE_FEATURE Related Features
182 * This API is related with the following features:\n
183 * - http://tizen.org/feature/location\n
184 * - http://tizen.org/feature/location.gps\n
185 * - http://tizen.org/feature/location.wps\n
187 * It is recommended to design feature related codes in your application for reliability.\n
189 * 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 * 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 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
200 * @ingroup CAPI_LOCATION_FRAMEWORK
201 * @defgroup CAPI_LOCATION_PREF_MODULE Location Preference
202 * @brief The Location Preference APIs provides functions related to Maps
206 * @section CAPI_LOCATION_PREF_MODULE_HEADER Required Header
207 * \#include <location_preference_product.h>
209 * @section CAPI_LOCATION_PREF_MODULE_OVERVIEW Overview
211 * You can set some options with Location Preference when you use Maps Service(geocoder, poi, and route) module.
213 * @section CAPI_LOCATION_PREF_MODULE_FEATURE Related Features
214 * This API is related with the following features:\n
215 * - http://tizen.org/feature/location\n
217 * It is recommended to design feature related codes in your application for reliability.\n
219 * 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 * 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 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
228 #endif /* __TIZEN_LOCATION_LOCATION_MANAGER_DOC_H__ */