Video: bada – Locations
Welcome to bada video lecture. In this lecture, I will be explaining about the APIs and the framework provided in bada for developing location based application. First , I will Explain about Namespaces related to locations. Location based services in bada is divided into three namespaces namely Locations, Location services and Location controls. Let’s dig into theses namespaces to get a detailed picture. Location namespace mainly discuss about the Location based services like Location provider , remote location provider classes which provides the methods to achieve the use cases like Where am I or where is my friend. Landmark, landmark stores, remote landmark store classes provides the methods to find interesting places around, Storing Data base of points of interest in the device & servers. Location services provides services for Map, geocoding , route, and directory and Location control allow the user to control map more easily.
I will start with the Locations namespace As discussed, the locations namespace can be best explained using the important classes like Location provider, Remote Location provider and landmarks. Landmarks support both device landmark store and remote landmark store. Let’s discuss about location provider. Location provider class will give the location of the device; it is implemented using GPS and WIFI . Location updates can be requested based on periodic or distance based. ILocationListener interface provides a listener that receives events associated with a particular location provider. In order to use the Location provider APIs, we need to include privileges of the LOCATION in manifest file. Location class describes the location using Qualified coordinate, Course , speed, Time stamp, Location method such as GPS, WPS, or HYBRID and Satellite Info. Coming to the Remote location provider .
Remote location provider will give the location of the other device both in periodic base and distance of the current location. IRemoteLocationListener interface provides a listener that receives events associated with a particular location provider. In order to use the Location provider APIs we need to include privileges of the REMOTE_LOCATION in manifest file. Location class methods describes the location using Last known location service and Trace service. Now, Let’s see how to get the location updates periodically. For Location updates, the registry function need to use is RequestLocationUpdates. For each time interval mentioned in the registry function, the listener function OnLocationUpdated will be getting called. On application going to the background or when location updates are not required, CancelLocationUpdates API can be called to cancel the location updates through which battery life is saved.
On returning application to the foreground, need to re-register for location updates using the RequestLocationUpdates API. On application Termination, listening to location updates can be canceled using CancelLocationUpdates method. Next, let’s see how area monitoring can be achieved. Area monitoring is nothing but the getting a notification on crossing a specified boundary. For monitoring the area, AddAreaListener is the method to be used for registration with the listener. When the device crosses the boundary, the callback OnBoundaryCrossed will be invoked. Pointed to be noted here is, if you have received the OnBoundaryCrossed event, the listener registration is cancelled automatically and if you want to receive it again, you need to re-register the listener. On termination, the listener can be removed with method, RemoveAreaListener.
Coming to the location information on request. Location information can be retrieved by application request instead of periodic updates. Since it returns the last location that was recorded, you must check the timestamp and other fields to determine if this information is recent enough for the application to use without creating a new request for obtaining the current location. GetLastKnownLocationN() has 2 overloaded variations. One will Get the last known location that is recorded regardless of the location method and the other one Gets the last known location recorded using the specified location method. Now Lets see what Landmark is. landmark is a known location with a name, also called as point of interest(POI). Landmark Store is a container of landmarks which will support search for landmarks by a name, a category, a bounding box. Privilege needed for landmark is LANDMARK. Now, the landmark class.
The named landmark mainly contains textual description, coordinates , address, timestamp of the last change, Geographical area covered , author and URLs for additional content. Lets see different functions supported in the landmark class. By using the landmark class methods you can get or set the data like AddressInfo , Author, Description, ExtraInfo , GeographicArea , Name, QualifiedCoordinates and Url. In addition to this, there are methods to get the LandmarkId, LandmarkStoreName and Timestamp. landmark class has three constructors which can be used based on convenience. The options are, you can duplicate a landmark, create a landmark with name or create an empty landmark and fill in the details later. As discussed early, landmark store is a set of landmarks. Landmark stores are of two types ; private, which be visible only to the creator. And Public, which is visible to any application. In public type, the creator has the full access to the Landmark store and the others can only retrieve the values. Now ,Let’s see a sample code snippet of how to create the public landmark store. In this sample, I have created the landmark store with name “Store".
The second parameter of the API, CreateLandmarkStore states whether it is public or not. ‘True’ for public and ‘false’ for private. Then, I have used construct method to initialize the landmark store. Next, we will see how we can add a landmark to the landmark store. Here, I have used the landmark constructor which takes name as input parameter. Then, I have prepared a coordinates object and set it to the landmark using the SetQualifiedCoordinate API. Finally, added the landmark to the landmark store using the API, AddLandmark with landmark instance and category as parameters. Now Lets see how to search a landmark by giving the latitude and longitude values. In order to get alert for search result, listener is required, so I have created it first. While searching the landmark, interested landmark property can be enabled using the LandmarkPropertySelector . Here, I have enabled the address info and description. Then, SearchLandmarks API is called with parameters listener, latitude, longitude and landmark property selector.
Coming to the listener class, The Listener for search result is MyListener in our sample code. MyListener class mainly contains one method OnLandmarkSearchResultReceivedN which is the callback for search results of the landmark. Now, lets see how we can implement this method to retrieve the search result of the landmarks. The resultant landmarks if any, will be available as IEnumerator pointer in this method. We can iterate through the enumerator, type cast each item to landmark and can read the values. Next, Lets see how to search landmark by name. The implementation is as simple as giving the category to be searched, the name of the landmark to search, property selector and the listener to the API SearchLandmarks. In the place of name if null is passed all the landmarks in the specified category will be retrieved.
Also, landmarks can be searched using with different filters depending on the requirements. Filters will filter the resultant landmarks with the filter category and shows only those landmarks. In this example, let see how to search a landmark with filter category FOOD_AND_BEVERAGE within a range of 100 meters area from the current location. First, Get the current location using the API GetLastKnownLocationN and retrieve the coordiantes. Then set the circlegeographicarea to 100 meters from this coordinates. The filter category can be set using the SetCategory with the category name as input parameter and the area filter can be added using SetGeographicAreaFilter with area as input parameter. Now, search landmark with the parameters filter, selector,sorting order, sort category and the listener. Now that we have seen how to create and search landmarks, lets see how we can remove or update a landmark.
In this example, I am trying to update the description of the landmark. For that, I retrieved the landmark instance, first. Then updated the Description, using SetDescription API. Then I called the UpdateLandmark API of landmarkstore with the landmark as parameter. The Landmark can be deleted from a landmarkstore, using the DeleteLandmark API with the landmark instance as parameter. Next, Lets dig into the remote landmark store. Remote Landmark store is the means for storing the landmark in a remote place such as bada server. The privilege needed to use the remote landmark store APIs is REMOTE_LANDMARK which need to be added in the manifest file of the Application. remote landmark store is of two types ‘Predefined landmark stores’ and the ‘user created landmark stores’. The difference between the two types is Pre-defined landmark store is read only, since it is provided by the third party, and the user defined landmarks are the application landmarks. The applications landmarks can be created, deleted and accessed with the same application from any device.
That’s all with the first namespace Locations. Now lets move on to the next Namespace, Location Services. Location services provides location-based services, such as geocoding, routing, and directory searches. The privilege required for using the location services APIs is LOCATION_SERVICE. The Geocoding service helps to convert street addresses into coordinates and vice versa. Routing service allows your application to determine the route between two locations and implement navigation features. Directory service allows applications to perform geographically constrained searches for any data, such as places, products, and services Decarta is the default service provider used in bada. For developing any application related to location services, it is needed to register at Decarta site and get the credentials to use the service. Provider manager is the starting point for any location service. To use the service of the service provider, you need to connect to it using ConnectToServiceProviderN API, giving the credentials collected from the service provider. From bada SDK 2.
0 version onwards the first parameter of the connect to service provider API can be an empty string. If empty string or "DEFAULT_SERVICE_PROVIDER“ is passed as the first parameter, this method returns the default service provider for the requested service type. The different service provider types supported are map service, route service, Geocode service and direction. If you want to check the capabilities of the service provider, you can use the API, GetServiceProviderCapabilitiesN(). Now, lets discuss about the Geocoding services. In geocoding service, the location is represented as address and geographic coordinates. Address is the location represented in human- understandable format with country, state, city etc. And Geographic coordinates consists of longitude, latitude and altitude of the location.
This is used for mapping a location into Map or getting a location from GPS. The main functionality of this service is geocoding and reverse geocoding. In geocoding, address is converted to coordinates of the location to which the address corresponds to. And in reverse geocoding the reverse happens. Ie: the coordinates are converted to the address corresponding to the location represented by the coordinates. Lets check the important classes and interfaces which contributes in providing the geocoding service. First and the most important interface is the Igeocodingserviceprovider. This interface helps applications to request geocoding and reverse geocoding related services from the service provider. To convert address to coordinate, ie: to geocode, we can use the API, ‘geocode’. You can pass the addressinfo as the main parameter to this API to get the coordinates corresponding to a location. There is also an overloaded method to Geocode which will take the free form address or partial address as the main parameter and get you the location coordinates.
To do the reverse, ie: conversion from coordinates to address can be done with ‘reverseGeocode’ API. Both the geocode and reversegecode APIs are asynchronous and to receive the result you need to implement the IGeocodingServiceListener. To cancel the requests you can use the Cancel Request API. Lets check the address field used in geocoding. At least one from the following address fields is mandatory for geocoding. Streetname, street intersection. Ie: crossing 1 and crossing 2, postal code, state, country, city or district. Street number is optional. While requesting geocode or reversegeocode, you can set the preferences related to a geocoding service provider. GeocodingServicePreferences is the class which is used to capture this. These preferences include controlling the number of matches and exact matches. Geocoding service provider may find several coordinates for a given address. Application can tell the maximum number of geocoded results by setting the maximum number of matches as the number it wants.
SetMaxMatchesCount is the API to be used with the maximum matches as the input parameters. Application may want to get only one set of coordinates which matches exactly the given address. This can be done by setting the exact match preference as true. SetExactMatch is the API to be used for this purpose. Base country code can be set using the SetBaseCountryCode API. This will be the country code used by the given geocoder. As we discussed earlier, we need to implement IGeocodingServiceListener to receive the result of geocoding or reversegeocoding. This listener provides a callback mechanism for the geocoding service providers to send information about the service request to the applications. We can implement this this interface in our applications and register it in a service request to the service provider, represented by IGeocodingServiceProvider, to obtain information from it. There are two methods in this listener, which are OnGeocodingRequestResultReceivedN , OnReverseGeocodingRequestResultReceivedN. OnGeocodingRequestResultReceivedN will be called by geocoding service provider when the result of the geocoding request has been received. And for reverse geocoding request, the service provider will call OnReverseGeocodingRequestResultReceivedN when the result of the request has been received.
Now, Lets see an example of using the Geocode for better understanding of geocoding services. First, connect to the service provider using the ConnectToServiceProviderN API which returns the provider object. With the provider object call the Geocode method with the Address to geocode and pass the listener. The main point to be remembered about the geocode is, the country code should be set corresponding to the address to be geocoded. If not, even if the country name is mentioned in the address it will be ignored. If the country code is not set, the result will be wrong or no result. Now, lets see the declaration of the IGeocodingServiceListener class. OnGeocodingRequestResultReceivedN is the listener getting triggered on geocode and OnReverseGeocodingRequestResultReceivedN is listener for reverse geocode. The result values can be retrieved as the output parameters in the listener methods.
As discussed, the OnGeocodingRequestResultReceivedN callback will be getting triggered when the geocoding service providers send information about the result of the service request to applications. It is applications’ responsibility to show or use the obtained results. The result received will be a list of landmarks. You can iterate through the list, get each landmark and use the coordinates as shown in the example OnReverseGeocodingRequestResultReceivedN can also be implemented in a similar way. The result you will need to retrieve there will be the address for the requested location Now , Lets check the directory services. Directory service is provided through a location service provider, and allows applications to perform geographically constrained searches for any data, such as places, products, and services.
This service is about finding something somewhere. Here something means some human readable ID such as a name, category or keyword and somewhere can be an address or a geographical area. For example find cafe within 500 meters of my hotel. The result of this search will be landmarks. Lets check the important classes and interfaces for directory service. IDirectoryServiceProvider is the main interface for this service and it represents the directory service provider. This interface accesses the services offered by the directory service provider. The main APIs are Search , GetFilterN and CancelRequest. Search is the main API and it is asynchronous. We have to implement the listener and pass it to this API to get the result of the search. Other main parameters are the directory filter which contains keyword, category etc, then a Local filter such as geographic area, address etc. , and the preferences for the search.
Based on local filter, the search has 4 overloaded variations. They are, A search without any local filter, A search with address filter , A search with a geographic area filter and A search with free form address filter. A search can be cancelled with the CancelRequestAPI. To get the filter for the directory service provider, we can use the API, GetFilterN. DirectoryServicePreference is the class which is used to specify the preferences for the directory service provider. The preferences include, controlling options for the number of results and sorting. The provider will be having a default value for the maximum number of search results that can be given in response to a search request. We can change this value using SetMaxResultCount() API. To get a sorted result, you can set the sortOrder and criteria using the APIs SetSortBy and SetSortOrder. IDirectoryServiceListener is the listener used in directory service.
To obtain search results from the service provider, applications implement this interface and register it in the service request, i.e.: search in IDirectoryServiceProvider. The Only method we have in this interface is OnDirectoryRequestResultReceivedN. This method will be called by the directory service provider when the result of a search request has been received. Let us see the sample code for searching a coffee shop in map using the directory services. The basic code is same for connecting to the server. Then, create a directory filter instance. The filter can be added using the AddFilter API, The search is using the keyword “coffee” . Search API is called with the filter instance , the geographical area within which result is required, listener and the request ID. The listener triggered for the directory search is OnDirectoryRequestResultReceivedN. And data can retrieved by type casting. the directory search result data will be obtained as a output parameter in the listener.
The other operations like showing or using the values will be controlled by the application . This is all about the directory services. Next we will see the Route Services. Route service allows your application to determine the route between two locations, determine the route through multiple waypoints , and implement navigation features. You can use this service to display route on a map. Route service available with the support from the route service Provider. Route requests consists of the waypoints for the route and the preferences like area to area to be avoided, features to be avoided and the mode of transport. The result from the route service provider will include the route summary that contains the duration and length, route geometry ; ie: the set of coordinates that graphically represents the determined route and the turn-by-turn route instructions . Now, lets discuss the important classes and interfaces used for RouteService.
IRouteServiceProvider is the main interface and it represents the Route Service Provider. Through this interface applications request route related services from the route service provider. GetRoute() is the API which is used to request the route from route service provider. Its an asynchronous method and the result will be received through the listener, IRouteServiceListener. To cancel the GetRoute request, we can use the API, CancelRequest. RouteServicePreferences class captures the preferences related to route service providers. This class Encapsulates the preferences that are used when requesting routing services from a service provider. As discussed earlier, the preferences may include the type of the route, the transport mode used to travel the route, and the areas and features to be avoided when calculating the route. Lets check the APIs to be used for these purposes. You can set the maximum number of matches returned from the route service provider, using the API, SetMaxMatchesCount. You can avoid the unwanted areas and addresses using the APIs, SetAreasToAvoid(), SetAddressesToAvoid() and SetFreeformAddressesToAvoid ().
SetFeaturesToAvoid() API sets the features to be avoided in route generation. These features can be toll ways or bridges. Using SetTransportMode API, you can set the transport mode to be used in route generation. Possible transport mode values can be retrieved with the ProviderCapabilities::GetPropertyValue() method using ProviderCapabilities::ROUTE_SUPPORTED_TRANSPORT_MODES as the property key. You can use SetRouteType() to set the route type to be used in route generation. Possible route type values can be retrieved with the ProviderCapabilities::GetPropertyValue() method using ProviderCapabilities::ROUTE_SUPPORTED_ROUTE_TYPES as the property key. IRouteServiceListener is the listener used in route service. Applications implement this interface and register it in the service request in IRouteServiceProvider to obtain search results from the service provider. The only method available in this listener is OnRouteReceivedN() which will be called by the route service provider when the requested route has been calculated by the GetRoute method.
Lets discuss about the third and last namespace Location Controls. The Location control namespace contains classes and interfaces to allow the users to control the map easily. It provides various functionalities to render the map using the concept of layer, deals with the user input like zooming , panning , moving marker and display "My Location" and handle the overlays. Applications can draw some additional information about places or map features using InfoWindow. From SDK 2.0 onwards, we support map rotation and prefetch. Lets discuss about each concept in detail. First lets check rendering map in layers. The map control can render the maps using the concept of layers. Rendering the maps is completed by drawing each layer step by step. There are 5 type of layers: for rendering different kind of information: map, overlay, my location, InfoWindow, and zoom control. Map is the bottom most layer and control is the top most layer.
Let’s start with the basic sample code of how to draw a map. For getting the map , registration with the Decarta is required since Decarta is the service provider for bada locations. So in order to connect to the service provider the authentication in others words client name and client password is required. ConnectToServiceProviderN is the API to connect to the service provider with the parameters name, type of services and the additional information like user name, password received from Decarta for authentication to use the Decarta services. The name of the provider is optional. If nothing is given, the default service provider, ie: decarta is used. When calling the ConnectToServiceProviderN API, the service provider object is returned as a return value Now, Map instance is created and constructed with parameters, the rectangular area to be used for showing the map, the provider pointer stored from the return value of ConnectToServiceProviderN and Boolean variable to enable the map rotation. Then, the center of the map is set using the method SetCenter.
After setting the center of the map, the zoom level is set using the SetZoomLevel method. For listening to any of the events like touch events, AddTouchEventListener method should be called with the listener name as parameter . Finally , map class is added to the control using the API AddControl. After adding the control, draw and show methods should be called to show the map in the UI. And in catch, the pointers are deleted to free the memory. Lets see how to handle the overlays. Overlays are objects on the map that are tied to latitude , longitude coordinates. that is, for drawing shapes like rectangle, circles, polylines, polygons, icons or markers, or custom objects including their shadows on the map. Overlay layer provides event handlers for shapes and markers, you can add interactivity such as moving the markers by dragging. NativeMapOverlay is the lass which provides methods to make overlays which are rendered on a map. All overlays must inherit this class to work as an overlay on the map. We can use the SetExtraInfo() and GetExtraInfo() methods to set and get user information of about an overlay.
The SetHighlighted() method can be used to highlight an overlay, and the IsHighlighted() method can be used to check whether the overlay is highlighted. SetPriority() and GetPriority() are the methods to set and get the priority of the overlay. And to set and get the z-order of the overlay, we can use the SetZOrder() and GetZOrder() methods. There are 3 types of native overlays:Shapes, polylines and markers. Shapes are used to provide an interactive capability to the map overlay layers. You can create rectangles using Osp::Locations::Controls::MapOverlayRectangle, circles using Osp::Locations::Controls::MapOverlayCircle , and polygons using Osp::Locations::Controls::MapOverlayPolygon. Polylines using Osp::Locations::Controls::MapOverlayPolyline class are used to display polyline overlays. Markers, ie: MapOverlayMarker are used in much the same way as colored pins are used on physical maps.
For example, you can place markers on the map and display an information window when they are clicked. Now, Lets see sample code to add map overlay . this will give a clear picture on how to add map overlay. There are many overlays supported by bada like map overlay polygon , map overlay circle , map overlay polyline e.t.c. Lets see how to add map overlay polygon. Here just explaining about how to add map overlay as we already studied about the map rendering part earlier. First, create an object of the map overlay polygon. For drawing the polygon, coordinates should be set. Set the four coordinates. Then, add the coordinates to the array list. The array will be added to the polygon geographical area. Now , construct the map overlay polygon with the polygon geographical area as a input parameter. Finally, add the overlay to the map using the API AddMapOverlay. If intrested listener can be added for any events using the API AddMapOverlayEventListener. Let’s see handling the InfoWindow.
Info window can be used to describe some additional information about places or map features on the map. InfoWindow consists of an InfoWindow image box, a title area, a content area, and a close button. Users can draw both native or pre-defined InfoWindow and custom InfoWindow on the map. For custom info windows, you directly draw your content onto the canvas. In this case, DrawContent() is the method used to render the specific info window on the map. With a native info window , ie: NativeMapInfoWindow, you can set the title, set or draw the content such as text or bitmaps, open the information window, and finally draw and display the map on the canvas. The main APIs used for this are SetContent to set the content, SetCoordinates to set the coordinates and SetTiTle to set the title of the info window.
Next lets see ‘how to display my location’ . My Location can be displayed on the My Location layer. My Location displays current point to indicate the position on the map and circular bounds to represent the margin of error for the position. Current location information is updated on a regular basis. You can use the MoveToMyLocation() API of Map class to move the center of a map to the current location. Lets see Handling user input on the map. For handling user input on the map, map class provides methods for processing user input such as zooming or panning the map. Pan is the API which pans the map in the specified direction. Application developer can give the amount of pixels to be panned. SetZoomEnabled API can be used to the set zoom level of the map , this API can be used to increase or decrease the zoom level based on the application requirement. SetZoomEnabled() is the API to enable or disable zooming in a map and it can be checked with the API, IsZoomEnabled(). And the ZoomLevel can be retrieved using GetZoomLevel() Similarly, SetPanEnabled can be used to enable or disable panning and it can be checked with the API IsPanEnabled() Lets see map rotation which is introduced in SDK 2.
0 . Map Rotation is a feature in which the user will be able to rotate the map with respect to true north either clockwise or anti clockwise direction. Map rotation feature can be enabled by passing the “true” as the last parameter in map construct. You can use the API, Map::Rotate() to rotate the map according to a specified azimuth value. During the rotation of map, all the overlays, markers, my location icon and info window drawn on the map is kept intact with respect to the rotated map without changing their co-ordinates. Let’s see map rotation sample code for better understanding of the feature. In order to enable the map rotation while constructing the map the third parameter is passed as true. For rotating the map, the rotate method should be used with the azimuth, ie:the angle the map to be rotated and the Boolean variable to enable or disable the effect. Map prefetch feature allows the user to download a Map of size bigger than the actual screen size. This enhances the user experience during zooming and panning by avoiding the display of gray areas. Map Prefetch is not enabled by default.
SetPrefetchMargin of Map class is the API to be used to set the prefetch margin. There are two overloaded methods for SetPrefetchMargin through which the margin can by passing the width and height or dimension as input parameters. We have reached the end of the session. Let’s summarize what we have discussed. Locations namespace provides plenty of features related to location. The Location provider yields the current location and landmark store is the set of interesting locations. Location services gives the features like Geocoding provider to convert addresses to coordinates, Directory provider to search locations in a user-friendly manner, and Route provider for automatic navigation. The map control contains classes and interfaces to allow the users to control the map easily. Practice examples. Write code to show map. Find the distance between two coordinates. Write code to test the reverse geocoding.
Write code to test the area monitoring..