src/Tizen.Maps/Tizen.Maps/MapService.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 using System.Threading.Tasks;
  20
  21 namespace Tizen.Maps
  22 {
  23     /// <summary>
  24     /// Map service class for service request.
  25     /// </summary>
  26     /// <since_tizen> 3 </since_tizen>
  27     public partial class MapService : IDisposable
  28     {
  29         internal Interop.ServiceHandle handle;
  30
  31         private PlaceFilter _filter;
  32         private SearchPreference _searchPreference;
  33
  34         private static List<string> s_providers;
  35         private string _serviceProvider;
  36
  37
  38         /// <summary>
  39         /// Creates a new maps service object for given service provider.
  40         /// </summary>
  41         /// <since_tizen> 3 </since_tizen>
  42         /// <param name="serviceProvider">A string representing the name of the map service provider.</param>
  43         /// <param name="serviceProviderKey">A string representing a certificate key to use the map service provider.</param>
  44         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
  45         /// <privilege>http://tizen.org/privilege/network.get</privilege>
  46         /// <exception cref="System.NotSupportedException">Thrown when the required feature is not supported.</exception>
  47         /// <exception cref="System.ArgumentException">Thrown when parameters are invalid.</exception>
  48         /// <exception cref="System.InvalidOperationException">Thrown when a native operation failed to allocate memory and connect to the service.</exception>
  49         /// <exception cref="System.UnauthorizedAccessException">Thrown when application does not have some privilege to access this method.</exception>
  50         public MapService(string serviceProvider, string serviceProviderKey)
  51         {
  52             _serviceProvider = serviceProvider;
  53             handle = new Interop.ServiceHandle(serviceProvider);
  54             ProviderKey = serviceProviderKey;
  55             PlaceSearchFilter = new PlaceFilter();
  56             Preferences = new SearchPreference();
  57         }
  58
  59         /// <summary>
  60         /// Destroy the MapService object.
  61         /// </summary>
  62         ~MapService()
  63         {
  64             Dispose(false);
  65         }
  66
  67         /// <summary>
  68         /// Gets the list of available map service providers.
  69         /// </summary>
  70         /// <since_tizen> 3 </since_tizen>
  71         /// <value>The list of map service providers.</value>
  72         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
  73         /// <exception cref="System.NotSupportedException">Thrown when the required feature is not supported.</exception>
  74         /// <exception cref="System.UnauthorizedAccessException">Thrown when application does not have privilege to access this property.</exception>
  75         public static IEnumerable<string> Providers
  76         {
  77             get
  78             {
  79                 if (s_providers != null) return s_providers;
  80
  81                 s_providers = new List<string>();
  82                 Interop.ServiceHandle.ForeachProvider(provider => s_providers.Add(provider));
  83                 return s_providers;
  84             }
  85         }
  86
  87         /// <summary>
  88         /// Gets the name of the map service provider.
  89         /// </summary>
  90         /// <since_tizen> 3 </since_tizen>
  91         public string Provider { get { return _serviceProvider; } }
  92
  93         /// <summary>
  94         /// Gets a user consent for the map service provider
  95         /// </summary>
  96         /// <since_tizen> 4 </since_tizen>
  97         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
  98         public bool UserConsented
  99         {
 100             get
 101             {
 102                 return handle.UserConsented;
 103             }
 104         }
 105
 106         /// <summary>
 107         /// Gets and sets a string representing keys for the map service provider.
 108         /// </summary>
 109         /// <since_tizen> 3 </since_tizen>
 110         /// <remarks>Typically, the provider key is issued by each maps provider after signing up for a plan in the website.
 111         /// Depending on the plan and its provider which you have signed, you might have to pay for the network traffic.</remarks>
 112         public string ProviderKey
 113         {
 114             get
 115             {
 116                 return handle.ProviderKey;
 117             }
 118             set
 119             {
 120                 handle.ProviderKey = value;
 121             }
 122         }
 123
 124         /// <summary>
 125         /// Gets and sets a filter used for the place search result.
 126         /// </summary>
 127         /// <since_tizen> 3 </since_tizen>
 128         public PlaceFilter PlaceSearchFilter
 129         {
 130             get
 131             {
 132                 return _filter;
 133             }
 134             set
 135             {
 136                 if (value != null)
 137                 {
 138                     _filter = value;
 139                 }
 140             }
 141         }
 142
 143         /// <summary>
 144         /// Gets the search preferences used for <see cref="GeocodeRequest"/> or <see cref="ReverseGeocodeRequest"/>.
 145         /// </summary>
 146         /// <since_tizen> 3 </since_tizen>
 147         public IGeocodePreference GeocodePreferences
 148         {
 149             get
 150             {
 151                 return Preferences as IGeocodePreference;
 152             }
 153         }
 154
 155         /// <summary>
 156         /// Gets the search preferences used for <see cref="PlaceSearchRequest"/>.
 157         /// </summary>
 158         /// <since_tizen> 3 </since_tizen>
 159         public IPlaceSearchPreference PlaceSearchPreferences
 160         {
 161             get
 162             {
 163                 return Preferences as IPlaceSearchPreference;
 164             }
 165         }
 166
 167         /// <summary>
 168         /// Gets the search preferences used for <see cref="RouteSearchRequest"/>.
 169         /// </summary>
 170         /// <since_tizen> 3 </since_tizen>
 171         public IRouteSearchPreference RouteSearchPreferences
 172         {
 173             get
 174             {
 175                 return Preferences as IRouteSearchPreference;
 176             }
 177         }
 178
 179         /// <summary>
 180         /// Gets and sets the search preferences.
 181         /// </summary>
 182         /// <since_tizen> 3 </since_tizen>
 183         public SearchPreference Preferences
 184         {
 185             get
 186             {
 187                 if (_searchPreference == null)
 188                 {
 189                     _searchPreference = new SearchPreference(handle.Preferences);
 190                 }
 191                 return _searchPreference;
 192             }
 193             set
 194             {
 195                 if (value != null)
 196                 {
 197                     handle.Preferences = value.handle;
 198                     _searchPreference = value;
 199                 }
 200             }
 201         }
 202
 203         /// <summary>
 204         /// Gets the user's consent to use maps data.
 205         /// </summary>
 206         /// <since_tizen> 4 </since_tizen>
 207         /// <returns>Returns true if user agreed that the application can use maps data, otherwise false.</returns>
 208         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
 209         /// <exception cref="System.NotSupportedException">Thrown when the required feature is not supported.</exception>
 210         /// <exception cref="System.UnauthorizedAccessException">Thrown when application does not have some privilege to access this method.</exception>
 211         public async Task<bool> RequestUserConsent()
 212         {
 213             TaskCompletionSource<bool> tcs = new TaskCompletionSource<bool>();
 214             Interop.RequestUserConsentwithHandleCallback cb = (consented, userData) =>
 215             {
 216                 tcs.TrySetResult(consented);
 217             };
 218
 219             var err = handle.RequestUserConsent(cb, IntPtr.Zero);
 220             if (err.IsFailed())
 221             {
 222                 tcs.TrySetException(err.GetException("Failed to get user consent"));
 223             }
 224             return await tcs.Task.ConfigureAwait(false);
 225         }
 226
 227         /// <summary>
 228         /// Checks if the maps service supports the given request.
 229         /// </summary>
 230         /// <since_tizen> 3 </since_tizen>
 231         /// <param name="type">Request type to check</param>
 232         /// <returns>Returns true if the maps service supports a request, otherwise false.</returns>
 233         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
 234         /// <exception cref="System.NotSupportedException">Thrown when the required feature is not supported.</exception>
 235         /// <exception cref="System.UnauthorizedAccessException">Thrown when application does not have some privilege to access this method.</exception>
 236         public bool IsSupported(ServiceRequestType type)
 237         {
 238             bool result;
 239             var err = handle.IsServiceSupported((Interop.ServiceType)type, out result);
 240             err.WarnIfFailed($"Failed to get if {type} is supported");
 241             return (err.IsSuccess()) ? result : false;
 242         }
 243
 244         /// <summary>
 245         /// Checks if the maps service supports a given data feature.
 246         /// </summary>
 247         /// <since_tizen> 3 </since_tizen>
 248             /// <param name="data">Data feature to check.</param>
 249         /// <returns>Returns true if the maps service supports a data feature, otherwise false.</returns>
 250         /// <privilege>http://tizen.org/privilege/mapservice</privilege>
 251         /// <exception cref="System.NotSupportedException">Thrown when the required feature is not supported.</exception>
 252         /// <exception cref="System.UnauthorizedAccessException">Thrown when application does not have some privilege to access this method.</exception>
 253         public bool IsSupported(ServiceData data)
 254         {
 255             bool result;
 256             var err = handle.IsDataSupported((Interop.ServiceData)data, out result);
 257             err.WarnIfFailed($"Failed to get if {data} data is supported");
 258             return (err.IsSuccess()) ? result : false;
 259         }
 260
 261         /// <summary>
 262         /// Creates a geocode search request for the given free-formed address string.
 263         /// </summary>
 264         /// <since_tizen> 3 </since_tizen>
 265         /// <param name="address">A string representing free-formed address.</param>
 266         /// <returns>Returns a GeocodeRequest object created with an address string.</returns>
 267         public GeocodeRequest CreateGeocodeRequest(string address)
 268         {
 269             return new GeocodeRequest(this, address);
 270         }
 271
 272         /// <summary>
 273         /// Creates a geocode search request for the given free-formed address string, within the specified boundary.
 274         /// </summary>
 275         /// <since_tizen> 3 </since_tizen>
 276         /// <param name="address">A string representing the free-formed address.</param>
 277         /// <param name="boundary">An instance of Area object representing the interested area.</param>
 278         /// <seealso cref="Area"/>
 279         /// <returns>Returns a GeocodeRequest object created with an address string and a specified boundary.</returns>
 280         public GeocodeRequest CreateGeocodeRequest(string address, Area boundary)
 281         {
 282             return new GeocodeRequest(this, address, boundary);
 283         }
 284
 285         /// <summary>
 286         /// Creates a geocode search request for the given structured address.
 287         /// </summary>
 288         /// <since_tizen> 3 </since_tizen>
 289         /// <param name="address">A string representing the address of interest.</param>
 290         /// <returns>Returns a GeocodeRequest object created with a structured address.</returns>
 291         public GeocodeRequest CreateGeocodeRequest(PlaceAddress address)
 292         {
 293             return new GeocodeRequest(this, address);
 294         }
 295
 296         /// <summary>
 297         /// Creates a reverse geocode search request for the given latitude and longitude.
 298         /// </summary>
 299         /// <since_tizen> 3 </since_tizen>
 300         /// <param name="latitude">Latitude of the interested place.</param>
 301         /// <param name="longitude">Longitude of the interested place.</param>
 302         /// <returns>Returns a ReverseGeocodeRequest object created with the location coordinates.</returns>
 303         public ReverseGeocodeRequest CreateReverseGeocodeRequest(double latitude, double longitude)
 304         {
 305             return new ReverseGeocodeRequest(this, latitude, longitude);
 306         }
 307
 308         /// <summary>
 309         /// Creates a reverse geocode search request for the given position coordinates list.
 310         /// </summary>
 311         /// <since_tizen> 3 </since_tizen>
 312         /// <param name="coordinates">Coordinates list with [2 ~ 100] coordinates.</param>
 313         /// <returns>Returns a MultiReverseGeocodeRequest object created with a list of location coordinates.</returns>
 314         public MultiReverseGeocodeRequest CreateMultiReverseGeocodeRequest(IEnumerable<Geocoordinates> coordinates)
 315         {
 316             return new MultiReverseGeocodeRequest(this, coordinates);
 317         }
 318
 319         /// <summary>
 320         /// Creates a route search request for the origin and destination points.
 321         /// </summary>
 322         /// <since_tizen> 3 </since_tizen>
 323         /// <param name="from">Starting point.</param>
 324         /// <param name="to">Destination.</param>
 325         /// <returns>Returns a RouteSearchRequest object created with the origin and destination coordinates.</returns>
 326         public RouteSearchRequest CreateRouteSearchRequest(Geocoordinates from, Geocoordinates to)
 327         {
 328             return new RouteSearchRequest(this, from, to);
 329         }
 330
 331         /// <summary>
 332         /// Creates a place search request for a specified search radius around a given coordinates position.
 333         /// </summary>
 334         /// <since_tizen> 3 </since_tizen>
 335         /// <param name="coordinates">Geographical coordinates of the center.</param>
 336         /// <param name="distance">A double value representing the radius of an area to search places.</param>
 337         /// <returns>Returns a PlaceSearchRequest object created with the location coordinates and search radius.</returns>
 338         public PlaceSearchRequest CreatePlaceSearchRequest(Geocoordinates coordinates, int distance)
 339         {
 340             return new PlaceSearchRequest(this, coordinates, distance);
 341         }
 342
 343         /// <summary>
 344         /// Creates a place search request for places within a specified boundary.
 345         /// </summary>
 346         /// <since_tizen> 3 </since_tizen>
 347         /// <param name="boundary">An instance of Area object representing and area to search interested places.</param>
 348         /// <returns>Returns a PlaceSearchRequest object created with a specified boundary.</returns>
 349         public PlaceSearchRequest CreatePlaceSearchRequest(Area boundary)
 350         {
 351             return new PlaceSearchRequest(this, boundary);
 352         }
 353
 354         /// <summary>
 355         /// Creates a place search request for a free-formed address within the boundary.
 356         /// </summary>
 357         /// <since_tizen> 3 </since_tizen>
 358         /// <param name="address">A string which represents a free-formed address.</param>
 359         /// <param name="boundary">An instance of area object representing an area to search interested places.</param>
 360         /// <returns>Returns a PlaceSearchRequest object created with an address string and a specified boundary.</returns>
 361         public PlaceSearchRequest CreatePlaceSearchRequest(string address, Area boundary)
 362         {
 363             return new PlaceSearchRequest(this, address, boundary);
 364         }
 365
 366         #region IDisposable Support
 367         private bool _disposedValue = false;
 368
 369         /// <summary>
 370         /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
 371         /// </summary>
 372         /// <param name="disposing">If true, managed and unmanaged resources can be disposed, otherwise only unmanaged resources can be disposed.</param>
 373         /// <since_tizen> 3 </since_tizen>
 374         protected virtual void Dispose(bool disposing)
 375         {
 376             if (!_disposedValue)
 377             {
 378                 if (disposing)
 379                 {
 380                     _filter?.Dispose();
 381                     _searchPreference?.Dispose();
 382                 }
 383                 handle?.Dispose();
 384                 _disposedValue = true;
 385             }
 386         }
 387
 388         /// <summary>
 389         /// Releases all the resources used by this object.
 390         /// </summary>
 391         /// <since_tizen> 3 </since_tizen>
 392         public void Dispose()
 393         {
 394             Dispose(true);
 395             GC.SuppressFinalize(this);
 396         }
 397         #endregion
 398     }
 399 }