gio/gremoteactiongroup.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published
   6  * by the Free Software Foundation; either version 2 of the licence or (at
   7  * 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, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors: Ryan Lortie <desrt@desrt.ca>
  18  */
  19
  20 #include "config.h"
  21
  22 #include "gsimpleaction.h"
  23 #include "gactiongroup.h"
  24 #include "gactionmap.h"
  25 #include "gaction.h"
  26
  27 /**
  28  * SECTION:gremoteactiongroup
  29  * @title: GRemoteActionGroup
  30  * @short_description: A GActionGroup that interacts with other processes
  31  * @include: gio/gio.h
  32  *
  33  * The GRemoteActionGroup interface is implemented by #GActionGroup
  34  * instances that either transmit action invocations to other processes
  35  * or receive action invocations in the local process from other
  36  * processes.
  37  *
  38  * The interface has `_full` variants of the two
  39  * methods on #GActionGroup used to activate actions:
  40  * g_action_group_activate_action() and
  41  * g_action_group_change_action_state(). These variants allow a
  42  * "platform data" #GVariant to be specified: a dictionary providing
  43  * context for the action invocation (for example: timestamps, startup
  44  * notification IDs, etc).
  45  *
  46  * #GDBusActionGroup implements #GRemoteActionGroup.  This provides a
  47  * mechanism to send platform data for action invocations over D-Bus.
  48  *
  49  * Additionally, g_dbus_connection_export_action_group() will check if
  50  * the exported #GActionGroup implements #GRemoteActionGroup and use the
  51  * `_full` variants of the calls if available.  This
  52  * provides a mechanism by which to receive platform data for action
  53  * invocations that arrive by way of D-Bus.
  54  *
  55  * Since: 2.32
  56  **/
  57
  58 /**
  59  * GRemoteActionGroupInterface:
  60  * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
  61  * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
  62  *
  63  * The virtual function table for #GRemoteActionGroup.
  64  *
  65  * Since: 2.32
  66  **/
  67
  68 #include "config.h"
  69
  70 #include "gremoteactiongroup.h"
  71
  72 G_DEFINE_INTERFACE (GRemoteActionGroup, g_remote_action_group, G_TYPE_ACTION_GROUP)
  73
  74 static void
  75 g_remote_action_group_default_init (GRemoteActionGroupInterface *iface)
  76 {
  77 }
  78
  79 /**
  80  * g_remote_action_group_activate_action_full:
  81  * @remote: a #GDBusActionGroup
  82  * @action_name: the name of the action to activate
  83  * @parameter: (allow-none): the optional parameter to the activation
  84  * @platform_data: the platform data to send
  85  *
  86  * Activates the remote action.
  87  *
  88  * This is the same as g_action_group_activate_action() except that it
  89  * allows for provision of "platform data" to be sent along with the
  90  * activation request.  This typically contains details such as the user
  91  * interaction timestamp or startup notification information.
  92  *
  93  * @platform_data must be non-%NULL and must have the type
  94  * %G_VARIANT_TYPE_VARDICT.  If it is floating, it will be consumed.
  95  *
  96  * Since: 2.32
  97  **/
  98 void
  99 g_remote_action_group_activate_action_full (GRemoteActionGroup *remote,
 100                                             const gchar        *action_name,
 101                                             GVariant           *parameter,
 102                                             GVariant           *platform_data)
 103 {
 104   G_REMOTE_ACTION_GROUP_GET_IFACE (remote)
 105     ->activate_action_full (remote, action_name, parameter, platform_data);
 106 }
 107
 108 /**
 109  * g_remote_action_group_change_action_state_full:
 110  * @remote: a #GRemoteActionGroup
 111  * @action_name: the name of the action to change the state of
 112  * @value: the new requested value for the state
 113  * @platform_data: the platform data to send
 114  *
 115  * Changes the state of a remote action.
 116  *
 117  * This is the same as g_action_group_change_action_state() except that
 118  * it allows for provision of "platform data" to be sent along with the
 119  * state change request.  This typically contains details such as the
 120  * user interaction timestamp or startup notification information.
 121  *
 122  * @platform_data must be non-%NULL and must have the type
 123  * %G_VARIANT_TYPE_VARDICT.  If it is floating, it will be consumed.
 124  *
 125  * Since: 2.32
 126  **/
 127 void
 128 g_remote_action_group_change_action_state_full (GRemoteActionGroup *remote,
 129                                                 const gchar        *action_name,
 130                                                 GVariant           *value,
 131                                                 GVariant           *platform_data)
 132 {
 133   G_REMOTE_ACTION_GROUP_GET_IFACE (remote)
 134     ->change_action_state_full (remote, action_name, value, platform_data);
 135 }