McpDispatchOperationPolicy

McpDispatchOperationPolicy — Dispatch Operation policy object, implemented by plugins

Synopsis

#include <mission-control-plugins/mission-control-plugins.h>

void                (*McpDispatchOperationPolicyCb)     (McpDispatchOperationPolicy *policy,
                                                         McpDispatchOperation *dispatch_operation);
void                mcp_dispatch_operation_policy_check (McpDispatchOperationPolicy *policy,
                                                         McpDispatchOperation *dispatch_operation);
void                (*McpDispatchOperationPolicyHandlerIsSuitableAsync)
                                                        (McpDispatchOperationPolicy *policy,
                                                         TpClient *handler,
                                                         const gchar *unique_name,
                                                         McpDispatchOperation *dispatch_operation,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            (*McpDispatchOperationPolicyFinisher)
                                                        (McpDispatchOperationPolicy *policy,
                                                         GAsyncResult *result,
                                                         GError **error);
void                mcp_dispatch_operation_policy_handler_is_suitable_async
                                                        (McpDispatchOperationPolicy *policy,
                                                         TpClient *handler,
                                                         const gchar *unique_name,
                                                         McpDispatchOperation *dispatch_operation,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            mcp_dispatch_operation_policy_handler_is_suitable_finish
                                                        (McpDispatchOperationPolicy *policy,
                                                         GAsyncResult *result,
                                                         GError **error);
void                mcp_dispatch_operation_policy_iface_implement_check
                                                        (McpDispatchOperationPolicyIface *iface,
                                                         McpDispatchOperationPolicyCb impl);
struct              McpDispatchOperationPolicyIface;

Description

Plugins may implement McpDispatchOperationPolicy in order to apply policy to Telepathy channel dispatch operations passing through the Channel Dispatcher part of Mission Control. This interface behaves rather like the Observer clients in the Telepathy specification, and has access to the same information, but runs within the Mission Control process rather than being invoked over D-Bus.

To do so, the plugin must implement a GObject subclass that implements McpDispatchOperationPolicy, then return an instance of that subclass from mcp_plugin_ref_nth_object().

A typical plugin might look like this:

Example 3. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
G_DEFINE_TYPE_WITH_CODE (MyPlugin, my_plugin,
   G_TYPE_OBJECT,
   G_IMPLEMENT_INTERFACE (...);
   G_IMPLEMENT_INTERFACE (MCP_TYPE_DISPATCH_OPERATION_POLICY,
     cdo_policy_iface_init);
   G_IMPLEMENT_INTERFACE (...))
/* ... */
static void
cdo_policy_iface_init (McpDispatchOperationPolicyIface *iface,
    gpointer unused G_GNUC_UNUSED)
{
  iface->check = my_plugin_check_cdo;
  iface->handler_is_suitable_async = my_plugin_handler_is_suitable_async;
  iface->handler_is_suitable_finish = my_plugin_handler_is_suitable_finish;
}


A single object can implement more than one interface; for instance, it may be useful to combine this interface with McpRequestPolicy.

Details

McpDispatchOperationPolicyCb ()

void                (*McpDispatchOperationPolicyCb)     (McpDispatchOperationPolicy *policy,
                                                         McpDispatchOperation *dispatch_operation);

Signature of an implementation of mcp_dispatch_operation_policy_check().

policy :

an implementation of this interface, provided by a plugin

dispatch_operation :

an object representing a dispatch operation, i.e. a bundle of channels being dispatched

mcp_dispatch_operation_policy_check ()

void                mcp_dispatch_operation_policy_check (McpDispatchOperationPolicy *policy,
                                                         McpDispatchOperation *dispatch_operation);

Check what to do with a bundle of channels. Implementations of this method can use methods on dispatch_operation to examine the channels, delay dispatching, close the channels, etc. in order to impose whatever policy the plugin requires.

Mission Control calls this function in each plugin after invoking Observers, but before Approvers, and without waiting for Observers to reply.

policy :

an implementation of this interface, provided by a plugin

dispatch_operation :

an object representing a dispatch operation, i.e. a bundle of channels being dispatched

McpDispatchOperationPolicyHandlerIsSuitableAsync ()

void                (*McpDispatchOperationPolicyHandlerIsSuitableAsync)
                                                        (McpDispatchOperationPolicy *policy,
                                                         TpClient *handler,
                                                         const gchar *unique_name,
                                                         McpDispatchOperation *dispatch_operation,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Signature of mcp_dispatch_operation_policy_handler_is_suitable_async()

policy :

an implementation of this interface, provided by a plugin

handler :

a proxy for the Handler's D-Bus API, or NULL if the Handler is calling Claim (so its well-known name is not immediately obvious)

unique_name :

The Handler's unique name, or empty or NULL if it has not yet been started

dispatch_operation :

an object representing a dispatch operation, i.e. a bundle of channels being dispatched

callback :

callback to be called on success or failure

user_data :

user data for the callback

McpDispatchOperationPolicyFinisher ()

gboolean            (*McpDispatchOperationPolicyFinisher)
                                                        (McpDispatchOperationPolicy *policy,
                                                         GAsyncResult *result,
                                                         GError **error);

Signature of a virtual method used to finish an asynchronous operation that succeeds or fails, but does not return any additional value.

policy :

an implementation of this interface, provided by a plugin

result :

the asynchronous result passed to a GAsyncReadyCallback

error :

used to return an error. [allow-none]

Returns :

TRUE if the operation succeeded, FALSE on error

mcp_dispatch_operation_policy_handler_is_suitable_async ()

void                mcp_dispatch_operation_policy_handler_is_suitable_async
                                                        (McpDispatchOperationPolicy *policy,
                                                         TpClient *handler,
                                                         const gchar *unique_name,
                                                         McpDispatchOperation *dispatch_operation,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Check whether a handler is "suitable" for these channels. For instance, this could be used to ensure that only the platform's default UI can be used for particular channels, even if MC would normally consider a third-party UI to be a better match.

Mission Control calls all implementations of this method in parallel and waits for them all to return. If any of them raises an error, the handler is considered to be unsuitable.

policy :

an implementation of this interface, provided by a plugin

handler :

a proxy for the Handler's D-Bus API, or NULL if the Handler is calling Claim (so its well-known name is not immediately obvious)

unique_name :

The Handler's unique name, or empty or NULL if it has not yet been started

dispatch_operation :

an object representing a dispatch operation, i.e. a bundle of channels being dispatched

callback :

callback to be called on success or failure

user_data :

user data for the callback

mcp_dispatch_operation_policy_handler_is_suitable_finish ()

gboolean            mcp_dispatch_operation_policy_handler_is_suitable_finish
                                                        (McpDispatchOperationPolicy *policy,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish a call to mcp_dispatch_operation_policy_handler_is_suitable_async().

policy :

an implementation of this interface, provided by a plugin

result :

the asynchronous result passed to the GAsyncReadyCallback

error :

used to return an error. [allow-none]

Returns :

TRUE if the handler is suitable; FALSE if the handler is unsuitable or there was an error

mcp_dispatch_operation_policy_iface_implement_check ()

void                mcp_dispatch_operation_policy_iface_implement_check
                                                        (McpDispatchOperationPolicyIface *iface,
                                                         McpDispatchOperationPolicyCb impl);

This method is no longer necessary: just set iface->check = impl instead.

iface :

the interface

impl :

an implementation of the virtual method mcp_dispatch_operation_policy_check()

struct McpDispatchOperationPolicyIface

struct McpDispatchOperationPolicyIface {
    GTypeInterface parent;

    McpDispatchOperationPolicyCb check;
    McpDispatchOperationPolicyHandlerIsSuitableAsync handler_is_suitable_async;
    McpDispatchOperationPolicyFinisher handler_is_suitable_finish;
};

GTypeInterface parent;

the parent type

McpDispatchOperationPolicyCb check;

an implementation of mcp_dispatch_operation_policy_check(); NULL is equivalent to an implementation that does nothing

McpDispatchOperationPolicyHandlerIsSuitableAsync handler_is_suitable_async;

an implementation of mcp_dispatch_operation_policy_handler_is_suitable_async(); NULL is treated as equivalent to an implementation that accepts every handler, i.e. always asynchronously returns TRUE

McpDispatchOperationPolicyFinisher handler_is_suitable_finish;

an implementation of mcp_dispatch_operation_policy_handler_is_suitable_finish(); NULL is treated as equivalent to an implementation that accepts any GSimpleAsyncResult

See Also

McpDispatchOperation