src/Tizen.Applications.WatchfaceComplication/Tizen.Applications/ComplicationProvider.cs

   1 /*
   2  * Copyright (c) 2018 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.Text;
  20
  21 namespace Tizen.Applications.WatchfaceComplication
  22 {
  23     /// <summary>
  24     /// Represents the ComplicationProvider class for the complication provider service application.
  25     /// </summary>
  26     /// <since_tizen> 6 </since_tizen>
  27     public abstract class ComplicationProvider : IDisposable
  28     {
  29         private string _providerId;
  30         private bool _disposed = false;
  31         private const string LogTag = "WatchfaceComplication";
  32
  33         /// <summary>
  34         /// Initializes the ComplicationProvider class.
  35         /// </summary>
  36         /// <param name="providerId">The id of the complication provider.</param>
  37         /// <privilege>http://tizen.org/privilege/datasharing</privilege>
  38         /// <exception cref="ArgumentException">Thrown when providerId is invalid.</exception>
  39         /// <exception cref="InvalidOperationException">Thrown when the method failed due to invalid operation.</exception>
  40         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
  41         /// <exception cref="UnauthorizedAccessException">Thrown when the application does not have privilege to access this method.</exception>
  42         /// <example>
  43         /// <code>
  44         /// public class MyComplicationProvider : ComplicationProvider
  45         /// {
  46         ///     public MyComplicationProvider(string providerId)
  47         ///      : base(providerId)
  48         ///     {
  49         ///     }
  50         ///     protected override void OnDataUpdateRequested(string reqestAppId, ComplicationTypes type, Bundle contextData)
  51         ///     {
  52         ///     }
  53         /// }
  54         /// </code>
  55         /// </example>
  56         /// <since_tizen> 6 </since_tizen>
  57         protected ComplicationProvider(string providerId)
  58         {
  59             ComplicationError err = Interop.WatchfaceComplication.AddUpdateRequestedCallback(providerId, DataUpdateRequested, IntPtr.Zero);
  60             if (err != ComplicationError.None)
  61                 ErrorFactory.ThrowException(err, "fail to create provider");
  62             _providerId = providerId;
  63         }
  64
  65         /// <summary>
  66         /// Destructor of the provider class.
  67         /// </summary>
  68         ~ComplicationProvider()
  69         {
  70             Dispose(false);
  71         }
  72
  73         /// <summary>
  74         /// Gets the provider ID.
  75         /// </summary>
  76         /// <since_tizen> 6 </since_tizen>
  77         public string Id
  78         {
  79             get
  80             {
  81                 return _providerId;
  82             }
  83         }
  84
  85         private void DataUpdateRequested(string providerId, string reqAppId, ComplicationTypes type,
  86             IntPtr context, IntPtr sharedData, IntPtr userData)
  87         {
  88             Bundle bContext = new Bundle(new SafeBundleHandle(context, false));
  89             ComplicationData data = OnDataUpdateRequested(reqAppId, type, bContext);
  90             if (data == null)
  91             {
  92                 Log.Error(LogTag, "null complication data");
  93                 return;
  94             }
  95             ComplicationError err = data.UpdateSharedData(sharedData);
  96             if (err != ComplicationError.None)
  97                 Log.Error(LogTag, "Set complication data error : " + err);
  98         }
  99
 100         /// <summary>
 101         /// Overrides this method to handle the behavior when the complication data update request event comes from watchface complication.
 102         /// </summary>
 103         /// <param name="reqestAppId">The application ID of application which sent update request.</param>
 104         /// <param name="type">The requested type.</param>
 105         /// <param name="contextData">The complication's context which is set by complication setup application.</param>
 106         /// <returns>The requested ComplicationData</returns>
 107         /// <since_tizen> 6 </since_tizen>
 108         protected abstract ComplicationData OnDataUpdateRequested(string reqestAppId, ComplicationTypes type, Bundle contextData);
 109
 110         /// <summary>
 111         /// Emits the update event for complications.
 112         /// </summary>
 113         /// <privilege>http://tizen.org/privilege/datasharing</privilege>
 114         /// <exception cref="UnauthorizedAccessException">Thrown when the application does not have privilege to access this method.</exception>
 115         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
 116         /// <since_tizen> 6 </since_tizen>
 117         public void NotifyUpdate()
 118         {
 119             ComplicationError err = Interop.WatchfaceComplication.NotifyUpdate(_providerId);
 120             if (err != ComplicationError.None)
 121                 ErrorFactory.ThrowException(err, "fail to notify");
 122         }
 123
 124         /// <summary>
 125         /// Gets the received event type.
 126         /// </summary>
 127         /// <param name="recvAppCtrl">The appcontrol received event args.</param>
 128         /// <exception cref="ArgumentException">Thrown when the invalid parameter is passed.</exception>
 129         /// <exception cref="InvalidOperationException">Thrown when the method failed due to invalid operation.</exception>
 130         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
 131         /// <example>
 132         /// <code>
 133         /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
 134         /// {
 135         ///     EventTypes type = ComplicationProvider.GetEventType(e.ReceivedAppControl);
 136         ///     if (type == EventTypes.EventDoubleTap)
 137         ///     {
 138         ///         // do something
 139         ///     }
 140         ///     base.OnAppControlReceived(e);
 141         /// }
 142         /// </code>
 143         /// </example>
 144         /// <returns>The type of received event</returns>
 145         /// <since_tizen> 6 </since_tizen>
 146         public static EventTypes GetEventType(ReceivedAppControl recvAppCtrl)
 147         {
 148             EventTypes type;
 149             ComplicationError err = Interop.WatchfaceComplication.GetEventType(recvAppCtrl.SafeAppControlHandle, out type);
 150             if (err != ComplicationError.None)
 151                 ErrorFactory.ThrowException(err, "fail to get event");
 152             return type;
 153         }
 154
 155         /// <summary>
 156         /// Gets the received event target provider ID.
 157         /// </summary>
 158         /// <param name="recvAppCtrl">The appcontrol received event args.</param>
 159         /// <exception cref="ArgumentException">Thrown when e is invalid.</exception>
 160         /// <exception cref="InvalidOperationException">Thrown when the method failed due to invalid operation.</exception>
 161         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
 162         /// <example>
 163         /// <code>
 164         /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
 165         /// {
 166         ///     string providerId = ComplicationProvider.GetEventProviderId(e.ReceivedAppControl);
 167         ///     base.OnAppControlReceived(e);
 168         /// }
 169         /// </code>
 170         /// </example>
 171         /// <returns>The target provider ID of received event</returns>
 172         /// <since_tizen> 6 </since_tizen>
 173         public static string GetEventProviderId(ReceivedAppControl recvAppCtrl)
 174         {
 175             string providerId = string.Empty;
 176             ComplicationError err = Interop.WatchfaceComplication.GetEventProviderId(recvAppCtrl.SafeAppControlHandle, out providerId);
 177             if (err != ComplicationError.None && err != ComplicationError.NoData)
 178                 ErrorFactory.ThrowException(err, "fail to get event");
 179             return providerId;
 180         }
 181
 182         /// <summary>
 183         /// Gets the received event target complication type.
 184         /// </summary>
 185         /// <param name="recvAppCtrl">The appcontrol received event args.</param>
 186         /// <exception cref="ArgumentException">Thrown when e is invalid.</exception>
 187         /// <exception cref="InvalidOperationException">Thrown when the method failed due to invalid operation.</exception>
 188         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
 189         /// <example>
 190         /// <code>
 191         /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
 192         /// {
 193         ///     ComplicationTypes type = ComplicationProvider.GetEventComplicationType(e.ReceivedAppControl);
 194         ///     base.OnAppControlReceived(e);
 195         /// }
 196         /// </code>
 197         /// </example>
 198         /// <returns>The target complication type of received event</returns>
 199         /// <since_tizen> 6 </since_tizen>
 200         public static ComplicationTypes GetEventComplicationType(ReceivedAppControl recvAppCtrl)
 201         {
 202             ComplicationTypes type;
 203             ComplicationError err = Interop.WatchfaceComplication.GetEventComplicationType(recvAppCtrl.SafeAppControlHandle, out type);
 204             if (err != ComplicationError.None && err != ComplicationError.NoData)
 205                 ErrorFactory.ThrowException(err, "fail to get complication type");
 206             return type;
 207         }
 208
 209         /// <summary>
 210         /// Gets the received event target complication context.
 211         /// </summary>
 212         /// <param name="recvAppCtrl">The appcontrol received event args.</param>
 213         /// <exception cref="ArgumentException">Thrown when e is invalid.</exception>
 214         /// <exception cref="InvalidOperationException">Thrown when the method failed due to invalid operation.</exception>
 215         /// <exception cref="NotSupportedException">Thrown when the watchface complication is not supported.</exception>
 216         /// <example>
 217         /// <code>
 218         /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
 219         /// {
 220         ///     Bundle context = ComplicationProvider.GetEventContext(e.ReceivedAppControl);
 221         ///     base.OnAppControlReceived(e);
 222         /// }
 223         /// </code>
 224         /// </example>
 225         /// <returns>The context of received event</returns>
 226         /// <since_tizen> 6 </since_tizen>
 227         public static Bundle GetEventContext(ReceivedAppControl recvAppCtrl)
 228         {
 229             SafeBundleHandle bHandle;
 230             ComplicationError err = Interop.WatchfaceComplication.GetEventContext(recvAppCtrl.SafeAppControlHandle, out bHandle);
 231             if (err != ComplicationError.None)
 232             {
 233                 if (err == ComplicationError.NoData)
 234                     return null;
 235                 ErrorFactory.ThrowException(err, "fail to get complication context");
 236             }
 237
 238             return new Bundle(bHandle);
 239         }
 240
 241         /// <summary>
 242         /// Releases the unmanaged resources used by the ComplicationProvider class specifying whether to perform a normal dispose operation.
 243         /// </summary>
 244         /// <param name="disposing">true for a normal dispose operation; false to finalize the handle.</param>
 245         /// <since_tizen> 3 </since_tizen>
 246         protected virtual void Dispose(bool disposing)
 247         {
 248             if (!_disposed)
 249             {
 250                 Interop.WatchfaceComplication.RemoveUpdateRequestedCallback(_providerId, DataUpdateRequested);
 251                 _disposed = true;
 252             }
 253         }
 254
 255         /// <summary>
 256         /// Releases all resources used by the ComplicationProvider class.
 257         /// </summary>
 258         /// <since_tizen> 3 </since_tizen>
 259         public void Dispose()
 260         {
 261             Dispose(true);
 262             GC.SuppressFinalize(this);
 263         }
 264     }
 265 }