src/Tizen.Location.Geofence/Tizen.Location.Geofence/VirtualPerimeter.cs

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 using System;
  18 using System.Collections.Generic;
  19
  20 namespace Tizen.Location.Geofence
  21 {
  22     /// <summary>
  23     /// Allows to create a virtual fence as Geofence using GeofenceManager instance.
  24     /// User can manage all the geofence/place related data and events.
  25     /// </summary>
  26     /// <since_tizen>3</since_tizen>
  27     public class VirtualPerimeter
  28     {
  29         private IntPtr Handle;
  30
  31         /// <summary>
  32         /// Creates a VirtualPerimeter which can be used to create virtual fence.
  33         /// </summary>
  34         /// <since_tizen>3</since_tizen>
  35         /// <param name="manager">GeofenceManager instance.</param>
  36         /// <exception cref="ArgumentException"> Incase of invlid parameter.</exception>
  37         public VirtualPerimeter(GeofenceManager manager)
  38         {
  39             if (manager == null)
  40             {
  41                 throw GeofenceErrorFactory.CreateException(GeofenceError.InvalidParameter, "Invalid GeofenceManager instance");
  42             }
  43             else
  44             {
  45                 Handle = manager.Handle;
  46             }
  47         }
  48
  49         /// <summary>
  50         /// Creates a new place for geofencing service.
  51         /// </summary>
  52         /// <since_tizen>3</since_tizen>
  53         /// <param name="name">A place name to be created.</param>
  54         /// <returns>The place id to be newly created on success.</returns>
  55         /// <privilege>http://tizen.org/privilege/location</privilege>
  56         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
  57         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
  58         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
  59         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
  60         public int AddPlaceName(string name)
  61         {
  62             int placeId = 0;
  63             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.AddPlace(Handle, name, out placeId);
  64             if (ret != GeofenceError.None)
  65             {
  66                 throw GeofenceErrorFactory.CreateException(ret, "Failed to add place to Geofence Manager for " + name);
  67             }
  68
  69             return placeId;
  70         }
  71
  72         /// <summary>
  73         /// Updates the place name of a given place id.
  74         /// </summary>
  75         /// <since_tizen>3</since_tizen>
  76         /// <param name="placeId">The specified place id.</param>
  77         /// <param name="name">A new place name of the place id.</param>
  78         /// <privilege>http://tizen.org/privilege/location</privilege>
  79         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
  80         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
  81         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
  82         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
  83         public void UpdatePlace(int placeId, string name)
  84         {
  85             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.UpdatePlace(Handle, placeId, name);
  86             if (ret != GeofenceError.None)
  87             {
  88                 throw GeofenceErrorFactory.CreateException(ret, "Failed to update place to Geofence Manager for " + placeId);
  89             }
  90         }
  91
  92         /// <summary>
  93         /// Removes the specific place for geofencing service.
  94         /// </summary>
  95         /// <since_tizen>3</since_tizen>
  96         /// <param name="placeId">The specified place id.</param>
  97         /// <privilege>http://tizen.org/privilege/location</privilege>
  98         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
  99         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 100         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 101         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 102         public void RemovePlace(int placeId)
 103         {
 104             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.RemovePlace(Handle, placeId);
 105             if (ret != GeofenceError.None)
 106             {
 107                 throw GeofenceErrorFactory.CreateException(ret, "Failed to remove place from Geofence Manager for " + placeId);
 108             }
 109         }
 110
 111         /// <summary>
 112         /// Adds a geofence for a given geofence manager.
 113         /// </summary>
 114         /// <since_tizen>3</since_tizen>
 115         /// <param name="fence">The Geofence instance to be added.</param>
 116         /// <returns>The geofence id to be newly created on success.</returns>
 117         /// <remarks> The retun value will always be a number greater than zero.</remarks>
 118         /// <privilege>http://tizen.org/privilege/location</privilege>
 119         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
 120         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 121         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 122         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 123         public int AddGeofence(Fence fence)
 124         {
 125             int fenceId = 0;
 126             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.AddFence(Handle, fence.Handle, out fenceId);
 127             if (ret != GeofenceError.None)
 128             {
 129                 throw GeofenceErrorFactory.CreateException(ret, "Failed to add fence to Geofence Manager ");
 130             }
 131
 132             return fenceId;
 133         }
 134
 135         /// <summary>
 136         /// Removes a geofence with a given geofence id.
 137         /// </summary>
 138         /// <since_tizen>3</since_tizen>
 139         /// <param name="fenceId">The specified geofence id.</param>
 140         /// <privilege>http://tizen.org/privilege/location</privilege>
 141         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
 142         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 143         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 144         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 145         public void RemoveGeofence(int fenceId)
 146         {
 147             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.RemoveFence(Handle, fenceId);
 148             if (ret != GeofenceError.None)
 149             {
 150                 throw GeofenceErrorFactory.CreateException(ret, "Failed to remove geofence from Geofence Manager for " + fenceId);
 151             }
 152         }
 153
 154         /// <summary>
 155         /// Gets the name of place.
 156         /// </summary>
 157         /// <since_tizen>3</since_tizen>
 158         /// <param name="placeId">The place id.</param>
 159         /// <returns>The name of the place.</returns>
 160         /// <privilege>http://tizen.org/privilege/location</privilege>
 161         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
 162         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 163         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 164         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 165         public string GetPlaceName(int placeId)
 166         {
 167             string name = "";
 168             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.GetPlaceName(Handle, placeId, out name);
 169             if (ret != GeofenceError.None)
 170             {
 171                 throw GeofenceErrorFactory.CreateException(ret, "Failed to get placenamefrom Geofence Manager for " + placeId);
 172             }
 173
 174             return name;
 175         }
 176
 177         /// <summary>
 178         /// Retrieves a list of places registered in the specified geofence manager.
 179         /// </summary>
 180         /// <since_tizen>3</since_tizen>
 181         /// <returns>list of places registered as PlaceData instance list.</returns>
 182         /// <privilege>http://tizen.org/privilege/location</privilege>
 183         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 184         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 185         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 186         public IEnumerable<PlaceData> GetPlaceDataList()
 187         {
 188             List<PlaceData> places = new List<PlaceData>();
 189             Interop.VirtualPerimeter.ForEachPlaceListCallback placeCallback = (int placeId, string name, int index, int count, IntPtr data) =>
 190             {
 191                 if (count != 0)
 192                 {
 193                     PlaceData place = new PlaceData(placeId, name, index, count);
 194                     places.Add(place);
 195                 }
 196                 return true;
 197             };
 198
 199             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.GetForEachPlaceList(Handle, placeCallback, IntPtr.Zero);
 200             if (ret != GeofenceError.None)
 201             {
 202                 throw GeofenceErrorFactory.CreateException(ret, "Failed to get Places list from Geofence Manager ");
 203             }
 204
 205             return places;
 206         }
 207
 208         /// <summary>
 209         /// Retrieves a list of fences registered in the specified geofence manager.
 210         /// </summary>
 211         /// <since_tizen>3</since_tizen>
 212         /// <returns>list of FenceData instances registred for each Geofence.</returns>
 213         /// <privilege>http://tizen.org/privilege/location</privilege>
 214         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 215         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 216         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 217         public IEnumerable<FenceData> GetFenceDataList()
 218         {
 219             List<FenceData> fences = new List<FenceData>();
 220             Interop.VirtualPerimeter.ForEachFenceListCallback callback = (int fenceId, IntPtr handle, int index, int count, IntPtr data) =>
 221             {
 222                 if (count != 0)
 223                 {
 224                     FenceData fence = new FenceData(fenceId, handle, index, count);
 225                     fences.Add(fence);
 226                 }
 227                 return true;
 228             };
 229
 230             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.GetForEachFenceList(Handle, callback, IntPtr.Zero);
 231             if (ret != GeofenceError.None)
 232             {
 233                 throw GeofenceErrorFactory.CreateException(ret, "Failed to get Geofence list from Geofence Manager ");
 234             }
 235
 236             return fences;
 237         }
 238
 239         /// <summary>
 240         /// Retrieves a list of fences registered in the specified place.
 241         /// </summary>
 242         /// <since_tizen>3</since_tizen>
 243         /// <param name="placeId"> The place id.</param>
 244         /// <returns>list of FenceData instances registred for each Geofence for specified place.</returns>
 245         /// <privilege>http://tizen.org/privilege/location</privilege>
 246         /// <exception cref="ArgumentException">Incase of Invalid parameter.</exception>
 247         /// <exception cref="InvalidOperationException">Incase of any System error.</exception>
 248         /// <exception cref="UnauthorizedAccessException">Incase of Privileges are not defined.</exception>
 249         /// <exception cref="NotSupportedException">Incase of Geofence is not supported.</exception>
 250         public IEnumerable<FenceData> GetGeofenceDataListByPlaceId(int placeId)
 251         {
 252             List<FenceData> fences = new List<FenceData>();
 253             Interop.VirtualPerimeter.ForEachFenceListCallback callback = (int fenceId, IntPtr handle, int index, int count, IntPtr data) =>
 254             {
 255                 FenceData fence = new FenceData(fenceId, handle, index, count);
 256                 fences.Add(fence);
 257                 return true;
 258             };
 259
 260             GeofenceError ret = (GeofenceError)Interop.VirtualPerimeter.GetForEachPlaceFenceList(Handle, placeId, callback, IntPtr.Zero);
 261             if (ret != GeofenceError.None)
 262             {
 263                 throw GeofenceErrorFactory.CreateException(ret, "Failed to get Geofence list from Geofence Manager for " + placeId);
 264             }
 265
 266             return fences;
 267         }
 268     }
 269 }