## TpCallChannel

TpCallChannel — proxy object for a call channel

## Synopsis

    #include <telepathy-glib/telepathy-glib.h>

    struct              TpCallChannel;
    struct              TpCallChannelClass;
    #define             TP_CALL_CHANNEL_FEATURE_CORE

    struct              TpCallStateReason;

    GPtrArray *         tp_call_channel_get_contents        (TpCallChannel *self);
    TpCallState         tp_call_channel_get_state           (TpCallChannel *self,
                                                             TpCallFlags *flags,
                                                             GHashTable **details,
                                                             TpCallStateReason **reason);
    gboolean            tp_call_channel_has_hardware_streaming
                                                            (TpCallChannel *self);
    gboolean            tp_call_channel_has_initial_audio   (TpCallChannel *self,
                                                             const gchar **initial_audio_name);
    gboolean            tp_call_channel_has_initial_video   (TpCallChannel *self,
                                                             const gchar **initial_video_name);
    gboolean            tp_call_channel_has_mutable_contents
                                                            (TpCallChannel *self);
    GHashTable *        tp_call_channel_get_members         (TpCallChannel *self);

    gboolean            tp_call_channel_has_dtmf            (TpCallChannel *self);
    gboolean            tp_call_channel_has_hold            (TpCallChannel *self);
    void                tp_call_channel_send_tones_async    (TpCallChannel *self,
                                                             const gchar *tones,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_send_tones_finish   (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

    void                tp_call_channel_set_ringing_async   (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_set_ringing_finish  (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_call_channel_set_queued_async    (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_set_queued_finish   (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_call_channel_accept_async        (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_accept_finish       (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_call_channel_hangup_async        (TpCallChannel *self,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *detailed_reason,
                                                             const gchar *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_hangup_finish       (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_call_channel_add_content_async   (TpCallChannel *self,
                                                             const gchar *name,
                                                             TpMediaStreamType type,
                                                             TpMediaStreamDirection initial_direction,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    TpCallContent *     tp_call_channel_add_content_finish  (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_call_channel_request_hold_async  (TpCallChannel *self,
                                                             gboolean hold,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_call_channel_request_hold_finish (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

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

      GBoxed
       +----TpCallStateReason

## Implemented Interfaces

TpCallChannel implements TpChannelIface.

## Properties

      "contents"                 GPtrArray*            : Read
      "flags"                    guint                 : Read
      "hardware-streaming"       gboolean              : Read
      "hold-state"               guint                 : Read
      "hold-state-reason"        guint                 : Read
      "initial-audio"            gboolean              : Read
      "initial-audio-name"       gchar*                : Read
      "initial-video"            gboolean              : Read
      "initial-video-name"       gchar*                : Read
      "mutable-contents"         gboolean              : Read
      "state"                    guint                 : Read
      "state-details"            GHashTable*           : Read
      "state-reason"             TpCallStateReason*    : Read

## Signals

      "content-added"                                  : Run Last
      "content-removed"                                : Run Last
      "members-changed"                                : Run Last
      "state-changed"                                  : Run Last

## Description

TpCallChannel is a sub-class of TpChannel providing convenient API to make calls

## Details

### struct TpCallChannel

    struct TpCallChannel;

Data structure representing a TpCallChannel.

Since 0.17.5

### struct TpCallChannelClass

    struct TpCallChannelClass {
    };

The class of a TpCallChannel.

Since 0.17.5

### TP_CALL_CHANNEL_FEATURE_CORE

    #define             TP_CALL_CHANNEL_FEATURE_CORE

Expands to a call to a function that returns a quark for the "core" feature on a TpCallChannel.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to trigger the callback.

### struct TpCallStateReason

    struct TpCallStateReason {
      TpHandle actor;
      TpCallStateChangeReason reason;
      gchar *dbus_reason;
      gchar *message;
    };

Data structure representing the reason for a call state change.

TpHandle `actor`; | the contact responsible for the change, or 0 if no contact was responsible
TpCallStateChangeReason `reason`; | the reason for the change. If TP_CALL_STATE_CHANGE_REASON_USER_REQUESTED then the `actor` member will dictate whether it was the local user or a remote contact responsible
gchar *`dbus_reason`; | A specific reason for the change, which may be a D-Bus error in the Telepathy namespace, a D-Bus error in any other namespace (for implementation-specific errors), or the empty string to indicate that the state change was not an error
gchar *`message`; | A developer readable debug message giving the reason for the state change.

Since 0.17.5

### tp_call_channel_get_contents ()

    GPtrArray *         tp_call_channel_get_contents        (TpCallChannel *self);

`self` : | a TpCallChannel
Returns : | the value of "contents". [transfer none][type GLib.PtrArray][element-type TelepathyGLib.CallContent]

Since 0.17.5

### tp_call_channel_get_state ()

    TpCallState         tp_call_channel_get_state           (TpCallChannel *self,
                                                             TpCallFlags *flags,
                                                             GHashTable **details,
                                                             TpCallStateReason **reason);

`self` : | a TpCallChannel
`flags` : | a place to set the value of "flags". [out][allow-none][transfer none]
`details` : | a place to set the value of "state-details". [out][allow-none][transfer none]
`reason` : | a place to set the value of "state-reason". [out][allow-none][transfer none]
Returns : | the value of "state"

Since 0.17.5

### tp_call_channel_has_hardware_streaming ()

    gboolean            tp_call_channel_has_hardware_streaming
                                                            (TpCallChannel *self);

`self` : | a TpCallChannel
Returns : | the value of "hardware-streaming"

Since 0.17.5

### tp_call_channel_has_initial_audio ()

    gboolean            tp_call_channel_has_initial_audio   (TpCallChannel *self,
                                                             const gchar **initial_audio_name);

`self` : | a TpCallChannel
`initial_audio_name` : | a place to set the value of "initial-audio-name". [out][allow-none][transfer none]
Returns : | the value of "initial-audio"

Since 0.17.5

### tp_call_channel_has_initial_video ()

    gboolean            tp_call_channel_has_initial_video   (TpCallChannel *self,
                                                             const gchar **initial_video_name);

`self` : | a TpCallChannel
`initial_video_name` : | a place to set the value of "initial-video-name". [out][allow-none][transfer none]
Returns : | the value of "initial-video"

Since 0.17.5

### tp_call_channel_has_mutable_contents ()

    gboolean            tp_call_channel_has_mutable_contents
                                                            (TpCallChannel *self);

`self` : | a TpCallChannel
Returns : | the value of "mutable-contents"

Since 0.17.5

### tp_call_channel_get_members ()

    GHashTable *        tp_call_channel_get_members         (TpCallChannel *self);

Get the members of this call.

The TpContact objects are guaranteed to have all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | a TpCallChannel
Returns : | GHashTable mapping TpContact to its new TpCallMemberFlags. [transfer none][type GLib.HashTable][element-type TelepathyGLib.Contact uint]

Since 0.17.5

### tp_call_channel_has_dtmf ()

    gboolean            tp_call_channel_has_dtmf            (TpCallChannel *self);

Whether or not `self` can send DTMF tones using `tp_call_channel_send_tones_async()`. To be able to send DTMF tones, at least one of `self`'s "contents" must implement `TP_IFACE_CALL_CONTENT_INTERFACE_DTMF` interface.

`self` : | a TpCallChannel
Returns : | whether or not `self` can send DTMF tones.

Since 0.17.5

### tp_call_channel_has_hold ()

    gboolean            tp_call_channel_has_hold            (TpCallChannel *self);

Whether or not `self` has the `TP_IFACE_CHANNEL_INTERFACE_HOLD` interfaces

`self` : | a TpCallChannel
Returns : | whether or not `self` supports Hold

Since 0.17.6

### tp_call_channel_send_tones_async ()

    void                tp_call_channel_send_tones_async    (TpCallChannel *self,
                                                             const gchar *tones,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Send `tones` on every of `self`'s contents which have the `TP_IFACE_CALL_CONTENT_INTERFACE_DTMF` interface.

For more details, see `tp_call_content_send_tones_async()`.

`self` : | a TpCallChannel
`tones` : | a string representation of one or more DTMF events.
`cancellable` : | optional GCancellable object, `NULL` to ignore
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_send_tones_finish ()

    gboolean            tp_call_channel_send_tones_finish   (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_send_tones_async()`.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | `TRUE` on success, `FALSE` otherwise.

Since 0.17.5

### tp_call_channel_set_ringing_async ()

    void                tp_call_channel_set_ringing_async   (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Indicate that the local user has been alerted about the incoming call.

`self` : | a TpCallChannel
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_set_ringing_finish ()

    gboolean            tp_call_channel_set_ringing_finish  (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_set_ringing_async()`.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill

Since 0.17.5

### tp_call_channel_set_queued_async ()

    void                tp_call_channel_set_queued_async    (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Notifies the CM that the local user is already in a call, so this call has been put in a call-waiting style queue.

`self` : | a TpCallChannel
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_set_queued_finish ()

    gboolean            tp_call_channel_set_queued_finish   (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_set_queued_async()`.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill

Since 0.17.5

### tp_call_channel_accept_async ()

    void                tp_call_channel_accept_async        (TpCallChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

For incoming calls with "state" set to `TP_CALL_STATE_INITIALISED`, accept the incoming call. This changes "state" to `TP_CALL_STATE_ACCEPTED`.

For outgoing calls with "state" set to `TP_CALL_STATE_PENDING_INITIATOR`, actually call the remote contact; this changes "state" to `TP_CALL_STATE_INITIALISING`.

`self` : | a TpCallChannel
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_accept_finish ()

    gboolean            tp_call_channel_accept_finish       (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_accept_async()`.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill

Since 0.17.5

### tp_call_channel_hangup_async ()

    void                tp_call_channel_hangup_async        (TpCallChannel *self,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *detailed_reason,
                                                             const gchar *message,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request that the call is ended. All contents will be removed from `self` so that the "contents" property will be the empty list.

`self` : | a TpCallChannel
`reason` : | a TpCallStateChangeReason
`detailed_reason` : | a more specific reason for the call hangup, if one is available, or an empty or `NULL` string otherwise
`message` : | a human-readable message to be sent to the remote contact(s)
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_hangup_finish ()

    gboolean            tp_call_channel_hangup_finish       (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_hangup_async()`.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill

Since 0.17.5

### tp_call_channel_add_content_async ()

    void                tp_call_channel_add_content_async   (TpCallChannel *self,
                                                             const gchar *name,
                                                             TpMediaStreamType type,
                                                             TpMediaStreamDirection initial_direction,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Request that a new Content of type `type` is added to `self`. Callers should check the value of the "mutable-contents" property before trying to add another content as it might not be allowed.

`self` : | a TpCallChannel
`name` : | the suggested name of the content to add
`type` : | the media stream type of the content to be added to the call, from TpMediaStreamType
`initial_direction` : | The initial direction of the content
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.5

### tp_call_channel_add_content_finish ()

    TpCallContent *     tp_call_channel_add_content_finish  (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes `tp_call_channel_add_content_async()`.

The returned TpCallContent is NOT guaranteed to have `TP_CALL_CONTENT_FEATURE_CORE` prepared.

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill
Returns : | reference to the new TpCallContent. [transfer full]

Since 0.17.5

### tp_call_channel_request_hold_async ()

    void                tp_call_channel_request_hold_async  (TpCallChannel *self,
                                                             gboolean hold,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Requests that the connection manager holds or unholds the call. Watch "hold-state" property to know when the channel goes on hold or is unheld. Unholding may fail if the streaming implementation can not obtain all the resources needed to restart the call.

`self` : | a TpCallChannel
`hold` : | Whether to request a hold or a unhold
`callback` : | a callback to call when the operation finishes
`user_data` : | data to pass to `callback`

Since 0.17.6

### tp_call_channel_request_hold_finish ()

    gboolean            tp_call_channel_request_hold_finish (TpCallChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes tp_call_channel_request_hold_async

`self` : | a TpCallChannel
`result` : | a GAsyncResult
`error` : | a GError to fill

Since 0.17.6

## Property Details

### The `"contents"` property

      "contents"                 GPtrArray*            : Read

GPtrArray of TpCallContent objects. The list of content objects that are part of this call.

It is NOT guaranteed that `TP_CALL_CONTENT_FEATURE_CORE` is prepared on those objects.

Since 0.17.5

### The `"flags"` property

      "flags"                    guint                 : Read

A TpCallFlags specifying the flags of the call state.

Default value: 0

Since 0.17.5

### The `"hardware-streaming"` property

      "hardware-streaming"       gboolean              : Read

Whether or not the streaming is done by dedicated hardware.

Default value: FALSE

Since 0.17.5

### The `"hold-state"` property

      "hold-state"               guint                 : Read

A TpLocalHoldState specifying if the Call is currently held

Default value: 0

Since 0.17.6

### The `"hold-state-reason"` property

      "hold-state-reason"        guint                 : Read

A TpLocalHoldStateReason specifying why the Call is currently held.

Default value: 0

Since 0.17.6

### The `"initial-audio"` property

      "initial-audio"            gboolean              : Read

Whether or not the Call was started with audio.

Default value: FALSE

Since 0.17.5

### The `"initial-audio-name"` property

      "initial-audio-name"       gchar*                : Read

If "initial-audio" is set to `TRUE`, then this property will is the name of the intial audio content, `NULL` otherwise.

Default value: NULL

Since 0.17.5

### The `"initial-video"` property

      "initial-video"            gboolean              : Read

Whether or not the Call was started with video.

Default value: FALSE

Since 0.17.5

### The `"initial-video-name"` property

      "initial-video-name"       gchar*                : Read

If "initial-video" is set to `TRUE`, then this property will is the name of the intial video content, `NULL` otherwise.

Default value: NULL

Since 0.17.5

### The `"mutable-contents"` property

      "mutable-contents"         gboolean              : Read

Whether or not call contents can be added or removed.

Default value: FALSE

Since 0.17.5

### The `"state"` property

      "state"                    guint                 : Read

A TpChannelCallState specifying the state of the call.

Default value: 0

Since 0.17.5

### The `"state-details"` property

      "state-details"            GHashTable*           : Read

Detailed infoermation about "state". It is a GHashTable mapping gchar*->GValue, it can be accessed using the tp_asv_* functions.

Since 0.17.5

### The `"state-reason"` property

      "state-reason"             TpCallStateReason*    : Read

Reason why "state" last changed.

Since 0.17.5

## Signal Details

### The `"content-added"` signal

    void                user_function                      (TpCallChannel *self,
                                                            GObject       *content,
                                                            gpointer       user_data)      : Run Last

The ::content-added signal is emitted whenever a TpCallContent is added to `self`.

It is NOT guaranteed that `TP_CALL_CONTENT_FEATURE_CORE` is prepared on `content`.

`self` : | the TpCallChannel
`content` : | the newly added TpCallContent
`user_data` : | user data set when the signal handler was connected.

Since 0.17.5

### The `"content-removed"` signal

    void                user_function                      (TpCallChannel     *self,
                                                            GObject           *content,
                                                            TpCallStateReason *reason,
                                                            gpointer           user_data)      : Run Last

The ::content-removed signal is emitted whenever a TpCallContent is removed from `self`.

It is NOT guaranteed that `TP_CALL_CONTENT_FEATURE_CORE` is prepared on `content`.

`self` : | the TpCallChannel
`content` : | the newly removed TpCallContent
`reason` : | a TpCallStateReason
`user_data` : | user data set when the signal handler was connected.

Since 0.17.5

### The `"members-changed"` signal

    void                user_function                      (TpCallChannel     *self,
                                                            GHashTable        *updates,
                                                            GPtrArray         *removed,
                                                            TpCallStateReason *reason,
                                                            gpointer           user_data)      : Run Last

The ::members-changed signal is emitted whenever the call's members changes.

The TpContact objects are guaranteed to have all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

`self` : | the TpCallChannel
`updates` : | GHashTable mapping TpContact to its new TpCallMemberFlags. [type GLib.HashTable][element-type TelepathyGLib.Contact uint]
`removed` : | GPtrArray of TpContact removed from the call members. [type GLib.PtrArray][element-type TelepathyGLib.Contact]
`reason` : | the TpCallStateReason for the change
`user_data` : | user data set when the signal handler was connected.

Since 0.17.5

### The `"state-changed"` signal

    void                user_function                      (TpCallChannel     *self,
                                                            guint              state,
                                                            guint              flags,
                                                            TpCallStateReason *reason,
                                                            GHashTable        *details,
                                                            gpointer           user_data)      : Run Last

The ::state-changed signal is emitted whenever the call state changes.

`self` : | the TpCallChannel
`state` : | the new TpCallState
`flags` : | the new TpCallFlags
`reason` : | the TpCallStateReason for the change
`details` : | additional details as a GHashTable readable using the tp_asv_* functions. [element-type utf8 GObject.Value]
`user_data` : | user data set when the signal handler was connected.

Since 0.17.5