gio/gnotification.c

   1 /*
   2  * Copyright © 2013 Lars Uebernickel
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Authors: Lars Uebernickel <lars@uebernic.de>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gnotification-private.h"
  25 #include "gdbusutils.h"
  26 #include "gicon.h"
  27 #include "gaction.h"
  28
  29 /**
  30  * SECTION:gnotification
  31  * @short_description: User Notifications (pop up messages)
  32  * @include: gio/gio.h
  33  *
  34  * #GNotification is a mechanism for creating a notification to be shown
  35  * to the user -- typically as a pop-up notification presented by the
  36  * desktop environment shell.
  37  *
  38  * The key difference between #GNotification and other similar APIs is
  39  * that, if supported by the desktop environment, notifications sent
  40  * with #GNotification will persist after the application has exited,
  41  * and even across system reboots.
  42  *
  43  * Since the user may click on a notification while the application is
  44  * not running, applications using #GNotification should be able to be
  45  * started as a D-Bus service, using #GApplication.
  46  *
  47  * User interaction with a notification (either the default action, or
  48  * buttons) must be associated with actions on the application (ie:
  49  * "app." actions).  It is not possible to route user interaction
  50  * through the notification itself, because the object will not exist if
  51  * the application is autostarted as a result of a notification being
  52  * clicked.
  53  *
  54  * A notification can be sent with g_application_send_notification().
  55  *
  56  * Since: 2.40
  57  **/
  58
  59 /**
  60  * GNotification:
  61  *
  62  * This structure type is private and should only be accessed using the
  63  * public APIs.
  64  *
  65  * Since: 2.40
  66  **/
  67
  68 typedef GObjectClass GNotificationClass;
  69
  70 struct _GNotification
  71 {
  72   GObject parent;
  73
  74   gchar *title;
  75   gchar *body;
  76   GIcon *icon;
  77   gboolean urgent;
  78   GPtrArray *buttons;
  79   gchar *default_action;
  80   GVariant *default_action_target;
  81 };
  82
  83 typedef struct
  84 {
  85   gchar *label;
  86   gchar *action_name;
  87   GVariant *target;
  88 } Button;
  89
  90 G_DEFINE_TYPE (GNotification, g_notification, G_TYPE_OBJECT);
  91
  92 static void
  93 button_free (gpointer data)
  94 {
  95   Button *button = data;
  96
  97   g_free (button->label);
  98   g_free (button->action_name);
  99   if (button->target)
 100     g_variant_unref (button->target);
 101
 102   g_slice_free (Button, button);
 103 }
 104
 105 static void
 106 g_notification_dispose (GObject *object)
 107 {
 108   GNotification *notification = G_NOTIFICATION (object);
 109
 110   g_clear_object (&notification->icon);
 111
 112   G_OBJECT_CLASS (g_notification_parent_class)->dispose (object);
 113 }
 114
 115 static void
 116 g_notification_finalize (GObject *object)
 117 {
 118   GNotification *notification = G_NOTIFICATION (object);
 119
 120   g_free (notification->title);
 121   g_free (notification->body);
 122   g_free (notification->default_action);
 123   if (notification->default_action_target)
 124     g_variant_unref (notification->default_action_target);
 125   g_ptr_array_free (notification->buttons, TRUE);
 126
 127   G_OBJECT_CLASS (g_notification_parent_class)->finalize (object);
 128 }
 129
 130 static void
 131 g_notification_class_init (GNotificationClass *klass)
 132 {
 133   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 134
 135   object_class->dispose = g_notification_dispose;
 136   object_class->finalize = g_notification_finalize;
 137 }
 138
 139 static void
 140 g_notification_init (GNotification *notification)
 141 {
 142   notification->buttons = g_ptr_array_new_full (2, button_free);
 143 }
 144
 145 /**
 146  * g_notification_new:
 147  * @title: the title of the notification
 148  *
 149  * Creates a new #GNotification with @title as its title.
 150  *
 151  * After populating @notification with more details, it can be sent to
 152  * the desktop shell with g_application_send_notification(). Changing
 153  * any properties after this call will not have any effect until
 154  * resending @notification.
 155  *
 156  * Returns: a new #GNotification instance
 157  *
 158  * Since: 2.40
 159  */
 160 GNotification *
 161 g_notification_new (const gchar *title)
 162 {
 163   GNotification *notification;
 164
 165   g_return_val_if_fail (title != NULL, NULL);
 166
 167   notification = g_object_new (G_TYPE_NOTIFICATION, NULL);
 168   notification->title = g_strdup (title);
 169
 170   return notification;
 171 }
 172
 173 /*< private >
 174  * g_notification_get_title:
 175  * @notification: a #GNotification
 176  *
 177  * Gets the title of @notification.
 178  *
 179  * Returns: the title of @notification
 180  *
 181  * Since: 2.40
 182  */
 183 const gchar *
 184 g_notification_get_title (GNotification *notification)
 185 {
 186   g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
 187
 188   return notification->title;
 189 }
 190
 191 /**
 192  * g_notification_set_title:
 193  * @notification: a #GNotification
 194  * @title: the new title for @notification
 195  *
 196  * Sets the title of @notification to @title.
 197  *
 198  * Since: 2.40
 199  */
 200 void
 201 g_notification_set_title (GNotification *notification,
 202                           const gchar   *title)
 203 {
 204   g_return_if_fail (G_IS_NOTIFICATION (notification));
 205   g_return_if_fail (title != NULL);
 206
 207   g_free (notification->title);
 208
 209   notification->title = g_strdup (title);
 210 }
 211
 212 /*< private >
 213  * g_notification_get_body:
 214  * @notification: a #GNotification
 215  *
 216  * Gets the current body of @notification.
 217  *
 218  * Returns: (allow-none): the body of @notification
 219  *
 220  * Since: 2.40
 221  */
 222 const gchar *
 223 g_notification_get_body (GNotification *notification)
 224 {
 225   g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
 226
 227   return notification->body;
 228 }
 229
 230 /**
 231  * g_notification_set_body:
 232  * @notification: a #GNotification
 233  * @body: (allow-none): the new body for @notification, or %NULL
 234  *
 235  * Sets the body of @notification to @body.
 236  *
 237  * Since: 2.40
 238  */
 239 void
 240 g_notification_set_body (GNotification *notification,
 241                          const gchar   *body)
 242 {
 243   g_return_if_fail (G_IS_NOTIFICATION (notification));
 244   g_return_if_fail (body != NULL);
 245
 246   g_free (notification->body);
 247
 248   notification->body = g_strdup (body);
 249 }
 250
 251 /*< private >
 252  * g_notification_get_icon:
 253  * @notification: a #GNotification
 254  *
 255  * Gets the icon currently set on @notification.
 256  *
 257  * Returns: (transfer none): the icon associated with @notification
 258  *
 259  * Since: 2.40
 260  */
 261 GIcon *
 262 g_notification_get_icon (GNotification *notification)
 263 {
 264   g_return_val_if_fail (G_IS_NOTIFICATION (notification), NULL);
 265
 266   return notification->icon;
 267 }
 268
 269 /**
 270  * g_notification_set_icon:
 271  * @notification: a #GNotification
 272  * @icon: the icon to be shown in @notification, as a #GIcon
 273  *
 274  * Sets the icon of @notification to @icon.
 275  *
 276  * Since: 2.40
 277  */
 278 void
 279 g_notification_set_icon (GNotification *notification,
 280                          GIcon         *icon)
 281 {
 282   g_return_if_fail (G_IS_NOTIFICATION (notification));
 283
 284   if (notification->icon)
 285     g_object_unref (notification->icon);
 286
 287   notification->icon = g_object_ref (icon);
 288 }
 289
 290 /*< private >
 291  * g_notification_get_urgent:
 292  * @notification: a #GNotification
 293  *
 294  * Returns %TRUE if @notification is marked as urgent.
 295  *
 296  * Since: 2.40
 297  */
 298 gboolean
 299 g_notification_get_urgent (GNotification *notification)
 300 {
 301   g_return_val_if_fail (G_IS_NOTIFICATION (notification), FALSE);
 302
 303   return notification->urgent;
 304 }
 305
 306 /**
 307  * g_notification_set_urgent:
 308  * @notification: a #GNotification
 309  * @urgent: %TRUE if @notification is urgent
 310  *
 311  * Sets or unsets whether @notification is marked as urgent.
 312  *
 313  * Since: 2.40
 314  */
 315 void
 316 g_notification_set_urgent (GNotification *notification,
 317                            gboolean       urgent)
 318 {
 319   g_return_if_fail (G_IS_NOTIFICATION (notification));
 320
 321   notification->urgent = urgent;
 322 }
 323
 324 /**
 325  * g_notification_add_button:
 326  * @notification: a #GNotification
 327  * @label: label of the button
 328  * @detailed_action: a detailed action name
 329  *
 330  * Adds a button to @notification that activates the action in
 331  * @detailed_action when clicked. That action must be an
 332  * application-wide action (starting with "app."). If @detailed_action
 333  * contains a target, the action will be activated with that target as
 334  * its parameter.
 335  *
 336  * See g_action_parse_detailed_name() for a description of the format
 337  * for @detailed_action.
 338  *
 339  * Since: 2.40
 340  */
 341 void
 342 g_notification_add_button (GNotification *notification,
 343                            const gchar   *label,
 344                            const gchar   *detailed_action)
 345 {
 346   gchar *action;
 347   GVariant *target;
 348   GError *error = NULL;
 349
 350   g_return_if_fail (detailed_action != NULL);
 351
 352   if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
 353     {
 354       g_warning ("%s: %s", G_STRFUNC, error->message);
 355       g_error_free (error);
 356       return;
 357     }
 358
 359   g_notification_add_button_with_target_value (notification, label, action, target);
 360
 361   g_free (action);
 362   if (target)
 363     g_variant_unref (target);
 364 }
 365
 366 /**
 367  * g_notification_add_button_with_target: (skip)
 368  * @notification: a #GNotification
 369  * @label: label of the button
 370  * @action: an action name
 371  * @target_format: (allow-none): a GVariant format string, or %NULL
 372  * @...: positional parameters, as determined by @format_string
 373  *
 374  * Adds a button to @notification that activates @action when clicked.
 375  * @action must be an application-wide action (it must start with "app.").
 376  *
 377  * If @target_format is given, it is used to collect remaining
 378  * positional parameters into a GVariant instance, similar to
 379  * g_variant_new(). @action will be activated with that GVariant as its
 380  * parameter.
 381  *
 382  * Since: 2.40
 383  */
 384 void
 385 g_notification_add_button_with_target (GNotification *notification,
 386                                        const gchar   *label,
 387                                        const gchar   *action,
 388                                        const gchar   *target_format,
 389                                        ...)
 390 {
 391   va_list args;
 392   GVariant *target = NULL;
 393
 394   if (target_format)
 395     {
 396       va_start (args, target_format);
 397       target = g_variant_new_va (target_format, NULL, &args);
 398       va_end (args);
 399     }
 400
 401   g_notification_add_button_with_target_value (notification, label, action, target);
 402 }
 403
 404 /**
 405  * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
 406  * @notification: a #GNotification
 407  * @label: label of the button
 408  * @action: an action name
 409  * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
 410  *
 411  * Adds a button to @notification that activates @action when clicked.
 412  * @action must be an application-wide action (it must start with "app.").
 413  *
 414  * If @target is non-%NULL, @action will be activated with @target as
 415  * its parameter.
 416  *
 417  * Since: 2.40
 418  */
 419 void
 420 g_notification_add_button_with_target_value (GNotification *notification,
 421                                              const gchar   *label,
 422                                              const gchar   *action,
 423                                              GVariant      *target)
 424 {
 425   Button *button;
 426
 427   g_return_if_fail (G_IS_NOTIFICATION (notification));
 428   g_return_if_fail (label != NULL);
 429   g_return_if_fail (action != NULL && g_action_name_is_valid (action));
 430
 431   if (!g_str_has_prefix (action, "app."))
 432     {
 433       g_warning ("%s: action '%s' does not start with 'app.'."
 434                  "This is unlikely to work properly.", G_STRFUNC, action);
 435     }
 436
 437   button =  g_slice_new0 (Button);
 438   button->label = g_strdup (label);
 439   button->action_name = g_strdup (action);
 440
 441   if (target)
 442     button->target = g_variant_ref_sink (target);
 443
 444   g_ptr_array_add (notification->buttons, button);
 445 }
 446
 447 /*< private >
 448  * g_notification_get_n_buttons:
 449  * @notification: a #GNotification
 450  *
 451  * Returns: the amount of buttons added to @notification.
 452  */
 453 guint
 454 g_notification_get_n_buttons (GNotification *notification)
 455 {
 456   return notification->buttons->len;
 457 }
 458
 459 /*< private >
 460  * g_notification_get_button:
 461  * @notification: a #GNotification
 462  * @index: index of the button
 463  * @label: (): return location for the button's label
 464  * @action: (): return location for the button's associated action
 465  * @target: (): return location for the target @action should be
 466  * activated with
 467  *
 468  * Returns a description of a button that was added to @notification
 469  * with g_notification_add_button().
 470  *
 471  * @index must be smaller than the value returned by
 472  * g_notification_get_n_buttons().
 473  */
 474 void
 475 g_notification_get_button (GNotification  *notification,
 476                            gint            index,
 477                            gchar         **label,
 478                            gchar         **action,
 479                            GVariant      **target)
 480 {
 481   Button *button;
 482
 483   button = g_ptr_array_index (notification->buttons, index);
 484
 485   if (label)
 486     *label = g_strdup (button->label);
 487
 488   if (action)
 489     *action = g_strdup (button->action_name);
 490
 491   if (target)
 492     *target = button->target ? g_variant_ref (button->target) : NULL;
 493 }
 494
 495 /*< private >
 496  * g_notification_get_button_with_action:
 497  * @notification: a #GNotification
 498  * @action: an action name
 499  *
 500  * Returns the index of the button in @notification that is associated
 501  * with @action, or -1 if no such button exists.
 502  */
 503 gint
 504 g_notification_get_button_with_action (GNotification *notification,
 505                                        const gchar   *action)
 506 {
 507   guint i;
 508
 509   for (i = 0; i < notification->buttons->len; i++)
 510     {
 511       Button *button;
 512
 513       button = g_ptr_array_index (notification->buttons, i);
 514       if (g_str_equal (action, button->action_name))
 515         return i;
 516     }
 517
 518   return -1;
 519 }
 520
 521
 522 /*< private >
 523  * g_notification_get_default_action:
 524  * @notification: a #GNotification
 525  * @action: (allow-none): return location for the default action
 526  * @target: (allow-none): return location for the target of the default action
 527  *
 528  * Gets the action and target for the default action of @notification.
 529  *
 530  * Returns: %TRUE if @notification has a default action
 531  */
 532 gboolean
 533 g_notification_get_default_action (GNotification  *notification,
 534                                    gchar         **action,
 535                                    GVariant      **target)
 536 {
 537   if (notification->default_action == NULL)
 538     return FALSE;
 539
 540   if (action)
 541     *action = g_strdup (notification->default_action);
 542
 543   if (target)
 544     {
 545       if (notification->default_action_target)
 546         *target = g_variant_ref (notification->default_action_target);
 547       else
 548         *target = NULL;
 549     }
 550
 551   return TRUE;
 552 }
 553
 554 /**
 555  * g_notification_set_default_action:
 556  * @notification: a #GNotification
 557  * @detailed_action: a detailed action name
 558  *
 559  * Sets the default action of @notification to @detailed_action. This
 560  * action is activated when the notification is clicked on.
 561  *
 562  * The action in @detailed_action must be an application-wide action (it
 563  * must start with "app."). If @detailed_action contains a target, the
 564  * given action will be activated with that target as its parameter.
 565  * See g_action_parse_detailed_name() for a description of the format
 566  * for @detailed_action.
 567  *
 568  * When no default action is set, the application that the notification
 569  * was sent on is activated.
 570  *
 571  * Since: 2.40
 572  */
 573 void
 574 g_notification_set_default_action (GNotification *notification,
 575                                    const gchar   *detailed_action)
 576 {
 577   gchar *action;
 578   GVariant *target;
 579   GError *error = NULL;
 580
 581   if (!g_action_parse_detailed_name (detailed_action, &action, &target, &error))
 582     {
 583       g_warning ("%s: %s", G_STRFUNC, error->message);
 584       g_error_free (error);
 585       return;
 586     }
 587
 588   g_notification_set_default_action_and_target_value (notification, action, target);
 589
 590   g_free (action);
 591   if (target)
 592     g_variant_unref (target);
 593 }
 594
 595 /**
 596  * g_notification_set_default_action_and_target: (skip)
 597  * @notification: a #GNotification
 598  * @action: an action name
 599  * @target_format: (allow-none): a GVariant format string, or %NULL
 600  * @...: positional parameters, as determined by @format_string
 601  *
 602  * Sets the default action of @notification to @action. This action is
 603  * activated when the notification is clicked on. It must be an
 604  * application-wide action (it must start with "app.").
 605  *
 606  * If @target_format is given, it is used to collect remaining
 607  * positional parameters into a GVariant instance, similar to
 608  * g_variant_new(). @action will be activated with that GVariant as its
 609  * parameter.
 610  *
 611  * When no default action is set, the application that the notification
 612  * was sent on is activated.
 613  *
 614  * Since: 2.40
 615  */
 616 void
 617 g_notification_set_default_action_and_target (GNotification *notification,
 618                                               const gchar   *action,
 619                                               const gchar   *target_format,
 620                                               ...)
 621 {
 622   va_list args;
 623   GVariant *target = NULL;
 624
 625   if (target_format)
 626     {
 627       va_start (args, target_format);
 628       target = g_variant_new_va (target_format, NULL, &args);
 629       va_end (args);
 630     }
 631
 632   g_notification_set_default_action_and_target_value (notification, action, target);
 633 }
 634
 635 /**
 636  * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
 637  * @notification: a #GNotification
 638  * @action: an action name
 639  * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
 640  *
 641  * Sets the default action of @notification to @action. This action is
 642  * activated when the notification is clicked on. It must be an
 643  * application-wide action (start with "app.").
 644  *
 645  * If @target_format is given, it is used to collect remaining
 646  * positional parameters into a GVariant instance, similar to
 647  * g_variant_new().
 648  *
 649  * If @target is non-%NULL, @action will be activated with @target as
 650  * its parameter.
 651  *
 652  * When no default action is set, the application that the notification
 653  * was sent on is activated.
 654  *
 655  * Since: 2.40
 656  */
 657 void
 658 g_notification_set_default_action_and_target_value (GNotification *notification,
 659                                                     const gchar   *action,
 660                                                     GVariant      *target)
 661 {
 662   g_return_if_fail (G_IS_NOTIFICATION (notification));
 663   g_return_if_fail (action != NULL && g_action_name_is_valid (action));
 664
 665   if (!g_str_has_prefix (action, "app."))
 666     {
 667       g_warning ("%s: action '%s' does not start with 'app.'."
 668                  "This is unlikely to work properly.", G_STRFUNC, action);
 669     }
 670
 671   g_free (notification->default_action);
 672   g_clear_pointer (&notification->default_action_target, g_variant_unref);
 673
 674   notification->default_action = g_strdup (action);
 675
 676   if (target)
 677     notification->default_action_target = g_variant_ref_sink (target);
 678 }
 679
 680 static GVariant *
 681 g_notification_serialize_button (Button *button)
 682 {
 683   GVariantBuilder builder;
 684
 685   g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
 686
 687   g_variant_builder_add (&builder, "{sv}", "label", g_variant_new_string (button->label));
 688   g_variant_builder_add (&builder, "{sv}", "action", g_variant_new_string (button->action_name));
 689
 690   if (button->target)
 691     g_variant_builder_add (&builder, "{sv}", "target", button->target);
 692
 693   return g_variant_builder_end (&builder);
 694 }
 695
 696 /*< private >
 697  * g_notification_serialize:
 698  *
 699  * Serializes @notification into an floating variant of type a{sv}.
 700  *
 701  * Returns: the serialized @notification as a floating variant.
 702  */
 703 GVariant *
 704 g_notification_serialize (GNotification *notification)
 705 {
 706   GVariantBuilder builder;
 707
 708   g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{sv}"));
 709
 710   if (notification->title)
 711     g_variant_builder_add (&builder, "{sv}", "title", g_variant_new_string (notification->title));
 712
 713   if (notification->body)
 714     g_variant_builder_add (&builder, "{sv}", "body", g_variant_new_string (notification->body));
 715
 716   if (notification->icon)
 717     {
 718       GVariant *serialized_icon;
 719
 720       if ((serialized_icon = g_icon_serialize (notification->icon)))
 721         {
 722           g_variant_builder_add (&builder, "{sv}", "icon", serialized_icon);
 723           g_variant_unref (serialized_icon);
 724         }
 725     }
 726
 727   g_variant_builder_add (&builder, "{sv}", "urgent", g_variant_new_boolean (notification->urgent));
 728
 729   if (notification->default_action)
 730     {
 731       g_variant_builder_add (&builder, "{sv}", "default-action",
 732                                                g_variant_new_string (notification->default_action));
 733
 734       if (notification->default_action_target)
 735         g_variant_builder_add (&builder, "{sv}", "default-action-target",
 736                                                   notification->default_action_target);
 737     }
 738
 739   if (notification->buttons->len > 0)
 740     {
 741       GVariantBuilder actions_builder;
 742       guint i;
 743
 744       g_variant_builder_init (&actions_builder, G_VARIANT_TYPE ("aa{sv}"));
 745
 746       for (i = 0; i < notification->buttons->len; i++)
 747         {
 748           Button *button = g_ptr_array_index (notification->buttons, i);
 749           g_variant_builder_add (&actions_builder, "@a{sv}", g_notification_serialize_button (button));
 750         }
 751
 752       g_variant_builder_add (&builder, "{sv}", "buttons", g_variant_builder_end (&actions_builder));
 753     }
 754
 755   return g_variant_builder_end (&builder);
 756 }