4 * Copyright (c) 2010-2013 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Youngae Kang <youngae.kang@samsung.com>, Minjune Kim <sena06.kim@samsung.com>
7 * Genie Kim <daejins.kim@samsung.com>
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
13 * http://www.apache.org/licenses/LICENSE-2.0
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
23 #ifndef __LOCATION_H__
24 #define __LOCATION_H__
28 #include <location-types.h>
29 #include <location-position.h>
30 #include <location-velocity.h>
31 #include <location-accuracy.h>
32 #include <location-address.h>
33 #include <location-boundary.h>
34 #include <location-satellite.h>
40 * @brief This file contains the Location API and related structure and enumeration.
43 * @defgroup LocationFW LocationFW
44 * @brief This is a Location Framework for providing location based services.
45 * @addtogroup LocationFW
47 * @defgroup LocationAPI Location API
48 * @brief This sub module provides the Location API.
49 * @addtogroup LocationAPI
55 * Initialize location sub module.
57 * This API should be called before any other Location APIs.
63 * Please refer #LocationError for more information.
66 int location_init (void);
70 * Create a new #LocationObject by using given #LocationMethod.
72 * Returned object is necessary for other APIs.
74 * #location_init should be called before.
77 * method - Location method to be used.
78 * @return a new #LocationObject
79 * @retval NULL if error occured
82 LocationObject *location_new (LocationMethod method);
86 * Free memory of given #LocationObject.
89 * #location_init should be called before.
92 * obj - a #LocationObject created by #location_new.
96 * Please refer #LocationError for more information.
100 #include <location.h>
101 int main (int argc, char *argv[])
103 LocationObject *loc = NULL;
105 loc = location_new (LOCATION_METHOD_GPS);
109 // ... Implement your code
112 // You must free LocationObject when you don't need to use anymore.
117 int location_free (LocationObject *obj);
121 * Start the location service by using given #LocationObject.
123 * If you want to recieve signals, you should use this API.
125 * #location_init should be called before.
128 * obj - a #LocationObject created by #location_new
132 * Please refer #LocationError for more information.
136 #include <location.h>
137 static GMainLoop *loop = NULL;
139 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
141 LocationObject *loc = (LocationObject*)userdata;
142 LocationAccuracy *acc = NULL;
143 LocationPosition *pos = NULL;
144 LocationVelocity *vel = NULL;
145 LocationAddress *addr = NULL;
146 LocationMethod method;
148 g_object_get(loc, "method", &method, NULL);
149 g_debug("Get property>> method:%d", method);
151 if (LOCATION_ERROR_NONE == location_get_position (loc, &pos, &acc)) {
152 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
153 pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
154 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
155 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
156 location_position_free(pos);
157 location_accuracy_free(acc);
158 } else g_warning ("SYNC>> Current position> failed");
160 if (LOCATION_ERROR_NONE == location_get_velocity (loc, &vel, &acc)) {
161 g_debug ("SYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
162 vel->timestamp, vel->speed, vel->direction, vel->climb);
163 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
164 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
165 location_velocity_free(vel);
166 location_accuracy_free(acc);
167 } else g_warning ("SYNC>> Current velocity> failed");
169 if (LOCATION_ERROR_NONE == location_get_address(loc, &addr, &acc)) {
170 g_debug ("SYNC>> Current address> %s %s %s %s %s %s %s",
171 addr->building_number, addr->street, addr->district, addr->city, addr->state, addr->postal_code, addr->country_code);
172 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)", acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
173 location_address_free(addr);
174 location_accuracy_free(acc);
175 } else g_warning ("SYNC>> Current address> failed");
179 cb_service_updated (GObject *self,
185 LocationAccuracy *acc = (LocationAccuracy*) accuracy;
187 case POSITION_UPDATED: {
188 LocationPosition *pos = (LocationPosition*) data;
189 g_debug ("ASYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
190 pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
191 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
192 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
195 case VELOCITY_UPDATED: {
196 LocationVelocity *vel = (LocationVelocity*) data;
197 g_debug ("ASYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
198 vel->timestamp, vel->speed, vel->direction, vel->climb);
199 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
200 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
203 case SATELLITE_UPDATED: {
211 LocationSatellite *sat = (LocationSatellite *)data;
212 g_debug ("ASYNC>> Current Satellite> time: %d, satellite in view = %d, satellite in used = %d", sat->timestamp, sat->num_of_sat_inview, sat->num_of_sat_used);
213 g_debug ("\tinview satellite information = ");
214 for (idx=0; idx<sat->num_of_sat_inview; idx++) {
215 location_satellite_get_satellite_details(sat, idx, &prn, &used, &elevation, &azimuth, &snr);
216 g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
222 g_warning ("ASYNC>> Undefined update type");
228 int main (int argc, char *argv[])
230 LocationObject *loc = NULL;
231 int interval = 6; //seconds
234 loc = location_new (LOCATION_METHOD_GPS);
238 g_object_set(loc, "update-interval", interval, NULL);
240 g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
241 g_signal_connect (loc, "service-updated", G_CALLBACK(cb_service_updated), loc);
244 loop = g_main_loop_new (NULL, TRUE);
245 g_main_loop_run (loop); // GMainLoop is needed for receiving signals.
252 int location_start (LocationObject *obj);
256 * Stop the location service by using given #LocationObject.
258 * After call this API, you can not recieve signals.
260 * #location_init should be called before.\n
261 * #location_start should be called before.
264 * obj - a #LocationObject created by #location_new
268 * Please refer #LocationError for more information.
269 * @see location_start
272 #include <location.h>
273 static GMainLoop *loop = NULL;
275 int main (int argc, char *argv[])
277 LocationObject *loc = NULL;
279 loc = location_new (LOCATION_METHOD_GPS);
284 loop = g_main_loop_new (NULL, TRUE);
285 g_main_loop_run (loop);
290 // you can not receive signals anymore.
295 int location_stop (LocationObject *obj);
299 * Check wheither a method is available.
302 * #location_init should be called before.\n
304 * @param [in] method - a #LocationMethod
306 * @retval True Supported
307 * False Not supported
309 #include <location.h>
310 static GMainLoop *loop = NULL;
312 int main (int argc, char *argv[])
314 gboolean is_supported = FALSE;
318 is_supported = location_is_supported_method(LOCATION_METHOD_HYBRID);
319 if(is_supported == TRUE)
320 g_printf("Hybrid Method is supported.\n");
322 g_printf("Hybrid Method is not supported.\n");
328 gboolean location_is_supported_method(LocationMethod method);
332 * Check wheither GPS is turned on or off.
335 * #location_init should be called before.\n
337 * @param [in] method - a #LocationMethod
339 * @retval True Turned on
342 #include <location.h>
343 static GMainLoop *loop = NULL;
345 int main (int argc, char *argv[])
347 gboolean is_enabled = FALSE;
351 is_enabled = location_is_enabled_gps(loc);
352 if(is_enable == TRUE)
353 g_printf("GPS is turned on.\n");
355 g_printf("GPS is turned off.\n");
361 gboolean location_is_enabled_gps(LocationObject *obj);
365 * Get current position information with estimate of the accuracy.
366 * @remarks Out parameters are should be freed.
368 * #location_init should be called before.\n
369 * #location_start should be called before.
372 * obj - a #LocationObject created by #location_new
374 * position - a new #LocationPosition
376 * accuracy - a new #LocationAccuracy
380 * Please refer #LocationError for more information.
381 * @see location_get_velocity
384 #include <location.h>
385 static GMainLoop *loop = NULL;
387 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
389 g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
391 LocationObject *loc = (LocationObject*)userdata;
392 LocationAccuracy *acc = NULL;
393 LocationPosition *pos = NULL;
395 // This function works properly after service is enabled.
396 if (LOCATION_ERROR_NONE == location_get_position (loc, &pos, &acc)) {
397 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
398 pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status);
399 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
400 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
401 location_position_free(pos);
402 location_accuracy_free(acc);
403 } else g_warning ("SYNC>> Current position> failed");
406 int main (int argc, char *argv[])
408 LocationObject *loc = NULL;
409 gulong handler_id = 0;
412 loop = g_main_loop_new (NULL, TRUE);
413 loc = location_new (LOCATION_METHOD_GPS);
415 g_debug("location_new failed");
419 handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
420 location_start (loc);
421 g_main_loop_run (loop);
423 g_signal_handler_disconnect(loc, handler_id);
431 int location_get_position (LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
435 * Get current position & velocity information with estimate of the accuracy.
436 * @remarks Out parameters are should be freed.
438 * #location_init should be called before.\n
439 * #location_start should be called before.
441 * @param [in] obj - a #LocationObject created by #location_new
442 * @param [out] position - a new #LocationPosition
443 * @param [out] velocity - a new #LocationVelocity
444 * @param [out] accuracy - a new #LocationAccuracy
448 * Please refer #LocationError for more information.
449 * @see location_get_position
452 #include <location.h>
453 static GMainLoop *loop = NULL;
455 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
457 g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
459 LocationObject *loc = (LocationObject*)userdata;
461 LocationPosition *pos = NULL;
462 LocationVelocity *vel = NULL;
463 LocationAccuracy *acc = NULL;
465 // This function works properly after service is enabled.
466 if (LOCATION_ERROR_NONE == location_get_position_ext (loc, &pos, &vel, &acc)) {
467 g_debug ("SYNC>> Current position> time: %d, lat: %f, long: %f, alt: %f, status: %d, speed: %f, direction: %f",
468 pos->timestamp, pos->latitude, pos->longitude, pos->altitude, pos->status, vel->speed, vel->direction);
469 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
470 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
471 location_position_free(pos);
472 location_accuracy_free(acc);
473 } else g_warning ("SYNC>> Current position_ext > failed");
476 int main (int argc, char *argv[])
478 LocationObject *loc = NULL;
479 gulong handler_id = 0;
482 loop = g_main_loop_new (NULL, TRUE);
483 loc = location_new (LOCATION_METHOD_GPS);
485 g_debug("location_new failed");
489 handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
490 location_start (loc);
491 g_main_loop_run (loop);
493 g_signal_handler_disconnect(loc, handler_id);
501 int location_get_position_ext (LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
505 * Get last position information with estimate of the accuracy.
506 * @remarks Out parameters are should be freed.
507 * @pre #location_init should be called before.
510 * obj - a #LocationObject created by #location_new
511 * @param [out] position - a new #LocationPosition
512 * @param [out] accuracy - a new #LocationAccuracy
516 * Please refer #LocationError for more information.
517 * @see location_get_position
520 #include <location.h>
522 int main (int argc, char *argv[])
524 LocationObject *loc = NULL;
526 LocationPosition *last_pos = NULL;
527 LocationAccuracy *last_acc = NULL;
530 loc = location_new (LOCATION_METHOD_GPS);
532 g_debug("location_new failed");
536 if (LOCATION_ERROR_NONE == location_get_last_position (loc, &last_pos, &last_acc)) {
537 g_debug ("SYNC>> Last position> time: %d, lat: %f, long: %f, alt: %f, status: %d",
538 last_pos->timestamp, last_pos->latitude, last_pos->longitude, last_pos->altitude, last_pos->status);
539 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
540 last_acc->level, last_acc->horizontal_accuracy, last_acc->vertical_accuracy);
541 location_position_free(last_pos);
542 location_accuracy_free(last_acc);
543 } else g_warning ("SYNC>> Last position> failed");
551 int location_get_last_position (LocationObject *obj, LocationPosition **position, LocationAccuracy **accuracy);
555 * Get last position & velocity information with estimate of the accuracy.
556 * @remarks Out parameters are should be freed.
557 * @pre #location_init should be called before.
559 * @param [in] obj - a #LocationObject created by #location_new
560 * @param [out] position - a new #LocationPosition
561 * @param [out] velocity - a new #LocationVelocity
562 * @param [out] accuracy - a new #LocationAccuracy
566 * Please refer #LocationError for more information.
567 * @see location_get_position_ext
570 #include <location.h>
572 int main (int argc, char *argv[])
574 LocationObject *loc = NULL;
576 LocationPosition *last_pos = NULL;
577 LocationVelocity *last_vel = NULL;
578 LocationAccuracy *last_acc = NULL;
581 loc = location_new (LOCATION_METHOD_GPS);
583 g_debug("location_new failed");
587 if (LOCATION_ERROR_NONE == location_get_last_position_ext (loc, &last_pos, &last_vel, &last_acc)) {
588 g_debug ("SYNC>> Last position> time: %d, lat: %f, long: %f, alt: %f, status: %d, speed: %f, direction: %f",
589 last_pos->timestamp, last_pos->latitude, last_pos->longitude, last_pos->altitude, last_pos->status, last_vel->speed, last_vel->direction);
590 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
591 last_acc->level, last_acc->horizontal_accuracy, last_acc->vertical_accuracy);
592 location_position_free(last_pos);
593 location_velocity_free(last_vel);
594 location_accuracy_free(last_acc);
595 } else g_warning ("SYNC>> Last position_ext > failed");
603 int location_get_last_position_ext (LocationObject *obj, LocationPosition **position, LocationVelocity **velocity, LocationAccuracy **accuracy);
606 * Get last satellite information.
607 * @remarks This API is not implemented now. \n
608 * Out parameters are should be freed.
610 * #location_init should be called before.
613 * obj - a #LocationObject created by #location_new
614 * @param [out] satellite - a new #LocationSatellite
617 * Please refer #LocationError for more information.
618 * @see location_get_last_satellite
621 #include <location.h>
623 int main (int argc, char *argv[])
625 LocationObject *loc = NULL;
626 int ret = 0, idx = 0;
627 LocationSatellite *sat = NULL;
635 loc = location_new (LOCATION_METHOD_GPS);
637 g_debug("location_new failed");
641 if (LOCATION_ERROR_NONE == location_get_satellite (loc, &sat)) {
642 g_debug ("SYNC>> Current Sattelite> satellite in view = %d, satellite in used = %d", sat->num_of_sat_inview, sat->num_of_sat_used);
643 g_debug ("\tinview satellite information = ");
644 for (idx=0; idx<sat->num_of_sat_inview; idx++) {
645 location_satellite_get_satellite_details(sat, idx, &prn, &used, &elevation, &azimuth, &snr);
646 g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
648 location_satellite_free (sat);
649 } else g_warning ("SYNC>> Current satellite> failed");
657 int location_get_satellite (LocationObject *obj, LocationSatellite **satellite);
661 * Get last satellite information.
662 * @remarks This API is not implemented now. \n
663 * Out parameters are should be freed.
665 * #location_init should be called before.
668 * obj - a #LocationObject created by #location_new
670 * satellite - a new #LocationSatellite
674 * Please refer #LocationError for more information.
677 #include <location.h>
679 int main (int argc, char *argv[])
681 LocationObject *loc = NULL;
682 int ret = 0, idx = 0;
683 LocationSatellite *last_sat = NULL;
691 loc = location_new (LOCATION_METHOD_GPS);
693 g_debug("location_new failed");
697 if (LOCATION_ERROR_NONE == location_get_last_satellite (loc, &last_sat)) {
698 g_debug ("SYNC>> Last Sattelite> satellite in view = %d, satellite in used = %d", last_sat->num_of_sat_inview, last_sat->num_of_sat_used);
699 g_debug ("\tinview satellite information = ");
700 for (idx=0; idx<last_sat->num_of_sat_inview; idx++) {
701 location_satellite_get_satellite_details(last_sat, idx, &prn, &used, &elevation, &azimuth, &snr);
702 g_debug ("\t\t[%02d] used: %d, prn: %d, elevation: %d, azimuth: %d, snr: %d", idx, used, prn, elevation, azimuth, snr);
704 location_satellite_free (last_sat);
705 } else g_warning ("SYNC>> Last satellite> failed");
713 int location_get_last_satellite (LocationObject *obj, LocationSatellite **satellite);
717 * Get current velocity information with estimate of the accuracy.
718 * @remarks Out parameters are should be freed.
720 * #location_init should be called before.\n
721 * #location_start should be called before.
724 * obj - a #LocationObject created by #location_new
726 * velocity - a new #LocationVelocity
728 * accuracy - a new #LocationAccuracy
732 * Please refer #LocationError for more information.
733 * @see location_get_position
736 #include <location.h>
737 static GMainLoop *loop = NULL;
739 static void cb_service_enabled (GObject *self, guint status, gpointer userdata)
741 g_debug("cb_service_enabled: status(%d) userdata(0x%x)", status, (unsigned int)userdata);
743 LocationObject *loc = (LocationObject*)userdata;
744 LocationAccuracy *acc = NULL;
745 LocationVelocity *vel = NULL;
747 if (LOCATION_ERROR_NONE == location_get_velocity (loc, &vel, &acc)) {
748 g_debug ("SYNC>> Current velocity> time: %d, speed: %f, direction:%f, climb:%f",
749 vel->timestamp, vel->speed, vel->direction, vel->climb);
750 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
751 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
752 location_velocity_free(vel);
753 location_accuracy_free(acc);
754 } else g_warning ("SYNC>> Current velocity> failed");
757 int main (int argc, char *argv[])
759 LocationObject *loc = NULL;
760 gulong hander_id = 0;
763 loop = g_main_loop_new (NULL, TRUE);
765 loc = location_new (LOCATION_METHOD_GPS);
767 g_debug("location_new failed");
771 handler_id = g_signal_connect (loc, "service-enabled", G_CALLBACK(cb_service_enabled), loc);
772 location_start (loc);
773 g_main_loop_run (loop);
775 g_signal_handler_disconnect(loc, handler_id);
784 int location_get_velocity (LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
788 * Get last velocity information with estimate of the accuracy.
789 * @remarks Out parameters are should be freed.
791 * #location_init should be called before.
794 * obj - a #LocationObject created by #location_new
796 * velocity - a new #LocationVelocity
798 * accuracy - a new #LocationAccuracy
802 * Please refer #LocationError for more information.
803 * @see location_get_position
806 #include <location.h>
808 int main (int argc, char *argv[])
811 LocationObject *loc = NULL;
812 LocationVelocity *vel = NULL;
813 LocationAccuracy *acc = NULL;
814 gulong hander_id = 0;
818 loc = location_new (LOCATION_METHOD_GPS);
820 g_debug("location_new failed");
824 ret = location_get_last_velocity (loc, &vel, &acc);
825 if (ret == LOCATION_ERROR_NONE) {
826 g_debug ("SYNC>> Last velocity> time: %d, speed: %f, direction:%f, climb:%f",
827 vel->timestamp, vel->speed, vel->direction, vel->climb);
828 g_debug ("\tAccuracy level %d (%.0f meters %.0f meters)",
829 acc->level, acc->horizontal_accuracy, acc->vertical_accuracy);
830 location_velocity_free(vel);
831 location_accuracy_free(acc);
839 int location_get_last_velocity (LocationObject *obj, LocationVelocity **velocity, LocationAccuracy **accuracy);
843 * Get the accessibility state of an application
846 * #location_init should be called before.\n
848 * @param [out] state - a #LocationAccessState
852 * Please refer #LocationError for more information.
854 int location_get_accessibility_state (LocationAccessState *state);
858 * Send command to the server.
859 * @remarks This functions is not implemneted yet.
861 * #location_init should be called before.\n
862 * Calling application must have glib or ecore main loop.\n
863 * Calling application must have an active data connection.
865 * @param [in] cmd - a #char
869 * Please refer #LocationError for more information.
871 int location_send_command(const char *cmd);
879 #endif /* __LOCATION_H__ */