McpDispatchOperationPolicy: Mission Control Plugins Reference Manual

## McpDispatchOperationPolicy McpDispatchOperationPolicy — Dispatch Operation policy object, implemented by plugins |

## Functions

void | (*McpDispatchOperationPolicyCb) ()
void | mcp_dispatch_operation_policy_check ()
void | (*McpDispatchOperationPolicyHandlerIsSuitableAsync) ()
gboolean | (*McpDispatchOperationPolicyFinisher) ()
void | mcp_dispatch_operation_policy_handler_is_suitable_async ()
gboolean | mcp_dispatch_operation_policy_handler_is_suitable_finish ()
void | mcp_dispatch_operation_policy_iface_implement_check ()

## Object Hierarchy

        GInterface
        ╰── McpDispatchOperationPolicy

## Includes

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

## 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.

## Functions

### McpDispatchOperationPolicyCb ()

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

Signature of an implementation of `mcp_dispatch_operation_policy_check()`.

#### Parameters

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.

#### Parameters

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()`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

iface | the interface |
impl | an implementation of the virtual method `mcp_dispatch_operation_policy_check()` |

## See Also

McpDispatchOperation