src/Tizen.Applications.Notification/Tizen.Applications.Notifications/NotificationManager.cs

   1 /*
   2  * Copyright (c) 2017 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 namespace Tizen.Applications.Notifications
  18 {
  19     using System;
  20     using System.ComponentModel;
  21
  22     /// <summary>
  23     /// NotificationManager class to post, update, delete, and get notification.
  24     /// </summary>
  25     /// <since_tizen> 3 </since_tizen>
  26     public static class NotificationManager
  27     {
  28         /// <summary>
  29         /// Posts a new notification.
  30         /// </summary>
  31         /// <param name="notification">Notification to post.</param>
  32         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
  33         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
  34         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
  35         /// <example>
  36         /// <code>
  37         /// Notification notification = new Notification
  38         /// {
  39         ///     Title = "title",
  40         ///     Content = "content",
  41         ///     Icon = "absolute icon path",
  42         ///     Tag = "first notification"
  43         /// };
  44         ///
  45         /// Notification.AccessorySet accessory = new Notification.AccessorySet
  46         /// {
  47         ///     SoundOption = AccessoryOption.On,
  48         ///     CanVibrate = true
  49         /// };
  50         /// notification.Accessory = accessory;
  51         ///
  52         ///     // do something
  53         ///
  54         /// NotificationManager.Post(notification);
  55         /// </code>
  56         /// </example>
  57         /// <privilege>http://tizen.org/privilege/notification</privilege>
  58         /// <since_tizen> 3 </since_tizen>
  59         public static void Post(Notification notification)
  60         {
  61             if (notification == null)
  62             {
  63                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument to post method");
  64             }
  65
  66             notification.Make();
  67
  68             NotificationError ret = Interop.Notification.Post(notification.Handle);
  69             if (ret != NotificationError.None)
  70             {
  71                 throw NotificationErrorFactory.GetException(ret, "post notification failed");
  72             }
  73
  74             int priv_id, group_id;
  75             Interop.Notification.GetID(notification.Handle, out group_id, out priv_id);
  76             notification.PrivID = priv_id;
  77         }
  78
  79         /// <summary>
  80         /// Updates a posted notification.
  81         /// </summary>
  82         /// <param name="notification">Notification to update.</param>
  83         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
  84         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
  85         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
  86         /// <example>
  87         /// <code>
  88         /// string tag = "first tag";
  89         ///
  90         /// Notification notification = new Notification
  91         /// {
  92         ///     Title = "title",
  93         ///     Content = "content",
  94         ///     Icon = "absolute icon path",
  95         ///     Tag = tag
  96         /// };
  97         ///
  98         /// Notification.AccessorySet accessory = new Notification.AccessorySet
  99         /// {
 100         ///     LedOption = AccessoryOption.On,
 101         ///     VibrationOption = AccessoryOption.Custom,
 102         ///     VibrationPath = "vibration absolute path"
 103         /// }
 104         /// notification.Accessory = accessory;
 105         ///
 106         /// NotificationManager.Post(notification);
 107         ///
 108         ///     // do something
 109         ///
 110         /// Notification loadNotification = NotificationManager.Load(tag);
 111         ///
 112         /// loadNotification.Progress = new ProgressType(ProgressCategory.Percent, 0.0. 100.0);
 113         ///
 114         /// Thread thread = new Thread(new ParameterizedThreadStart(UpdateProgress));
 115         /// thread.IsBackground = true;
 116         /// thread.Start(notification);
 117         ///
 118         ///   ...
 119         ///
 120         /// static void UpdateProgress(Object obj)
 121         /// {
 122         ///     Notification notification = (Notification)obj;
 123         ///
 124         ///     for (double current = 1.0; current &lt;= 100.0; current = current + 1.0)
 125         ///     {
 126         ///         notification.Progress.ProgressCurrent = current;
 127         ///         NotificationManager.Update(notification);
 128         ///         Thread.Sleep(300);
 129         ///     }
 130         /// }
 131         /// </code>
 132         /// </example>
 133         /// <privilege>http://tizen.org/privilege/notification</privilege>
 134         /// <pre>
 135         /// Post method should be called on the notification object.
 136         /// </pre>
 137         /// <since_tizen> 3 </since_tizen>
 138         public static void Update(Notification notification)
 139         {
 140             if (notification == null || notification.Handle == null || notification.Handle.IsInvalid)
 141             {
 142                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument to post method");
 143             }
 144
 145             notification.Make();
 146             NotificationError ret = Interop.Notification.Update(notification.Handle);
 147             if (ret != NotificationError.None)
 148             {
 149                 throw NotificationErrorFactory.GetException(ret, "update notification failed");
 150             }
 151         }
 152
 153         /// <summary>
 154         /// Deletes a posted notification.
 155         /// </summary>
 156         /// <param name="notification">Notification to remove.</param>
 157         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 158         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
 159         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 160         /// <example>
 161         /// <code>
 162         /// Notification notification = new Notification
 163         /// {
 164         ///     Title = "title",
 165         ///     Content = "content",
 166         ///     Icon = "absolute icon path",
 167         ///     Tag = "first notification"
 168         /// };
 169         /// NotificationManager.Post(notification);
 170         ///
 171         ///     // do something
 172         ///
 173         /// NotificationManager.Delete(notification);
 174         /// </code>
 175         /// </example>
 176         /// <privilege>http://tizen.org/privilege/notification</privilege>
 177         /// <pre>
 178         /// Post method should be called on the notification object.
 179         /// </pre>
 180         /// <since_tizen> 3 </since_tizen>
 181         public static void Delete(Notification notification)
 182         {
 183             if (notification == null || notification.Handle == null || notification.Handle.IsInvalid)
 184             {
 185                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument to post method");
 186             }
 187
 188             NotificationError ret = Interop.Notification.Delete(notification.Handle);
 189             if (ret != NotificationError.None)
 190             {
 191                 throw NotificationErrorFactory.GetException(ret, "delete notification failed");
 192             }
 193         }
 194
 195         /// <summary>
 196         /// Removes all posted notifications of calling application.
 197         /// </summary>
 198         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
 199         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 200         /// <example>
 201         /// <code>
 202         /// Notification firstNotification = new Notification
 203         /// {
 204         ///     Title = "title",
 205         ///     Content = "content",
 206         ///     Icon = "absolute icon path",
 207         ///     Tag = "first notification"
 208         /// };
 209         /// NotificationManager.Post(firstNotification);
 210         ///
 211         /// Notification secondNotification = new Notification
 212         /// {
 213         ///     Title = "title",
 214         ///     Content = "content",
 215         ///     Icon = "absolute icon path",
 216         ///     Tag = "second notification"
 217         /// };
 218         /// NotificationManager.Post(secondNotification);
 219         /// NotificationManager.DeleteAll();
 220         /// </code>
 221         /// </example>
 222         /// <privilege>http://tizen.org/privilege/notification</privilege>
 223         /// <since_tizen> 3 </since_tizen>
 224         public static void DeleteAll()
 225         {
 226             NotificationError ret;
 227
 228             ret = Interop.Notification.DeleteAll((int)NotificationType.Basic);
 229             if (ret != NotificationError.None)
 230             {
 231                 throw NotificationErrorFactory.GetException(ret, "delete all notifications failed of Noti type");
 232             }
 233
 234             ret = Interop.Notification.DeleteAll((int)NotificationType.Ongoing);
 235             if (ret != NotificationError.None)
 236             {
 237                 throw NotificationErrorFactory.GetException(ret, "delete all notifications failed of Ongoing type");
 238             }
 239         }
 240
 241         /// <summary>
 242         /// Searches for a posted notification which has the specified tag and has not been deleted yet.
 243         /// </summary>
 244         /// <remarks>
 245         /// Load method should be called only for notifications, which have been posted using the NotificationManager.Post method.
 246         /// If two or more notifications share the same tag, the notification posted most recently is returned.
 247         /// </remarks>
 248         /// <param name="tag">Tag used to query.</param>
 249         /// <returns>Notification Object with specified tag.</returns>
 250         /// <exception cref="ArgumentException">Throwing the same exception when argument is invalid and when the tag does not exist is misleading.</exception>
 251         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 252         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 253         /// <example>
 254         /// <code>
 255         /// Notification notification = new Notification
 256         /// {
 257         ///     Title = "title",
 258         ///     Content = "content",
 259         ///     Icon = "absolute icon path",
 260         ///     Tag = "first notification"
 261         /// };
 262         /// NotificationManager.Post(notification);
 263         ///
 264         ///     // do someting
 265         ///
 266         /// Notification loadNotification = NotificationManager.Load("first notification");
 267         /// </code>
 268         /// </example>
 269         /// <privilege>http://tizen.org/privilege/notification</privilege>
 270         /// <since_tizen> 3 </since_tizen>
 271         public static Notification Load(string tag)
 272         {
 273             IntPtr ptr = IntPtr.Zero;
 274
 275             if (string.IsNullOrEmpty(tag))
 276             {
 277                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid parameter entered");
 278             }
 279
 280             ptr = Interop.Notification.Load(tag);
 281
 282             if (ptr == IntPtr.Zero)
 283             {
 284                 NotificationError ret = (NotificationError)Tizen.Internals.Errors.ErrorFacts.GetLastResult();
 285                 Log.Error(Notification.LogTag, "unable to load Notification : " + ret.ToString());
 286                 if (ret == NotificationError.DbError)
 287                 {
 288                     throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "the tag does not exist");
 289                 }
 290                 else
 291                 {
 292                     throw NotificationErrorFactory.GetException(ret, "unable to load Notification");
 293                 }
 294             }
 295
 296             Notification notification = new Notification
 297             {
 298                 Handle = new NotificationSafeHandle(ptr, true)
 299             }.Build();
 300
 301             return notification;
 302         }
 303
 304         /// <summary>
 305         /// Saves a notification template to the notification database.
 306         /// </summary>
 307         /// <param name="notification">Notification to save as template.</param>
 308         /// <param name="name">Template name.</param>
 309         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 310         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
 311         /// <exception cref="InvalidOperationException">Thrown when it can't be saved as a template.</exception>
 312         /// <example>
 313         /// <code>
 314         /// Notification notification = new Notification
 315         /// {
 316         ///     Title = "title",
 317         ///     Content = "content",
 318         ///     Icon = "absolute icon path",
 319         ///     Tag = "first notification"
 320         /// };
 321         ///
 322         /// Notification.Accessory accessory = new Notification.Accessory
 323         /// {
 324         ///     LedOption = AccessoryOption.On,
 325         ///     VibrationOption = AccessoryOption.Custom,
 326         ///     VibrationPath = "vibration absolute path"
 327         /// }
 328         /// notification.setAccessory(accessory);
 329         ///
 330         ///     // do something
 331         ///
 332         /// NotificationManager.Post(notification);
 333         ///
 334         /// Notification.LockStyle style = new Notification.LockStyle
 335         /// {
 336         ///     IconPath = "icon path",
 337         ///     ThumbnailPath = "Thumbnail path"
 338         /// }
 339         /// notification.AddStyle(style);
 340         /// NotificationManager.SaveTemplate(notification, "firstTemplate");
 341         /// </code>
 342         /// </example>
 343         /// <privilege>http://tizen.org/privilege/notification</privilege>
 344         /// <since_tizen> 3 </since_tizen>
 345         public static void SaveTemplate(Notification notification, string name)
 346         {
 347             if (notification == null || string.IsNullOrEmpty(name))
 348             {
 349                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument to save template");
 350             }
 351
 352             notification.Make();
 353
 354             NotificationError ret = Interop.Notification.SaveTemplate(notification.Handle, name);
 355             if (ret != NotificationError.None)
 356             {
 357                 throw NotificationErrorFactory.GetException(ret, "save as template failed");
 358             }
 359         }
 360
 361         /// <summary>
 362         /// Loads a notification template from the notification database.
 363         /// </summary>
 364         /// <param name="name">Template name.</param>
 365         /// <returns>Notification Object with inputted template name.</returns>
 366         /// <exception cref="ArgumentException">Throwing the same exception when argument is invalid and when the template does not exist is misleading.</exception>
 367         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 368         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 369         /// <example>
 370         /// <code>
 371         /// Notification notification = new Notification
 372         /// {
 373         ///     Title = "title",
 374         ///     Content = "content",
 375         ///     Icon = "absolute icon path",
 376         ///     Tag = "first notification"
 377         /// };
 378         ///
 379         /// Notification.Accessory accessory = new Notification.Accessory
 380         /// {
 381         ///     LedOption = AccessoryOption.On,
 382         ///     VibrationOption = AccessoryOption.Custom,
 383         ///     VibrationPath = "vibration absolute path"
 384         /// }
 385         /// notification.setAccessory(accessory);
 386         ///
 387         ///     // do something
 388         ///
 389         /// NotificationManager.Post(notification);
 390         ///
 391         /// Notification.LockStyle style = new Notification.LockStyle
 392         /// {
 393         ///     IconPath = "icon path",
 394         ///     ThumbnailPath = "Thumbnail path"
 395         /// }
 396         /// notification.AddStyle(style);
 397         /// NotificationManager.SaveTemplate(notification, "firstTemplate");
 398         /// Notification notificationTemplate = NotificationManager.LoadTemplate("firstTemplate");
 399         /// </code>
 400         /// </example>
 401         /// <privilege>http://tizen.org/privilege/notification</privilege>
 402         /// <since_tizen> 3 </since_tizen>
 403         public static Notification LoadTemplate(string name)
 404         {
 405             IntPtr handle = IntPtr.Zero;
 406
 407             if (string.IsNullOrEmpty(name))
 408             {
 409                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid argument to load template");
 410             }
 411
 412             handle = Interop.Notification.LoadTemplate(name);
 413             if (handle == IntPtr.Zero)
 414             {
 415                 NotificationError ret = (NotificationError)Tizen.Internals.Errors.ErrorFacts.GetLastResult();
 416                 if (ret == NotificationError.DbError)
 417                 {
 418                     throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "the name does not exist");
 419                 }
 420                 else
 421                 {
 422                     throw NotificationErrorFactory.GetException(ret, "unable to create Notification from template");
 423                 }
 424             }
 425
 426             Notification notification = new Notification
 427             {
 428                 Handle = new NotificationSafeHandle(handle, true)
 429             }.Build();
 430
 431             return notification;
 432         }
 433
 434         /// <summary>
 435         /// Gets notification block state.
 436         /// </summary>
 437         /// <remarks>
 438         /// The user can set the notification block state in settings.
 439         /// The block state indicates whether or not notifications can be posted.
 440         /// Additionally, only notifications to the notification panel are allowed in "Do not disturb mode".
 441         /// Sound, vibrate, and active notifications are blocked.
 442         /// </remarks>
 443         /// <returns>NotificationBlockState is a state if notification is posted.</returns>
 444         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission is denied.</exception>
 445         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 446         /// <privilege>http://tizen.org/privilege/notification</privilege>
 447         /// <since_tizen> 3 </since_tizen>
 448         public static NotificationBlockState GetBlockState()
 449         {
 450             NotificationBlockState state;
 451             NotificationError ret;
 452
 453             ret = Interop.Notification.GetBlockState(out state);
 454             if (ret != NotificationError.None)
 455             {
 456                 throw NotificationErrorFactory.GetException(ret, "GetBlockState failed");
 457             }
 458
 459             Log.Info(Notification.LogTag, "Current block state is " + state.ToString());
 460             return state;
 461         }
 462
 463         /// <summary>
 464         /// Make a NotificationSafeHandle from Notification.
 465         /// </summary>
 466         /// <param name="notification">The Notification class.</param>
 467         /// <returns>The NotificationSafeHandle class.</returns>
 468         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 469         /// <since_tizen> 3 </since_tizen>
 470         [EditorBrowsable(EditorBrowsableState.Never)]
 471         public static NotificationSafeHandle MakeNotificationSafeHandle(Notification notification)
 472         {
 473             if (notification == null)
 474             {
 475                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "invalid notification object");
 476             }
 477
 478             notification.Make();
 479
 480             return notification.Handle;
 481         }
 482
 483         /// <summary>
 484         /// Make a Notification from NotificationSafeHandle.
 485         /// </summary>
 486         /// <param name="handle">The NotificationSafeHandle class.</param>
 487         /// <returns>The Notification class.</returns>
 488         /// <exception cref="ArgumentException">Thrown when an argument is invalid.</exception>
 489         /// <since_tizen> 3 </since_tizen>
 490         [EditorBrowsable(EditorBrowsableState.Never)]
 491         public static Notification MakeNotification(NotificationSafeHandle handle)
 492         {
 493             if (handle == null || handle.IsInvalid == true)
 494             {
 495                 throw NotificationErrorFactory.GetException(NotificationError.InvalidParameter, "handle is invalid or null");
 496             }
 497
 498             Notification notification = new Notification { Handle = handle }.Build();
 499
 500             return notification;
 501         }
 502     }
 503 }