## TpBaseMediaCallStream

TpBaseMediaCallStream — base class for TpSvcCallStreamInterfaceMedia implementations

## Synopsis

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

                        TpBaseMediaCallStream;
    struct              TpBaseMediaCallStreamClass;
    gboolean            (*TpBaseMediaCallStreamFinishInitialCandidatesFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             GError **error);
    GPtrArray *         (*TpBaseMediaCallStreamAddCandidatesFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             const GPtrArray *candidates,
                                                             GError **error);
    void                (*TpBaseMediaCallStreamReportFailureFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             TpStreamFlowState old_state,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);
    void                (*TpBaseMediaCallStreamRequestReceivingFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             TpHandle contact,
                                                             gboolean receive);
    gboolean            (*TpBaseMediaCallStreamSetSendingFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             gboolean sending,
                                                             GError **error);
    void                tp_base_media_call_stream_set_relay_info
                                                            (TpBaseMediaCallStream *self,
                                                             GPtrArray *relays);
    void                tp_base_media_call_stream_set_stun_servers
                                                            (TpBaseMediaCallStream *self,
                                                             GPtrArray *stun_servers);
    void                tp_base_media_call_stream_add_endpoint
                                                            (TpBaseMediaCallStream *self,
                                                             TpCallStreamEndpoint *endpoint);
    void                tp_base_media_call_stream_remove_endpoint
                                                            (TpBaseMediaCallStream *self,
                                                             TpCallStreamEndpoint *endpoint);
    GList *             tp_base_media_call_stream_get_endpoints
                                                            (TpBaseMediaCallStream *self);
    const gchar *       tp_base_media_call_stream_get_username
                                                            (TpBaseMediaCallStream *self);
    const gchar *       tp_base_media_call_stream_get_password
                                                            (TpBaseMediaCallStream *self);
    void                tp_base_media_call_stream_update_receiving_state
                                                            (TpBaseMediaCallStream *self);
    TpStreamFlowState   tp_base_media_call_stream_get_receiving_state
                                                            (TpBaseMediaCallStream *self);
    void                tp_base_media_call_stream_update_sending_state
                                                            (TpBaseMediaCallStream *self);
    TpStreamFlowState   tp_base_media_call_stream_get_sending_state
                                                            (TpBaseMediaCallStream *self);
    void                tp_base_media_call_stream_set_local_sending
                                                            (TpBaseMediaCallStream *self,
                                                             gboolean sending);
    gboolean            tp_base_media_call_stream_get_local_sending
                                                            (TpBaseMediaCallStream *self);
    GPtrArray *         tp_base_media_call_stream_get_local_candidates
                                                            (TpBaseMediaCallStream *self);

## Object Hierarchy

      GObject
       +----TpBaseCallStream
             +----TpBaseMediaCallStream

## Implemented Interfaces

TpBaseMediaCallStream implements TpSvcDBusProperties, TpSvcCallStream and TpSvcCallStreamInterfaceMedia.

## Properties

      "endpoints"                GPtrArray_DBusGObjectPath_*  : Read
      "has-server-info"          gboolean              : Read
      "ice-restart-pending"      gboolean              : Read
      "local-candidates"         GPtrArray_GValueArray_guint+gchararray+guint+GHashTable_gchararray+GValue___*  : Read
      "local-credentials"        GValueArray_gchararray+gchararray_*  : Read
      "receiving-state"          guint                 : Read
      "relay-info"               GPtrArray_GHashTable_gchararray+GValue__*  : Read
      "sending-state"            guint                 : Read
      "stun-servers"             GPtrArray_GValueArray_gchararray+guint__*  : Read
      "transport"                guint                 : Read / Write / Construct Only

## Description

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

Subclasses must still implement TpBaseCallStream's virtual methods plus TpBaseMediaCallStreamClass.add_local_candidates and TpBaseMediaCallStreamClass.finish_initial_candidates.

## Details

### TpBaseMediaCallStream

    typedef struct _TpBaseMediaCallStream TpBaseMediaCallStream;

A base class for media call stream implementations

Since 0.17.5

### struct TpBaseMediaCallStreamClass

    struct TpBaseMediaCallStreamClass {
      TpBaseMediaCallStreamReportFailureFunc report_sending_failure;
      TpBaseMediaCallStreamReportFailureFunc report_receiving_failure;
      TpBaseMediaCallStreamAddCandidatesFunc add_local_candidates;
      TpBaseMediaCallStreamFinishInitialCandidatesFunc finish_initial_candidates;

      TpBaseMediaCallStreamRequestReceivingFunc request_receiving;
      TpBaseMediaCallStreamSetSendingFunc set_sending;
    };

The class structure for TpBaseMediaCallStream

TpBaseMediaCallStreamReportFailureFunc `report_sending_failure`; | optional; called to indicate a failure in the outgoing portion of the stream
TpBaseMediaCallStreamReportFailureFunc `report_receiving_failure`; | optional; called to indicate a failure in the incoming portion of the stream
TpBaseMediaCallStreamAddCandidatesFunc `add_local_candidates`; | mandatory; called when new candidates are added
TpBaseMediaCallStreamFinishInitialCandidatesFunc `finish_initial_candidates`; | optional; called when the initial batch of candidates has been added, and should now be processed/sent to the remote side
TpBaseMediaCallStreamRequestReceivingFunc `request_receiving`; | optional (see "can-request-receiving"); virtual method called when user requested receiving from the given remote contact. This virtual method should be implemented instead of TpBaseCallStream.request_receiving
TpBaseMediaCallStreamSetSendingFunc `set_sending`; | mandatory; virtual method called when user requested to start/stop sending to remote contacts. This virtual method should be implemented instead of TpBaseCallStream.set_sending

Since 0.17.5

### TpBaseMediaCallStreamFinishInitialCandidatesFunc ()

    gboolean            (*TpBaseMediaCallStreamFinishInitialCandidatesFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             GError **error);

Signature of an implementation of TpBaseMediaCallStreamClass.finish_initial_candidates.

`self` : | a TpBaseMediaCallStream
`error` : | a GError to fill

Since 0.17.5

### TpBaseMediaCallStreamAddCandidatesFunc ()

    GPtrArray *         (*TpBaseMediaCallStreamAddCandidatesFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             const GPtrArray *candidates,
                                                             GError **error);

Signature of an implementation of TpBaseMediaCallStreamClass.add_local_candidates.

Implementation should validate the added `candidates` and return a subset (or all) of them that are accepted. Implementation should return a new GPtrArray build in a way that `g_ptr_array_unref()` is enough to free all its memory. It is fine to just add element pointers from `candidates` to the returned GPtrArray without deep-copy them.

`self` : | a TpBaseMediaCallStream
`candidates` : | a GPtrArray of GValueArray containing candidates info
`error` : | a GError to fill

Since 0.17.5

### TpBaseMediaCallStreamReportFailureFunc ()

    void                (*TpBaseMediaCallStreamReportFailureFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             TpStreamFlowState old_state,
                                                             TpCallStateChangeReason reason,
                                                             const gchar *dbus_reason,
                                                             const gchar *message);

Signature of an implementation of TpBaseMediaCallStreamClass.report_sending_failure and TpBaseMediaCallStreamClass.report_receiving_failure.

`self` : | a TpBaseMediaCallStream
`old_state` : | the previous TpStreamFlowState
`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

### TpBaseMediaCallStreamRequestReceivingFunc ()

    void                (*TpBaseMediaCallStreamRequestReceivingFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             TpHandle contact,
                                                             gboolean receive);

Signature of an implementation of TpBaseMediaCallStreamClass.request_receiving.

`self` : | a TpBaseMediaCallStream
`contact` : | the contact from who user wants to start or stop receiving
`receive` : | wheter or not user would like to be receiving

Since 0.17.5

### TpBaseMediaCallStreamSetSendingFunc ()

    gboolean            (*TpBaseMediaCallStreamSetSendingFunc)
                                                            (TpBaseMediaCallStream *self,
                                                             gboolean sending,
                                                             GError **error);

Signature of an implementation of TpBaseMediaCallStreamClass.set_sending.

`self` : | a TpBaseMediaCallStream
`sending` : | whether or not user would like to be sending
`error` : | a GError to fill
Returns : | `TRUE` on success, `FALSE` otherwise.

Since 0.17.5

### tp_base_media_call_stream_set_relay_info ()

    void                tp_base_media_call_stream_set_relay_info
                                                            (TpBaseMediaCallStream *self,
                                                             GPtrArray *relays);

Set the relays info. The GPtrArray should have a free_func defined such as `g_ptr_array_ref()` is enough to keep the data and `g_ptr_array_unref()` is enough to release it later.

Note that this replaces the previously set relays, it is not an addition.

`self` : | a TpBaseMediaCallStream
`relays` : | the new relays info

Since 0.17.5

### tp_base_media_call_stream_set_stun_servers ()

    void                tp_base_media_call_stream_set_stun_servers
                                                            (TpBaseMediaCallStream *self,
                                                             GPtrArray *stun_servers);

Set the STUN servers. The GPtrArray should have a free_func defined such as `g_ptr_array_ref()` is enough to keep the data and `g_ptr_array_unref()` is enough to release it later.

Note that this replaces the previously set STUN servers, it is not an addition.

`self` : | a TpBaseMediaCallStream
`stun_servers` : | the new stun servers

Since 0.17.5

### tp_base_media_call_stream_add_endpoint ()

    void                tp_base_media_call_stream_add_endpoint
                                                            (TpBaseMediaCallStream *self,
                                                             TpCallStreamEndpoint *endpoint);

Add `endpoint` to "endpoints" list, and emits EndpointsChanged DBus signal.

`self` : | a TpBaseMediaCallStream
`endpoint` : | a TpCallStreamEndpoint

Since 0.17.5

### tp_base_media_call_stream_remove_endpoint ()

    void                tp_base_media_call_stream_remove_endpoint
                                                            (TpBaseMediaCallStream *self,
                                                             TpCallStreamEndpoint *endpoint);

Remove `endpoint` from "endpoints" list, and emits EndpointsChanged DBus signal.

`self` : | a TpBaseMediaCallStream
`endpoint` : | a TpCallStreamEndpoint

Since 0.17.5

### tp_base_media_call_stream_get_endpoints ()

    GList *             tp_base_media_call_stream_get_endpoints
                                                            (TpBaseMediaCallStream *self);

Same as "endpoints" but as a GList of TpCallStreamEndpoint.

`self` : | a TpBaseMediaCallStream
Returns : | Borrowed GList of TpCallStreamEndpoint.

Since 0.17.5

### tp_base_media_call_stream_get_username ()

    const gchar *       tp_base_media_call_stream_get_username
                                                            (TpBaseMediaCallStream *self);

`self` : | a TpBaseMediaCallStream
Returns : | the username part of "local-credentials"

Since 0.17.5

### tp_base_media_call_stream_get_password ()

    const gchar *       tp_base_media_call_stream_get_password
                                                            (TpBaseMediaCallStream *self);

`self` : | a TpBaseMediaCallStream
Returns : | the password part of "local-credentials"

Since 0.17.5

### tp_base_media_call_stream_update_receiving_state ()

    void                tp_base_media_call_stream_update_receiving_state
                                                            (TpBaseMediaCallStream *self);

Update the receiving state.

`self` : | a TpBaseMediaCallStream

Since 0.17.5

### tp_base_media_call_stream_get_receiving_state ()

    TpStreamFlowState   tp_base_media_call_stream_get_receiving_state
                                                            (TpBaseMediaCallStream *self);

`self` : | a TpBaseMediaCallStream
Returns : | the value of "receiving-state".

Since 0.17.5

### tp_base_media_call_stream_update_sending_state ()

    void                tp_base_media_call_stream_update_sending_state
                                                            (TpBaseMediaCallStream *self);

Update the sending state.

`self` : | a TpBaseMediaCallStream

Since 0.17.5

### tp_base_media_call_stream_get_sending_state ()

    TpStreamFlowState   tp_base_media_call_stream_get_sending_state
                                                            (TpBaseMediaCallStream *self);

`self` : | a TpBaseMediaCallStream
Returns : | the value of "sending-state".

Since 0.17.5

### tp_base_media_call_stream_set_local_sending ()

    void                tp_base_media_call_stream_set_local_sending
                                                            (TpBaseMediaCallStream *self,
                                                             gboolean sending);

Set local sending state.

`self` : | a TpBaseMediaCallStream
`sending` : | whether or not we are sending

Since 0.17.5

### tp_base_media_call_stream_get_local_sending ()

    gboolean            tp_base_media_call_stream_get_local_sending
                                                            (TpBaseMediaCallStream *self);

Gets the local sending state

`self` : | a TpBaseMediaCallStream
Returns : | The local sending state

Since 0.17.7

### tp_base_media_call_stream_get_local_candidates ()

    GPtrArray *         tp_base_media_call_stream_get_local_candidates
                                                            (TpBaseMediaCallStream *self);

`self` : | a TpBaseMediaCallStream
Returns : | the value of "local-candidates" as a GtrArray

Since 0.17.5

## Property Details

### The `"endpoints"` property

      "endpoints"                GPtrArray_DBusGObjectPath_*  : Read

GPtrArray{object-path string} The endpoints of this content.

Since 0.17.5

### The `"has-server-info"` property

      "has-server-info"          gboolean              : Read

`TRUE` if "relay-info" and "stun-servers" have been set.

Default value: FALSE

Since 0.17.5

### The `"ice-restart-pending"` property

      "ice-restart-pending"      gboolean              : Read

`TRUE` when ICERestartRequested signal is emitted, and `FALSE` when SetCredentials is called. Useful for debugging.

Default value: FALSE

Since 0.17.5

### The `"local-candidates"` property

      "local-candidates"         GPtrArray_GValueArray_guint+gchararray+guint+GHashTable_gchararray+GValue___*  : Read

GPtrArray{candidate GValueArray} List of local candidates.

Since 0.17.5

### The `"local-credentials"` property

      "local-credentials"        GValueArray_gchararray+gchararray_*  : Read

GValueArray{username string, password string} ufrag and pwd as defined by ICE.

Since 0.17.5

### The `"receiving-state"` property

      "receiving-state"          guint                 : Read

The receiving TpStreamFlowState.

Default value: 0

Since 0.17.5

### The `"relay-info"` property

      "relay-info"               GPtrArray_GHashTable_gchararray+GValue__*  : Read

GPtrArray{relay-info asv} List of relay information.

Since 0.17.5

### The `"sending-state"` property

      "sending-state"            guint                 : Read

The sending TpStreamFlowState.

Default value: 0

Since 0.17.5

### The `"stun-servers"` property

      "stun-servers"             GPtrArray_GValueArray_gchararray+guint__*  : Read

GPtrArray{stun-server GValueArray} List of STUN servers.

Since 0.17.5

### The `"transport"` property

      "transport"                guint                 : Read / Write / Construct Only

The TpStreamTransportType of this stream.

Default value: 0

Since 0.17.5

## See Also

TpSvcCallStreamInterfaceMedia, TpBaseCallChannel, TpBaseCallStream and TpBaseCallContent