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