TpCallChannel: telepathy-glib API Reference Manual

## TpCallChannel TpCallChannel — proxy object for a call channel |

## Functions

GPtrArray * | tp_call_channel_get_contents ()
TpCallState | tp_call_channel_get_state ()
gboolean | tp_call_channel_has_hardware_streaming ()
gboolean | tp_call_channel_has_initial_audio ()
gboolean | tp_call_channel_has_initial_video ()
gboolean | tp_call_channel_has_mutable_contents ()
GHashTable * | tp_call_channel_get_members ()
gboolean | tp_call_channel_has_dtmf ()
gboolean | tp_call_channel_has_hold ()
void | tp_call_channel_send_tones_async ()
gboolean | tp_call_channel_send_tones_finish ()
void | tp_call_channel_set_ringing_async ()
gboolean | tp_call_channel_set_ringing_finish ()
void | tp_call_channel_set_queued_async ()
gboolean | tp_call_channel_set_queued_finish ()
void | tp_call_channel_accept_async ()
gboolean | tp_call_channel_accept_finish ()
void | tp_call_channel_hangup_async ()
gboolean | tp_call_channel_hangup_finish ()
void | tp_call_channel_add_content_async ()
TpCallContent * | tp_call_channel_add_content_finish ()
void | tp_call_channel_request_hold_async ()
gboolean | tp_call_channel_request_hold_finish ()

## Properties

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

## Signals

void | content-added | Run Last
void | content-removed | Run Last
void | members-changed | Run Last
void | state-changed | Run Last

## Types and Values

struct | TpCallChannel
struct | TpCallChannelClass
#define | TP_CALL_CHANNEL_FEATURE_CORE
struct | TpCallStateReason

## Object Hierarchy

        GBoxed
        ╰── TpCallStateReason
        GObject
        ╰── TpProxy
            ╰── TpChannel
                ╰── TpCallChannel

## Implemented Interfaces

TpCallChannel implements TpChannelIface.

## Includes

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

## Description

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

## Functions

### tp_call_channel_get_contents ()

    GPtrArray *
    tp_call_channel_get_contents (TpCallChannel *self);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

Since: 0.17.6

## Types and Values

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

#### Members

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

## Property Details

### The `“contents”` property

      “contents”                 GPtrArray *

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.

Owner: TpCallChannel

Flags: Read

Since: 0.17.5

### The `“flags”` property

      “flags”                    guint

A TpCallFlags specifying the flags of the call state.

Owner: TpCallChannel

Flags: Read

Default value: 0

Since: 0.17.5

### The `“hardware-streaming”` property

      “hardware-streaming”       gboolean

Whether or not the streaming is done by dedicated hardware.

Owner: TpCallChannel

Flags: Read

Default value: FALSE

Since: 0.17.5

### The `“hold-state”` property

      “hold-state”               guint

A TpLocalHoldState specifying if the Call is currently held

Owner: TpCallChannel

Flags: Read

Default value: 0

Since: 0.17.6

### The `“hold-state-reason”` property

      “hold-state-reason”        guint

A TpLocalHoldStateReason specifying why the Call is currently held.

Owner: TpCallChannel

Flags: Read

Default value: 0

Since: 0.17.6

### The `“initial-audio”` property

      “initial-audio”            gboolean

Whether or not the Call was started with audio.

Owner: TpCallChannel

Flags: Read

Default value: FALSE

Since: 0.17.5

### The `“initial-audio-name”` property

      “initial-audio-name”       gchar *

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

Owner: TpCallChannel

Flags: Read

Default value: NULL

Since: 0.17.5

### The `“initial-video”` property

      “initial-video”            gboolean

Whether or not the Call was started with video.

Owner: TpCallChannel

Flags: Read

Default value: FALSE

Since: 0.17.5

### The `“initial-video-name”` property

      “initial-video-name”       gchar *

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

Owner: TpCallChannel

Flags: Read

Default value: NULL

Since: 0.17.5

### The `“mutable-contents”` property

      “mutable-contents”         gboolean

Whether or not call contents can be added or removed.

Owner: TpCallChannel

Flags: Read

Default value: FALSE

Since: 0.17.5

### The `“state”` property

      “state”                    guint

A TpCallState specifying the state of the call.

Owner: TpCallChannel

Flags: Read

Default value: 0

Since: 0.17.5

### The `“state-details”` property

      “state-details”            GHashTable *

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

Owner: TpCallChannel

Flags: Read

Since: 0.17.5

### The `“state-reason”` property

      “state-reason”             TpCallStateReason *

Reason why “state” last changed.

Owner: TpCallChannel

Flags: Read

Since: 0.17.5

## Signal Details

### The `“content-added”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.17.5

### The `“content-removed”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.17.5

### The `“members-changed”` signal

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

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.

#### Parameters

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

Flags: Run Last

Since: 0.17.5

### The `“state-changed”` signal

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

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

#### Parameters

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

Flags: Run Last

Since: 0.17.5