gio/gremoteactiongroup.c

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