TpChannel

## TpChannel TpChannel — proxy object for a Telepathy channel |

## Synopsis

    #include <telepathy-glib/channel.h>

    TpChannel*          tp_channel_new                      (TpConnection *conn,
                                                             const gchar *object_path,
                                                             const gchar *optional_channel_type,
                                                             TpHandleType optional_handle_type,
                                                             TpHandle optional_handle,
                                                             GError **error);
    gboolean            tp_channel_run_until_ready          (TpChannel *self,
                                                             GError **error,
                                                             GMainLoop **loop);
                        TpChannel;
                        TpChannelClass;
    #define             TP_ERRORS_REMOVED_FROM_GROUP

    TpProxyPendingCall* tp_cli_channel_call_close           (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_close callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_channel_call_get_channel_type
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_channel_type callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_channel_call_get_handle      (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_handle callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_channel_call_get_interfaces  (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_interfaces callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_callback_for_close)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_callback_for_get_channel_type)
                                                            (TpChannel *proxy,
                                                             const gchar *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_callback_for_get_handle)
                                                            (TpChannel *proxy,
                                                             guint out0,
                                                             guint out1,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_channel_callback_for_get_interfaces)
                                                            (TpChannel *proxy,
                                                             const gchar **out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    gboolean            tp_cli_channel_run_close            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_channel_run_get_channel_type (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_channel_run_get_handle       (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             guint *out1,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_channel_run_get_interfaces   (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    TpProxySignalConnection* tp_cli_channel_connect_to_closed
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_signal_callback_closed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    void                (*tp_cli_channel_signal_callback_closed)
                                                            (TpChannel *proxy,
                                                             gpointer user_data,
                                                             GObject *weak_object);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpChannel

## Implemented Interfaces

TpChannel implements TpChannelIface.

## Properties

      "channel-ready"            gboolean              : Read
      "connection"               TpConnection          : Read / Write / Construct Only

## Description

TpChannel objects provide convenient access to Telepathy channels.

Compared with a simple proxy for method calls, they add the following features:

* calling `GetChannelType()`, `GetInterfaces()`, `GetHandles()` automatically

This section also documents the auto-generated C wrappers for the Channel D-Bus interface. Of these, in general, only `tp_cli_channel_call_close()` and `tp_cli_channel_run_close()` are useful (the TpChannel object provides a more convenient API for the rest).

## Details

### tp_channel_new ()

    TpChannel*          tp_channel_new                      (TpConnection *conn,
                                                             const gchar *object_path,
                                                             const gchar *optional_channel_type,
                                                             TpHandleType optional_handle_type,
                                                             TpHandle optional_handle,
                                                             GError **error);

`conn` : | a connection; may not be `NULL`
`object_path` : | the object path of the channel; may not be `NULL`
`optional_channel_type` : | the channel type if already known, or `NULL` if not
`optional_handle_type` : | the handle type if already known, or `TP_UNKNOWN_HANDLE_TYPE` if not
`optional_handle` : | the handle if already known, or 0 if not (if `optional_handle_type` is `TP_UNKNOWN_HANDLE_TYPE` or `TP_HANDLE_TYPE_NONE`, this must be 0)
`error` : | used to indicate the error if `NULL` is returned
Returns : | a new channel proxy, or `NULL` on invalid arguments.

Since 0.7.1

### tp_channel_run_until_ready ()

    gboolean            tp_channel_run_until_ready          (TpChannel *self,
                                                             GError **error,
                                                             GMainLoop **loop);

If `self` is ready for use (introspection has finished, etc.), return immediately. Otherwise, re-enter the main loop until the channel either becomes invalid or becomes ready for use, or until the main loop stored via `loop` is cancelled.

`self` : | a channel
`error` : | if not `NULL` and `FALSE` is returned, used to raise an error
`loop` : | if not `NULL`, a GMainLoop is placed here while it is being run (so calling code can call `g_main_loop_quit()` to abort), and `NULL` is placed here after the loop has been run
Returns : | `TRUE` if the channel has been introspected and is ready for use, `FALSE` if the channel has become invalid.

Since 0.7.1

### TpChannel

    typedef struct _TpChannel TpChannel;

A proxy object for a Telepathy channel.

Since 0.7.1

### TpChannelClass

    typedef struct _TpChannelClass TpChannelClass;

The class of a TpChannel.

Since 0.7.1

### TP_ERRORS_REMOVED_FROM_GROUP

    #define TP_ERRORS_REMOVED_FROM_GROUP (tp_errors_removed_from_group_quark ())

GError domain representing the local user being removed from a channel with the Group interface. The `code` in a GError with this domain must be a member of TpChannelGroupChangeReason.

This error may be raised on non-Group channels with certain reason codes if there's no better error code to use (mainly `TP_CHANNEL_GROUP_CHANGE_REASON_NONE`).

This macro expands to a function call returning a GQuark.

Since 0.7.1

### tp_cli_channel_call_close ()

    TpProxyPendingCall* tp_cli_channel_call_close           (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_close callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a Close method call.

Request that the channel be closed. This is not the case until the Closed signal has been emitted, and depending on the connection manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_call_get_channel_type ()

    TpProxyPendingCall* tp_cli_channel_call_get_channel_type
                                                            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_channel_type callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a GetChannelType method call.

Returns the interface name for the type of this channel.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_call_get_handle ()

    TpProxyPendingCall* tp_cli_channel_call_get_handle      (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_handle callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a GetHandle method call.

Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or zero if it is transient and defined only by its contents.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_call_get_interfaces ()

    TpProxyPendingCall* tp_cli_channel_call_get_interfaces  (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_channel_callback_for_get_interfaces callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a GetInterfaces method call.

Get the optional interfaces implemented by the channel.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_channel_callback_for_close ()

    void                (*tp_cli_channel_callback_for_close)
                                                            (TpChannel *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a Close method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_callback_for_get_channel_type ()

    void                (*tp_cli_channel_callback_for_get_channel_type)
                                                            (TpChannel *proxy,
                                                             const gchar *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a GetChannelType method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out0` : | Used to return an 'out' argument if `error` is `NULL`: The interface name
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_callback_for_get_handle ()

    void                (*tp_cli_channel_callback_for_get_handle)
                                                            (TpChannel *proxy,
                                                             guint out0,
                                                             guint out1,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a GetHandle method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out0` : | Used to return an 'out' argument if `error` is `NULL`: The handle type, or zero if this channel does not correspond to any particular handle
`out1` : | Used to return an 'out' argument if `error` is `NULL`: The handle, or zero if this channel does not correspond to any particular handle
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_callback_for_get_interfaces ()

    void                (*tp_cli_channel_callback_for_get_interfaces)
                                                            (TpChannel *proxy,
                                                             const gchar **out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when a GetInterfaces method call succeeds or fails.

`proxy` : | the proxy on which the call was made
`out0` : | Used to return an 'out' argument if `error` is `NULL`: An array of the D-Bus interface names
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_channel_run_close ()

    gboolean            tp_cli_channel_run_close            (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method Close and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Request that the channel be closed. This is not the case until the Closed signal has been emitted, and depending on the connection manager this may simply remove you from the channel on the server, rather than causing it to stop existing entirely. Some channels such as contact list channels may not be closed.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_run_get_channel_type ()

    gboolean            tp_cli_channel_run_get_channel_type (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetChannelType and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns the interface name for the type of this channel.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out0` : | Used to return an 'out' argument if `TRUE` is returned: The interface name
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_run_get_handle ()

    gboolean            tp_cli_channel_run_get_handle       (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             guint *out1,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetHandle and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns the handle type and number if this channel represents a communication with a particular contact, room or server-stored list, or zero if it is transient and defined only by its contents.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out0` : | Used to return an 'out' argument if `TRUE` is returned: The handle type, or zero if this channel does not correspond to any particular handle
`out1` : | Used to return an 'out' argument if `TRUE` is returned: The handle, or zero if this channel does not correspond to any particular handle
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_run_get_interfaces ()

    gboolean            tp_cli_channel_run_get_interfaces   (TpChannel *proxy,
                                                             gint timeout_ms,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetInterfaces and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Get the optional interfaces implemented by the channel.

`proxy` : | A TpChannel or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out0` : | Used to return an 'out' argument if `TRUE` is returned: An array of the D-Bus interface names
`error` : | If not `NULL`, used to return errors if `FALSE` is returned
`loop` : | If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`
Returns : | TRUE on success, FALSE and sets `error` on error

### tp_cli_channel_connect_to_closed ()

    TpProxySignalConnection* tp_cli_channel_connect_to_closed
                                                            (TpChannel *proxy,
                                                             tp_cli_channel_signal_callback_closed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

Connect a handler to the signal Closed.

Emitted when the channel has been closed. Method calls on the channel are no longer valid after this signal has been emitted, and the connection manager may then remove the object from the bus at any point.

`proxy` : | A TpChannel or subclass
`callback` : | Callback to be called when the signal is received
`user_data` : | User-supplied data for the callback
`destroy` : | Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
`error` : | If not `NULL`, used to raise an error if `NULL` is returned
Returns : | a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or `NULL` if the proxy does not have the desired interface or has become invalid.

### tp_cli_channel_signal_callback_closed ()

    void                (*tp_cli_channel_signal_callback_closed)
                                                            (TpChannel *proxy,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal Closed.

`proxy` : | The proxy on which `tp_cli_channel_connect_to_closed()` was called
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

## Property Details

### The `"channel-ready"` property

      "channel-ready"            gboolean              : Read

Initially `FALSE`; changes to `TRUE` when introspection of the channel has finished and it's ready for use.

By the time this property becomes `TRUE`, the "channel-type", "handle-type" and "handle" properties will have been set (if introspection did not fail), and any extra interfaces will have been set up.

Default value: FALSE

### The `"connection"` property

      "connection"               TpConnection          : Read / Write / Construct Only

The TpConnection to which this TpChannel belongs. Used for e.g. handle manipulation.

## See Also

TpConnection, channel-group, channel-text, channel-media