inc/FLocILocationProviderListener.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19 * @file         FLocILocationProviderListener.h
  20 * @brief        This is the header file for the %ILocationProviderListener interface.
  21 *
  22 * This header file contains the declarations of the %ILocationProviderListener interface.
  23 */
  24
  25 #ifndef _FLOC_ILOCATION_PROVIDER_LISTENER_H_
  26 #define _FLOC_ILOCATION_PROVIDER_LISTENER_H_
  27
  28 #include <FBaseRtIEventListener.h>
  29 #include <FLocTypes.h>
  30
  31 namespace Tizen { namespace Locations
  32 {
  33
  34 class Location;
  35
  36 /**
  37 * @interface    ILocationProviderListener
  38 * @brief        This interface defines listener interfaces to get asynchronous notifications from the location provider.
  39 *
  40 * @since 2.0
  41 *
  42 * The %ILocationProviderListener interface defines listener interfaces to get asynchronous notifications from the location provider.
  43 * An application should implement this listener interface and construct the location provider with the listener
  44 * to get the asynchronous notifications for the location updates and region monitoring requests.
  45 *
  46 * @see          LocationProvider
  47 */
  48 class _OSP_EXPORT_ ILocationProviderListener
  49         : virtual public Tizen::Base::Runtime::IEventListener
  50 {
  51 public:
  52         /**
  53         * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called
  54         * when the destructor of this interface is called.
  55         *
  56         * @since 2.0
  57         */
  58         virtual ~ILocationProviderListener(void)  {}
  59
  60         /**
  61         * Called when the location update is running.
  62         *
  63         * The location update is started when an application calls the LocationProvider::StartLocationUpdatesByInterval() or LocationProvider::StartLocationUpdatesByDistance() methods.
  64         *
  65         * Note that, the updated locations may not always fall into the requested accuracy level that the application has specified in the criteria.
  66         * The application is able to filter out less accurate locations by checking the location accuracy with the Location::GetHorizontalAccuracy() method
  67         * if it matters to the application.
  68         *
  69         * During updating locations, along with changes in the location's accuracy, changes in the service status are also notified.
  70         *
  71         * @since 2.0
  72         *
  73         * @param[in]    location        The location to update
  74         * @remarks      An application should implement this method when it requests for the location updates and wants to handle the updated locations.
  75         * @see          OnAccuracyChanged()
  76         * @see          OnLocationUpdateStatusChanged()
  77         */
  78         virtual void OnLocationUpdated(const Tizen::Locations::Location& location) { }
  79
  80         /**
  81         * Called when the location provider detects a movement entering into the registered region.
  82         *
  83         * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and is identified by the region ID.
  84         *
  85         * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified.
  86         *
  87         * @since 2.0
  88         *
  89         * @param[in]    regionId        The ID for the registered region
  90         * @remarks      An application should implement this method when it requests for the region monitoring and wants to handle the movement into the region.
  91         * @see          OnAccuracyChanged()
  92         * @see          OnRegionMonitoringStatusChanged()
  93         */
  94         virtual void OnRegionEntered(Tizen::Locations::RegionId regionId) { }
  95
  96         /**
  97         * Called when the location provider detects a movement leaving from the registered region.
  98         *
  99         * A region is registered for monitoring by calling LocationProvider::AddMonitoringRegion() and identified by the region ID.
 100         *
 101         * While monitoring regions, the changes in the location's accuracy and the changes in the service status are notified.
 102         *
 103         * @since 2.0
 104         *
 105         * @param[in]    regionId        The ID for the registered region
 106         * @remarks      An application should implement this method when it requests the region monitoring and wants to handle the movement out of the region.
 107         * @see          OnAccuracyChanged()
 108         * @see          OnRegionMonitoringStatusChanged()
 109         */
 110         virtual void OnRegionLeft(Tizen::Locations::RegionId regionId) { }
 111
 112         /**
 113         * Called when the service status of the location updates change.
 114         *
 115         * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service.
 116         *
 117         * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it
 118         * cannot fix the current location due to poor circumstances such as weak radio for positioning.
 119         * When this status continues for a fairly long time, it is recommended to cancel the request. The request should be run after some time in order to avoid excessive battery consumption.
 120         *
 121         * When the user withdraws the permission for an application to use the location information, the status changes to
 122         * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application.
 123         * In that case, the application might ask the user to grant permission to continue the aborted service
 124         * or to finalize all resources for the location provider.
 125         *
 126         * The status @c LOC_SVC_STATUS_PAUSED is displayed when the location provider pauses the ongoing service. This happens when the application requests for the location updates without keeping the location updates awake. The status will be changed to others
 127         * once the location provider resumes the paused service.
 128         *
 129         * Note that, the application can get notifications about the location updates and accuracy changes
 130         * only when the service status is @c LOC_SVC_STATUS_RUNNING.
 131         *
 132         * @since 2.0
 133         *
 134         * @param[in]    status  The service status of the location updates
 135         * @remarks      An application should implement this method when it requests for the location updates and wants to handle status changes of the service.
 136         */
 137         virtual void OnLocationUpdateStatusChanged(Tizen::Locations::LocationServiceStatus status) { }
 138
 139
 140         /**
 141         * Called when the service status of the region monitoring changes.
 142         *
 143         * The status changes to @c LOC_SVC_STATUS_RUNNING, when the location provider successfully runs the requested service.
 144         *
 145         * The status changes to @c LOC_SVC_STATUS_NOT_FIXED, when the location provider is not able to run the requested service because it
 146         * cannot fix the location that is suitable for monitoring the regions.
 147         *
 148         * When the user withdraws the permission for an application to use the location information, the status changes to
 149         * @c LOC_SVC_STATUS_DENIED and the location provider stops all ongoing services to the application.
 150         * In that case, the application might ask the user to grant permission to continue the aborted service
 151         * or to finalize all resources for the location provider.
 152         *
 153         * Note that, the application can get notifications about the movement around regions and accuracy changes
 154         * only when the service status is @c LOC_SVC_STATUS_RUNNING.
 155         *
 156         * @since 2.0
 157         *
 158         * @param[in]    status  The service status of the region monitoring
 159         * @remarks      An application should implement this method when it requests for the region monitoring and wants to handle status changes of the service.
 160         */
 161         virtual void OnRegionMonitoringStatusChanged(Tizen::Locations::LocationServiceStatus status) { }
 162
 163
 164         /**
 165         * Called when the accuracy level of the location changes.
 166         *
 167         * The location provider tries to provide accurate location services as specified in the criteria,
 168         * but the location provided by location provider may not always fall into the requested accuracy level.
 169         * The %OnAccuracyChanged() listener method is called whenever the current accuracy of the location provided by location provider is changed.
 170         *
 171         * The accuracy changes to @c LOC_ACCURACY_INVALID when the location provider is not running any services in @c LOC_SVC_STATUS_RUNNING
 172         * status.
 173         *
 174         * @since 2.0
 175         *
 176         * @param[in]    accuracy        The accuracy of the location
 177         */
 178         virtual void OnAccuracyChanged(Tizen::Locations::LocationAccuracy accuracy) = 0;
 179
 180 protected:
 181         //
 182         //This method is for internal use only. Using this method can cause behavioral, security-related,
 183         //and consistency-related issues in the application.
 184         //
 185         virtual void ILocationProviderListener_Reserved1(void) { }
 186
 187         //
 188         //This method is for internal use only. Using this method can cause behavioral, security-related,
 189         //and consistency-related issues in the application.
 190         //
 191         virtual void ILocationProviderListener_Reserved2(void) { }
 192
 193         //
 194         //This method is for internal use only. Using this method can cause behavioral, security-related,
 195         //and consistency-related issues in the application.
 196         //
 197         virtual void ILocationProviderListener_Reserved3(void) { }
 198 }; // ILocationProviderListener
 199 }} // Tizen::Locations
 200 #endif // _FLOC_ILOCATION_PROVIDER_LISTENER_H_