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.

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