← Back to branch summary

~ubuntu-branches/ubuntu/precise/telepathy-mission-control-5/precise

« back to all changes in this revision

Viewing changes to mission-control-plugins/request-policy.c

Tags: upstream-5.5.2
Import upstream version 5.5.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
mission-control-plugins/request-policy.c
 
1
/* Mission Control plugin API - ChannelRequest policy hook.
 
2
 *
 
3
 * Copyright (C) 2009 Nokia Corporation
 
4
 * Copyright (C) 2009 Collabora Ltd.
 
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 Public
 
17
 * License along with this library; if not, write to the Free Software
 
18
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
19
 */
 
20
 
 
21
/**
 
22
 * SECTION:request-policy
 
23
 * @title: McpRequestPolicy
 
24
 * @short_description: Request-policy object, implemented by plugins
 
25
 * @see_also: #McpRequest
 
26
 * @include: mission-control-plugins/mission-control-plugins.h
 
27
 *
 
28
 * Plugins may implement #McpRequestPolicy in order to apply policy to
 
29
 * Telepathy channel requests passing through the Channel Dispatcher part of
 
30
 * Mission Control. The plugins are run just after the requesting client calls
 
31
 * the ChannelRequest.Proceed method, and can inspect the request, delay its
 
32
 * processing, and/or make it fail.
 
33
 *
 
34
 * To do so, the plugin must implement a #GObject subclass that implements
 
35
 * #McpRequestPolicy, then return an instance of that subclass from
 
36
 * mcp_plugin_ref_nth_object().
 
37
 *
 
38
 * The contents of the #McpRequestPolicyIface struct are not public, so to
 
39
 * provide an implementation of the check method,
 
40
 * plugins should call mcp_request_policy_iface_implement_check() from the
 
41
 * interface initialization function, like this:
 
42
 *
 
43
 * <example><programlisting>
 
44
 * G_DEFINE_TYPE_WITH_CODE (MyPlugin, my_plugin,
 
45
 *    G_TYPE_OBJECT,
 
46
 *    G_IMPLEMENT_INTERFACE (...);
 
47
 *    G_IMPLEMENT_INTERFACE (MCP_TYPE_REQUEST_POLICY,
 
48
 *      request_policy_iface_init);
 
49
 *    G_IMPLEMENT_INTERFACE (...))
 
50
 * /<!-- -->* ... *<!-- -->/
 
51
 * static void
 
52
 * request_policy_iface_init (McpRequestPolicyIface *iface,
 
53
 *     gpointer unused G_GNUC_UNUSED)
 
54
 * {
 
55
 *   mcp_request_policy_iface_implement_check (iface,
 
56
 *       my_plugin_check_request);
 
57
 * }
 
58
 * </programlisting></example>
 
59
 *
 
60
 * A single object can implement more than one interface; for instance, it
 
61
 * may be useful to combine this interface with #McpDispatchOperationPolicy.
 
62
 */
 
63
 
 
64
#include <mission-control-plugins/mission-control-plugins.h>
 
65
 
 
66
struct _McpRequestPolicyIface {
 
67
    GTypeInterface parent;
 
68
 
 
69
    void (*check) (McpRequestPolicy *, McpRequest *);
 
70
};
 
71
 
 
72
GType
 
73
mcp_request_policy_get_type (void)
 
74
{
 
75
  static gsize once = 0;
 
76
  static GType type = 0;
 
77
 
 
78
  if (g_once_init_enter (&once))
 
79
    {
 
80
      static const GTypeInfo info = {
 
81
          sizeof (McpRequestPolicyIface),
 
82
          NULL, /* base_init */
 
83
          NULL, /* base_finalize */
 
84
          NULL, /* class_init */
 
85
          NULL, /* class_finalize */
 
86
          NULL, /* class_data */
 
87
          0, /* instance_size */
 
88
          0, /* n_preallocs */
 
89
          NULL, /* instance_init */
 
90
          NULL /* value_table */
 
91
      };
 
92
 
 
93
      type = g_type_register_static (G_TYPE_INTERFACE, "McpRequestPolicy",
 
94
          &info, 0);
 
95
      g_type_interface_add_prerequisite (type, G_TYPE_OBJECT);
 
96
 
 
97
      g_once_init_leave (&once, 1);
 
98
    }
 
99
 
 
100
  return type;
 
101
}
 
102
 
 
103
/**
 
104
 * mcp_request_policy_check:
 
105
 * @policy: an implementation of this interface, provided by a plugin
 
106
 * @request: an object representing a channel request
 
107
 *
 
108
 * Check what to do with a channel request. Implementations of this method
 
109
 * can use methods on @request to examine the request, delay
 
110
 * processing, make the request fail, etc. in order to impose whatever policy
 
111
 * the plugin requires.
 
112
 *
 
113
 * Mission Control calls this function in each plugin just after the requesting
 
114
 * client calls the Proceed method on the Telepathy ChannelRequest. If the
 
115
 * plugin makes the request fail, this does not take effect until all plugins
 
116
 * have been notified.
 
117
 */
 
118
void
 
119
mcp_request_policy_check (McpRequestPolicy *policy,
 
120
    McpRequest *request)
 
121
{
 
122
  McpRequestPolicyIface *iface = MCP_REQUEST_POLICY_GET_IFACE (policy);
 
123
 
 
124
  g_return_if_fail (iface != NULL);
 
125
 
 
126
  if (iface->check != NULL)
 
127
    iface->check (policy, request);
 
128
}
 
129
 
 
130
/**
 
131
 * mcp_request_policy_iface_implement_check:
 
132
 * @iface: the interface
 
133
 * @impl: an implementation of the virtual method mcp_request_policy_check()
 
134
 */
 
135
void
 
136
mcp_request_policy_iface_implement_check (McpRequestPolicyIface *iface,
 
137
    void (*impl) (McpRequestPolicy *, McpRequest *))
 
138
{
 
139
  iface->check = impl;
 
140
}