TpCallChannel

TpCallChannel — proxy object for a call channel

Functions

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

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