TpBaseCallChannel

## TpBaseCallChannel TpBaseCallChannel — base class for TpSvcChannelTypeCall implementations |

## Synopsis

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

                        TpBaseCallChannel;
    struct              TpBaseCallChannelClass;
    void                (*TpBaseCallChannelVoidFunc)        (TpBaseCallChannel *self);
    TpBaseCallContent * (*TpBaseCallChannelAddContentFunc)  (TpBaseCallChannel *self,
                                                             const gchar *name,
                                                             TpMediaStreamType media,
                                                             TpMediaStreamDirection initial_direction,
                                                             GError **error);
    void                (*TpBaseCallChannelHangupFunc)      (TpBaseCallChannel *self,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *detailed_reason,
                                                             const gchar *message);
    TpCallState         tp_base_call_channel_get_state      (TpBaseCallChannel *self);
    void                tp_base_call_channel_set_state      (TpBaseCallChannel *self,
                                                             TpCallState state,
                                                             guint actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);
    gboolean            tp_base_call_channel_has_initial_audio
                                                            (TpBaseCallChannel *self,
                                                             const gchar **initial_audio_name);
    gboolean            tp_base_call_channel_has_initial_video
                                                            (TpBaseCallChannel *self,
                                                             const gchar **initial_video_name);
    gboolean            tp_base_call_channel_has_mutable_contents
                                                            (TpBaseCallChannel *self);
    GList *             tp_base_call_channel_get_contents   (TpBaseCallChannel *self);
    void                tp_base_call_channel_add_content    (TpBaseCallChannel *self,
                                                             TpBaseCallContent *content);
    void                tp_base_call_channel_remove_content (TpBaseCallChannel *self,
                                                             TpBaseCallContent *content,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);
    void                tp_base_call_channel_update_member_flags
                                                            (TpBaseCallChannel *self,
                                                             TpHandle contact,
                                                             TpCallMemberFlags new_flags,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);
    void                tp_base_call_channel_remove_member  (TpBaseCallChannel *self,
                                                             TpHandle contact,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);
    GHashTable *        tp_base_call_channel_get_call_members
                                                            (TpBaseCallChannel *self);
    void                tp_base_call_channel_remote_accept  (TpBaseCallChannel *self);
    gboolean            tp_base_call_channel_is_accepted    (TpBaseCallChannel *self);

## Object Hierarchy

      GObject
       +----TpBaseChannel
             +----TpBaseCallChannel
                   +----TpBaseMediaCallChannel

## Implemented Interfaces

TpBaseCallChannel implements TpSvcDBusProperties, TpSvcChannel, TpChannelIface, TpExportableChannel, TpSvcChannelTypeCall and TpSvcChannelInterfaceDTMF.

## Properties

      "call-flags"               guint                 : Read
      "call-members"             GHashTable_guint+guint_*  : Read
      "call-state"               guint                 : Read
      "call-state-details"       GHashTable_gchararray+GValue_*  : Read
      "call-state-reason"        GValueArray_guint+guint+gchararray+gchararray_*  : Read
      "contents"                 GPtrArray_DBusGObjectPath_*  : Read
      "hardware-streaming"       gboolean              : Read
      "initial-audio"            gboolean              : Read / Write / Construct Only
      "initial-audio-name"       gchar*                : Read / Write / Construct Only
      "initial-tones"            gchar*                : Read / Write / Construct Only
      "initial-transport"        guint                 : Read / Write / Construct Only
      "initial-video"            gboolean              : Read / Write / Construct Only
      "initial-video-name"       gchar*                : Read / Write / Construct Only
      "member-identifiers"       GHashTable_guint+gchararray_*  : Read
      "mutable-contents"         gboolean              : Read / Write / Construct Only

## Description

This base class makes it easier to write TpSvcChannelTypeCall implementations by implementing its properties, and some of its methods.

Subclasses should fill in TpBaseCallChannelClass.accept, TpBaseCallChannelClass.add_content and TpBaseCallChannelClass.hangup virtual function.

## Details

### TpBaseCallChannel

    typedef struct _TpBaseCallChannel TpBaseCallChannel;

A base class for call channel implementations

Since 0.17.5

### struct TpBaseCallChannelClass

    struct TpBaseCallChannelClass {
      TpBaseCallChannelVoidFunc set_ringing;
      TpBaseCallChannelVoidFunc set_queued;
      TpBaseCallChannelVoidFunc accept;
      TpBaseCallChannelAddContentFunc add_content;
      TpBaseCallChannelHangupFunc hangup;
    };

The class structure for TpBaseCallChannel

TpBaseCallChannelVoidFunc `set_ringing`; | Notify members that client is ringing.
TpBaseCallChannelVoidFunc `set_queued`; | Notify members that call is queued.
TpBaseCallChannelVoidFunc `accept`; | accept the call. Note that TpBaseMediaCallChannel subclasses should not override this virtual method, but TpBaseMediaCallChannelClass.accept instead.
TpBaseCallChannelAddContentFunc `add_content`; | add content to the call. Implementation must call `tp_base_call_channel_add_content()`. Can be `NULL` if "mutable-contents" is `FALSE`.
TpBaseCallChannelHangupFunc `hangup`; | hangup the call.

Since 0.17.5

### TpBaseCallChannelVoidFunc ()

    void                (*TpBaseCallChannelVoidFunc)        (TpBaseCallChannel *self);

Signature of an implementation of TpBaseCallChannelClass.set_ringing, TpBaseCallChannelClass.set_queued and TpBaseCallChannelClass.accept.

`self` : | a TpBaseCallChannel

Since 0.17.5

### TpBaseCallChannelAddContentFunc ()

    TpBaseCallContent * (*TpBaseCallChannelAddContentFunc)  (TpBaseCallChannel *self,
                                                             const gchar *name,
                                                             TpMediaStreamType media,
                                                             TpMediaStreamDirection initial_direction,
                                                             GError **error);

Signature of an implementation of TpBaseCallChannelClass.add_content.

`self` : | a TpBaseCallChannel
`name` : | the name for the new content
`media` : | a TpMediaStreamType
`initial_direction` : | the desired initial direction of streams in the new content
`error` : | a GError to fill
Returns : | a borrowed TpBaseCallContent.

Since 0.17.5

### TpBaseCallChannelHangupFunc ()

    void                (*TpBaseCallChannelHangupFunc)      (TpBaseCallChannel *self,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *detailed_reason,
                                                             const gchar *message);

Signature of an implementation of TpBaseCallChannelClass.hangup.

`self` : | a TpBaseCallChannel
`reason` : | the TpCallStateChangeReason of the change
`detailed_reason` : | a more specific reason for the call hangup, if one is available, or an empty string otherwise.
`message` : | a human-readable message to be sent to the remote contact(s).

Since 0.17.5

### tp_base_call_channel_get_state ()

    TpCallState         tp_base_call_channel_get_state      (TpBaseCallChannel *self);

`self` : | a TpBaseCallChannel
Returns : | the value of "call-state"

Since 0.17.5

### tp_base_call_channel_set_state ()

    void                tp_base_call_channel_set_state      (TpBaseCallChannel *self,
                                                             TpCallState state,
                                                             guint actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);

Changes the call state and emit StateChanged signal with the new state.

`self` : | a TpBaseCallChannel
`state` : | the new TpCallState
`actor_handle` : | the contact responsible for the change, or 0 if no contact was responsible.
`reason` : | the TpCallStateChangeReason of the change
`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.
`message` : | an optional debug message, to expediate debugging the potentially many processes involved in a call.

Since 0.17.5

### tp_base_call_channel_has_initial_audio ()

    gboolean            tp_base_call_channel_has_initial_audio
                                                            (TpBaseCallChannel *self,
                                                             const gchar **initial_audio_name);

`self` : | a TpBaseCallChannel
`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_base_call_channel_has_initial_video ()

    gboolean            tp_base_call_channel_has_initial_video
                                                            (TpBaseCallChannel *self,
                                                             const gchar **initial_video_name);

`self` : | a TpBaseCallChannel
`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_base_call_channel_has_mutable_contents ()

    gboolean            tp_base_call_channel_has_mutable_contents
                                                            (TpBaseCallChannel *self);

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

Since 0.17.5

### tp_base_call_channel_get_contents ()

    GList *             tp_base_call_channel_get_contents   (TpBaseCallChannel *self);

Get the contents of this call. The GList and its elements must not be freed and should be copied before doing any modification.

`self` : | a TpBaseCallChannel
Returns : | a GList of TpBaseCallContent

Since 0.17.5

### tp_base_call_channel_add_content ()

    void                tp_base_call_channel_add_content    (TpBaseCallChannel *self,
                                                             TpBaseCallContent *content);

Add `content` to `self`. If `content`'s "disposition" is `TP_CALL_CONTENT_DISPOSITION_INITIAL`, also set "initial-audio" and "initial-audio-name" properties (or "initial-video" and "initial-video-name"). Note that it is not allowed to add INITIAL contents after having registered `self` on the bus.

`self` : | a TpBaseCallChannel
`content` : | a TpBaseCallContent to add

Since 0.17.5

### tp_base_call_channel_remove_content ()

    void                tp_base_call_channel_remove_content (TpBaseCallChannel *self,
                                                             TpBaseCallContent *content,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);

Remove `content` from `self`.

`self` : | a TpBaseCallChannel
`content` : | a TpBaseCallContent to remove
`actor_handle` : | the contact responsible for the change, or 0 if no contact was responsible.
`reason` : | the TpCallStateChangeReason of the change
`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.
`message` : | an optional debug message, to expediate debugging the potentially many processes involved in a call.

Since 0.17.5

### tp_base_call_channel_update_member_flags ()

    void                tp_base_call_channel_update_member_flags
                                                            (TpBaseCallChannel *self,
                                                             TpHandle contact,
                                                             TpCallMemberFlags new_flags,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);

Add or update `contact` call member with `flags` flags.

`self` : | a TpBaseCallChannel
`contact` : | the contact to update
`new_flags` : | the new TpCallMemberFlags of `contact`
`actor_handle` : | the contact responsible for the change, or 0 if no contact was responsible.
`reason` : | the TpCallStateChangeReason of the change
`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.
`message` : | an optional debug message, to expediate debugging the potentially many processes involved in a call.

Since 0.17.5

### tp_base_call_channel_remove_member ()

    void                tp_base_call_channel_remove_member  (TpBaseCallChannel *self,
                                                             TpHandle contact,
                                                             TpHandle actor_handle,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);

Remove `contact` from call members.

`self` : | a TpBaseCallChannel
`contact` : | the contact to remove
`actor_handle` : | the contact responsible for the change, or 0 if no contact was responsible.
`reason` : | the TpCallStateChangeReason of the change
`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.
`message` : | an optional debug message, to expediate debugging the potentially many processes involved in a call.

Since 0.17.5

### tp_base_call_channel_get_call_members ()

    GHashTable *        tp_base_call_channel_get_call_members
                                                            (TpBaseCallChannel *self);

`self` : | a TpBaseCallChannel
Returns : | the value of "call-members".

Since 0.17.5

### tp_base_call_channel_remote_accept ()

    void                tp_base_call_channel_remote_accept  (TpBaseCallChannel *self);

Must be called when the remote contact accepted the call. "call-state" must be either `TP_CALL_STATE_INITIALISED` or `TP_CALL_STATE_INITIALISING` and will then change to `TP_CALL_STATE_ACCEPTED`.

Must be used only for outgoing calls.

`self` : | a TpBaseCallChannel

Since 0.17.5

### tp_base_call_channel_is_accepted ()

    gboolean            tp_base_call_channel_is_accepted    (TpBaseCallChannel *self);

`self` : | a TpBaseCallChannel
Returns : | Whether or not the call has been remotely accepted.

Since 0.17.5

## Property Details

### The `"call-flags"` property

      "call-flags"               guint                 : Read

The flags of this call.

Default value: 0

Since 0.17.5

### The `"call-members"` property

      "call-members"             GHashTable_guint+guint_*  : Read

GHashTable mapping TpHandle of each call member to their TpCallMemberFlags.

Since 0.17.5

### The `"call-state"` property

      "call-state"               guint                 : Read

The state of this call.

Default value: 0

Since 0.17.5

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

      "call-state-details"       GHashTable_gchararray+GValue_*  : Read

Details on the call state.

Since 0.17.5

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

      "call-state-reason"        GValueArray_guint+guint+gchararray+gchararray_*  : Read

The reason for last call state change.

Since 0.17.5

### The `"contents"` property

      "contents"                 GPtrArray_DBusGObjectPath_*  : Read

GPtrArray of object-paths of the TpBaseCallContent objects.

Since 0.17.5

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

      "hardware-streaming"       gboolean              : Read

Indicate to clients whether or not this Connection Manager has hardware streaming.

Default value: FALSE

Since 0.17.5

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

      "initial-audio"            gboolean              : Read / Write / Construct Only

If set to `TRUE` on a requested channel, subclass should immediately attempt to establish an audio stream to the remote contact.

Default value: FALSE

Since 0.17.5

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

      "initial-audio-name"       gchar*                : Read / Write / Construct Only

Name to use to create the audio TpBaseCallContent if "initial-audio" is set to `TRUE`.

Default value: "audio"

Since 0.17.5

### The `"initial-tones"` property

      "initial-tones"            gchar*                : Read / Write / Construct Only

DTMF Tones to be played on the channel created.

Default value: ""

Since 0.17.5

### The `"initial-transport"` property

      "initial-transport"        guint                 : Read / Write / Construct Only

If set to `TRUE` on a requested channel, this indicates the transport that should be used for this call.

Default value: 0

Since 0.17.5

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

      "initial-video"            gboolean              : Read / Write / Construct Only

If set to `TRUE` on a requested channel, subclass should immediately attempt to establish a video stream to the remote contact.

Default value: FALSE

Since 0.17.5

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

      "initial-video-name"       gchar*                : Read / Write / Construct Only

Name to use to create the video TpBaseCallContent if "initial-video" is set to `TRUE`.

Default value: "video"

Since 0.17.5

### The `"member-identifiers"` property

      "member-identifiers"       GHashTable_guint+gchararray_*  : Read

GHashTable mapping TpHandle of each call member to their identifiers.

Since 0.17.5

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

      "mutable-contents"         gboolean              : Read / Write / Construct Only

Indicate to clients whether or not they can add/remove contents.

Default value: FALSE

Since 0.17.5

## See Also

TpSvcChannelTypeCall, TpBaseCallContent and TpBaseCallStream