McpDispatchOperation: Mission Control Plugins Reference Manual

## McpDispatchOperation McpDispatchOperation — Dispatch operation object, implemented by Mission Control |

## Functions

gboolean | mcp_dispatch_operation_find_channel_by_type ()
TpConnection * | mcp_dispatch_operation_ref_connection ()
TpChannel * | mcp_dispatch_operation_ref_nth_channel ()
const gchar * | mcp_dispatch_operation_get_account_path ()
const gchar * | mcp_dispatch_operation_get_connection_path ()
const gchar * | mcp_dispatch_operation_get_protocol ()
const gchar * | mcp_dispatch_operation_get_cm_name ()
guint | mcp_dispatch_operation_get_n_channels ()
const gchar * | mcp_dispatch_operation_get_nth_channel_path ()
GHashTable * | mcp_dispatch_operation_ref_nth_channel_properties ()
McpDispatchOperationDelay * | mcp_dispatch_operation_start_delay ()
void | mcp_dispatch_operation_end_delay ()
void | mcp_dispatch_operation_leave_channels ()
void | mcp_dispatch_operation_close_channels ()
void | mcp_dispatch_operation_destroy_channels ()

## Types and Values

| McpDispatchOperationDelay

## Object Hierarchy

        GInterface
        ╰── McpDispatchOperation

## Includes

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

## Description

This object represents a Telepathy ChannelDispatchOperation object, as used by Approvers. A ChannelDispatchOperation represents a bundle of one or more Telepathy Channels being dispatched to user interfaces or other clients.

The virtual method `mcd_dispatch_operation_policy_check()` receives an object provided by Mission Control that implements this interface. It can be used to inspect the channels, delay dispatching of the bundle until the plugin is ready to continue, or close the channels in various ways.

Only Mission Control should implement this interface.

## Functions

### mcp_dispatch_operation_find_channel_by_type ()

    gboolean
    mcp_dispatch_operation_find_channel_by_type
                                   (McpDispatchOperation *self,
                                    guint start_from,
                                    TpHandleType handle_type,
                                    GQuark channel_type,
                                    guint *ret_index,
                                    gchar **ret_dup_path,
                                    GHashTable **ret_ref_immutable_properties,
                                    TpChannel **ret_ref_channel);

Attempt to find a channel matching the given handle type and channel type in the bundle. This is an easy way to test whether the bundle contains any channels of interest to a particular plugin.

#### Parameters

self | a dispatch operation |
start_from | index at which to start searching, usually 0 |
handle_type | the handle type to match |
channel_type | the channel type to match |
ret_index | if not `NULL`, used to return the index of the first matching channel, suitable for use with `mcp_dispatch_operation_get_nth_channel_path()` etc. |
ret_dup_path | if not `NULL`, used to return the object path of the first matching channel, which must be freed with `g_free()` |
ret_ref_immutable_properties | if not `NULL`, used to return a reference to immutable properties, as if via `mcp_dispatch_operation_ref_nth_channel_properties()`, which must be released with `g_hash_table_unref()` |
ret_ref_channel | if not `NULL`, used to return a TpChannel, which is not guaranteed to be ready immediately, and must be released with `g_object_unref()` |

#### Returns

`TRUE` if a matching channel was found, or `FALSE` (without touching `ret_index` , `ret_dup_path` , `ret_ref_immutable_properties` or `ret_ref_channel` ) if not

### mcp_dispatch_operation_ref_connection ()

    TpConnection *
    mcp_dispatch_operation_ref_connection (McpDispatchOperation *self);

Return a TpConnection object. It is not guaranteed to be ready immediately; use `tp_connection_call_when_ready()`.

#### Parameters

self | a dispatch operation |

#### Returns

a reference to a TpConnection, which must be released with `g_object_unref()` by the caller

### mcp_dispatch_operation_ref_nth_channel ()

    TpChannel *
    mcp_dispatch_operation_ref_nth_channel
                                   (McpDispatchOperation *self,
                                    guint n);

Return a TpChannel object. It is not guaranteed to be ready immediately; use `tp_channel_call_when_ready()`.

#### Parameters

self | a dispatch operation |
n | index of the channel to inspect |

#### Returns

a reference to a TpChannel, which must be released with `g_object_unref()` by the caller, or `NULL` if `n` is too large

### mcp_dispatch_operation_get_account_path ()

    const gchar *
    mcp_dispatch_operation_get_account_path
                                   (McpDispatchOperation *self);

#### Parameters

self | a dispatch operation |

#### Returns

the D-Bus object path of the Account with which the channels are associated. The string is owned by `self` and must not be freed; it is only valid as long as a reference to `self` is held.

### mcp_dispatch_operation_get_connection_path ()

    const gchar *
    mcp_dispatch_operation_get_connection_path
                                   (McpDispatchOperation *self);

#### Parameters

self | a dispatch operation |

#### Returns

the D-Bus object path of the Connection with which the channels are associated. The string is owned by `self` and must not be freed; it is only valid as long as a reference to `self` is held.

### mcp_dispatch_operation_get_protocol ()

    const gchar *
    mcp_dispatch_operation_get_protocol (McpDispatchOperation *self);

#### Parameters

self | a dispatch operation |

#### Returns

the Telepathy identifier for the protocol, such as 'jabber' or 'icq' (the Protocol type in telepathy-spec). The string is owned by `self` and must not be freed; it is only valid as long as a reference to `self` is held.

### mcp_dispatch_operation_get_cm_name ()

    const gchar *
    mcp_dispatch_operation_get_cm_name (McpDispatchOperation *self);

#### Parameters

self | a dispatch operation |

#### Returns

the short name of the Telepathy connection manager, such as 'gabble' or 'haze' (the Connection_Manager_Name type in telepathy-spec). The string is owned by `self` and must not be freed; it is only valid as long as a reference to `self` is held.

### mcp_dispatch_operation_get_n_channels ()

    guint
    mcp_dispatch_operation_get_n_channels (McpDispatchOperation *self);

#### Parameters

self | a dispatch operation |

#### Returns

the number of channels in this dispatch operation.

### mcp_dispatch_operation_get_nth_channel_path ()

    const gchar *
    mcp_dispatch_operation_get_nth_channel_path
                                   (McpDispatchOperation *self,
                                    guint n);

#### Parameters

self | a dispatch operation |
n | index of the channel to inspect |

#### Returns

the D-Bus object path of the `n` 'th channel (starting from 0), or `NULL` if `n` is greater than or equal to `mcp_dispatch_operation_get_n_channels()`. The string is owned by `self` and must not be freed; it is only valid as long as a reference to `self` is held.

### mcp_dispatch_operation_ref_nth_channel_properties ()

    GHashTable *
    mcp_dispatch_operation_ref_nth_channel_properties
                                   (McpDispatchOperation *self,
                                    guint n);

Return the immutable properties of the `n` 'th channel (starting from 0), or `NULL` if `n` is greater than or equal to `mcp_dispatch_operation_get_n_channels()`.

The keys of the hash table are strings and the values are in GValue structures, using the same representation as dbus-glib, `tp_asv_get_string()` etc. Do not add or remove entries in this hash table.

#### Parameters

self | a dispatch operation |
n | index of the channel to inspect |

#### Returns

a reference to a hash table, which must be released with `g_hash_table_unref()` by the caller

### mcp_dispatch_operation_start_delay ()

    McpDispatchOperationDelay *
    mcp_dispatch_operation_start_delay (McpDispatchOperation *self);

Start to delay the dispatch operation, for instance while waiting for an asynchronous operation to finish. The returned token must be passed to `mcp_dispatch_operation_end_delay()` exactly once, at which point dispatching will continue and the token becomes invalid.

This is similar to an Observer delaying the return from ObserveChannels, except that there is no time limit - a dispatch operation policy plugin can delay the dispatch operation indefinitely.

#### Parameters

self | a dispatch operation |

#### Returns

a token which can be used to end the delay

### mcp_dispatch_operation_end_delay ()

    void
    mcp_dispatch_operation_end_delay (McpDispatchOperation *self,
                                      McpDispatchOperationDelay *delay);

Stop delaying the dispatch operation, allowing dispatching to proceed.

#### Parameters

self | a dispatch operation |
delay | a token obtained by calling `mcp_dispatch_operation_start_delay()` on `self` previously |

### mcp_dispatch_operation_leave_channels ()

    void
    mcp_dispatch_operation_leave_channels (McpDispatchOperation *self,
                                           gboolean wait_for_observers,
                                           TpChannelGroupChangeReason reason,
                                           const gchar *message);

`mcp_dispatch_operation_leave_channels` has been deprecated since version 5.15.1 and should not be used in newly-written code.

Use `tp_call_channel_hangup_async()` to hang up Call channels, `mcp_dispatch_operation_close_channels()` to close generic channels, or `mcp_dispatch_operation_destroy_channels()` to terminate the channel destructively.

Leave all channels in this bundle by using RemoveMembersWithReason if the channel has the Group interface, or Close if not.

This method was intended for StreamedMedia channels, which (ab)used the Group interface for call control. StreamedMedia channels have been superseded by Call channels, which have a proper "hang up" method which should be used instead.

#### Parameters

self | a dispatch operation |
wait_for_observers | if `FALSE`, leave the channels immediately; if `TRUE` (usually recommended), wait for Observers to reply first |
reason | the reason code to give |
message | a human-readable message provided by the user, or either the empty string or `NULL` if no message has been provided |

### mcp_dispatch_operation_close_channels ()

    void
    mcp_dispatch_operation_close_channels (McpDispatchOperation *self,
                                           gboolean wait_for_observers);

Close all channels in this bundle by using the Close D-Bus method.

Plugins that terminate an audio or audio/video call should use `tp_call_channel_hangup_async()` instead.

#### Parameters

self | a dispatch operation |
wait_for_observers | if `FALSE`, close the channels immediately; if `TRUE` (usually recommended), wait for Observers to reply first |

### mcp_dispatch_operation_destroy_channels ()

    void
    mcp_dispatch_operation_destroy_channels
                                   (McpDispatchOperation *self,
                                    gboolean wait_for_observers);

Close all channels in this bundle destructively, by using the Destroy D-Bus method if implemented, or the Close D-Bus method if not.

Plugins that terminate an audio or audio/video call should use `tp_call_channel_hangup_async()` instead.

#### Parameters

self | a dispatch operation |
wait_for_observers | if `FALSE`, close the channels immediately; if `TRUE` (usually recommended), wait for Observers to reply first |

## Types and Values

### McpDispatchOperationDelay

    typedef struct _McpDispatchOperationDelay McpDispatchOperationDelay;

## See Also

McpDispatchOperationPolicy