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