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

TpCallChannel

Functions

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

Functions

tp_call_channel_get_contents ()

Parameters

Returns

tp_call_channel_get_state ()

Parameters

Returns

tp_call_channel_has_hardware_streaming ()

Parameters

Returns

tp_call_channel_has_initial_audio ()

Parameters

Returns

tp_call_channel_has_initial_video ()

Parameters

Returns

tp_call_channel_has_mutable_contents ()

Parameters

Returns

tp_call_channel_get_members ()

Parameters

Returns

tp_call_channel_has_dtmf ()

Parameters

Returns

tp_call_channel_has_hold ()

Parameters

Returns

tp_call_channel_send_tones_async ()

Parameters

tp_call_channel_send_tones_finish ()

Parameters

Returns

tp_call_channel_set_ringing_async ()

Parameters

tp_call_channel_set_ringing_finish ()

Parameters

tp_call_channel_set_queued_async ()

Parameters

tp_call_channel_set_queued_finish ()

Parameters

tp_call_channel_accept_async ()

Parameters

tp_call_channel_accept_finish ()

Parameters

tp_call_channel_hangup_async ()

Parameters

tp_call_channel_hangup_finish ()

Parameters

tp_call_channel_add_content_async ()

Parameters

tp_call_channel_add_content_finish ()

Parameters

Returns

tp_call_channel_request_hold_async ()

Parameters

tp_call_channel_request_hold_finish ()

Parameters

Types and Values

struct TpCallChannel

struct TpCallChannelClass

TP_CALL_CHANNEL_FEATURE_CORE

struct TpCallStateReason

Members

Property Details

The “contents” property

The “flags” property

The “hardware-streaming” property

The “hold-state” property

The “hold-state-reason” property

The “initial-audio” property

The `“contents”` property

The `“flags”` property

The `“hardware-streaming”` property

The `“hold-state”` property

The `“hold-state-reason”` property

The `“initial-audio”` property

The `“initial-audio-name”` property

The `“initial-video”` property

The `“initial-video-name”` property

The `“mutable-contents”` property

The `“state”` property

The `“state-details”` property

The `“state-reason”` property

The `“content-added”` signal

The `“content-removed”` signal

The `“members-changed”` signal

The `“state-changed”` signal