Location Information
Location information allows you to get a device’s geographic position. Additionally, location-related information can also contain information about altitude, the accuracy of the location and altitude readings, and the user’s movement speed and direction.
The main features of the Tizen.Location namespace include the following:
-
Enabling the location service
You can use the location service to get the current location, receive location change events and satellite information, use location bounds, or track routes.
-
Defining the location type
You can select the appropriate location positioning system type to achieve the optimal quality level for the location service.
Location service
The Tizen.Location namespace provides the current location using the location sources specified in the Tizen.Location.LocationType enumeration. You can use the location service to manage location information in the following ways:
-
Get the user’s current location
You can set up event handlers to track the current location of the device and be notified of location change events.
-
Get satellite information
-
Use location bounds
You can create virtual perimeters and monitor when a device enters or leaves them.
NoteTo test the Tizen location-based services on the emulator, provide location data (longitude and latitude) using Emulator Control Panel.
Since satellite data is not supported on the emulator, GPS status data is available on a target device only.
Asynchronous location-related updates and region monitoring notifications are implemented with events. Location-related events are called only if the location service has been started
You can use the location state and updates as follows:
- If the location service is working correctly, Tizen.Location.ServiceState is set to
Enabled
. The device can receive notifications about location change events only in this service state. - If the location service is unable to run on the requested device due to weak radio reception, the location service state is set to
Disabled
. If this situation persists for a longer period, stop the service and try again later, to conserve the device battery.
Location types
The Tizen.Location.LocationType enumeration is used to specify the desired quality of service of the Tizen.Location.Location instance. For example, a location-based weather forecast application can require only very basic information to distinguish a city or a neighborhood, while a GPS navigation application can require the highest quality level to pinpoint a map location. Selecting the appropriate quality level not only helps to run the system efficiently but also leads to a good user experience.
Using the Tizen.Location.LocationType
enumeration allows your application to specify the following location positioning system types:
Hybrid
, which selects the best method available at the momentGPS
, which uses the global positioning systemWPS
, which uses the Wi-Fi positioning systemPassive
, which uses the passive mode
Prerequisites
To use the Tizen.Location namespace, the application has to request permission by adding the following privilege to the tizen-manifest.xml
file:
XML
Copy
<privileges>
<privilege>http://tizen.org/privilege/location</privilege>
</privileges>
Start the location service
To start the location service, proceed as follows:
-
Create a Tizen.Location.Locator instance with a specific value for its
LocationType
property before you use the location service.In this example, GPS is used as the source of the position data. You can use other values of the Tizen.Location.LocationType enumeration for hybrid and WPS sources:
C#CopyTizen.Location.Locator locator; locator = new Locator(LocationType.Gps);
Each
Tizen.Location.Locator
is an independent service. Multiple instances can be created in the same application to provide different services, such as GPS and WPS. Events are set for a given instance and are called only if the service is started for theirTizen.Location.Locator
instance. -
Start the location service using the
Start()
method. This call is asynchronous and only initiates the process of starting the location service. Once the service is started, registered event handlers are invoked when their corresponding events take place. To know when the service becomes enabled, use theServiceStateChanged
event of theTizen.Location.Locator
class:C#Copylocator.Start();
-
Using the location service consumes power, so if the service is not used, stop updating the location using the
Stop()
method. Call theStart()
method again if updated position information is needed:C#Copylocator.Stop();
-
At the end of the application lifecycle, destroy all used resources, such as the
Tizen.Location.Locator
instance:C#Copylocator.Dispose(); locator = NULL;
If you destroy the
Tizen.Location.Locator
instance, there is no need to call theStop()
method to stop the service, as the service is automatically stopped. In addition, you do not have to remove any previously added event handlers.
Get the current location
To synchronously retrieve the current location of the device, proceed as follows:
-
Register an event handler for location service state changes and start the location service:
C#Copylocator.ServiceStateChanged += ServiceStateHandler; locator.Start();
The
ServiceStateHandler()
method is an event handler, which is called when the location service state changes:C#Copybool serviceEnabled = false; void ServiceStateHandler(Object sender, ServiceStateChangedEventArgs e) { if (e.ServiceState == ServiceState.Enabled) serviceEnabled = true; }
-
After starting the location service, call the
GetLocation()
method to get the current location information:C#CopyTizen.Location.Location location = locator.GetLocation();
When the service state is set to
Disabled
, theGetLocation()
method may not return the current location, but a previous one. -
When you no longer need the state updates, remove the event handler:
C#Copylocator.ServiceStateChanged -= ServiceStateHandler;
Get location events
You can get a notification of the device position being updated by using an event handler for the LocationChanged
event of the Tizen.Location.Locator
class. The event handler is invoked periodically, receiving the device’s current position with every call. You can use the event handler to retrieve the device position (given as coordinates) and convert it to the corresponding address.
To use the location change event handler, proceed as follows:
-
Register the event handler:
C#Copylocator.Interval = 2; locator.LocationChanged += LocationChangedHandler
The
Interval
property determines the event call frequency. In this example, the event is called every 2 seconds. -
When the update is received, you can, for example, update the location that stores the device’s current position:
C#Copyvoid LocationChangedHandler(Object sender, LocationChangedEventArgs e) { Tizen.Location.Location location = e.Location; }
Note
The event is called only if the location service has already been started.
Get satellite information
You can retrieve and update information about a satellite visible to the device. The information includes azimuth, elevation, PRN, SNR, and NMEA data. An event handler is invoked periodically, receiving information about the visible satellites with every call.
To retrieve satellite information, proceed as follows:
-
Register an event handler for the
SatelliteStatusUpdated
event of the Tizen.Location.GpsSatellite class:C#Copysatellite.Interval = 3; satellite.SatelliteStatusUpdated += SatelliteStatusChangedHandler;
The
Interval
property of theTizen.Location.GpsSatellite
class determines the event call frequency. In this example, the event is called every 3 seconds. -
When the event handler is invoked, update the count of active and total satellites in view of the device:
C#Copyvoid SatelliteStatusChangedHandler(Object sender, SatelliteStatusChangedEventArgs e) { int active = e.ActiveCount; int inview = e.InViewCount; }
Note
The event is called only if the location service has already been started.
Use location bounds
You can define a virtual perimeter, which is monitored to see whether the device enters or exits the area.
To use a location boundary, proceed as follows:
-
Create location bounds with the required area type (rectangle, circle, or polygon) needed for your application:
C#CopyCoordinate one, two, three; List<:Coordinate> list = new List<Coordinate>(); one.Latitude = 10.10; one.Longitude = 10.10; two.Latitude = 20.20; two.Longitude = 20.20; three.Latitude = 30.30; three.Longitude = 10.10; list.Add(one); list.Add(two); list.Add(three); PolygonBoundary polygon = new PolygonBoundary(list);
When a circular bound is needed, use the Tizen.Location.CircleBoundary class.
-
To get notifications when the user enters or exits the defined perimeter, register an event handler:
C#Copylocator.ZoneChanged += ZoneChangedHandler;
Implement the event handler for the
ZoneChanged
event of theTizen.Location.Locator
class:C#Copyvoid ZoneChangedHandler(Object sender, ZoneChangedEventArgs e) { if (BoundaryState.In == e.BoundState) { /// Boundary changed } }
-
Call the
AddBoundary()
method to add the boundary to a location service:C#Copylocator.AddBoundary(polygon);
-
When the boundary is no longer needed, destroy it:
C#Copylocator.RemoveBoundary(polygon); polygon.Dispose();
Related information
- Dependencies
- Tizen 4.0 and Higher