## FsCandidate

FsCandidate — Structure describing a transport candidate.

## Synopsis

    #include <farstream/fs-conference.h>

    struct              FsCandidate;
    enum                FsCandidateType;
    enum                FsNetworkProtocol;
    enum                FsComponentType;
    FsCandidate *       fs_candidate_new                    (const gchar *foundation,
                                                             guint component_id,
                                                             FsCandidateType type,
                                                             FsNetworkProtocol proto,
                                                             const gchar *ip,
                                                             guint port);
    FsCandidate *       fs_candidate_new_full               (const gchar *foundation,
                                                             guint component_id,
                                                             const gchar *ip,
                                                             guint16 port,
                                                             const gchar *base_ip,
                                                             guint16 base_port,
                                                             FsNetworkProtocol proto,
                                                             guint32 priority,
                                                             FsCandidateType type,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             guint ttl);
    void                fs_candidate_destroy                (FsCandidate *cand);
    FsCandidate *       fs_candidate_copy                   (const FsCandidate *cand);
    void                fs_candidate_list_destroy           (GList *candidate_list);
    GList *             fs_candidate_list_copy              (const GList *candidate_list);

## Description

An FsCandidate is a way to exchange candidate information between the client and Farstream. This description is compatible with ICE-13. It can also be a multicast address. Candidates are linked to streams. The information specified in this structure is usually representative of the codec information exchanged in the signaling.

## Details

### struct FsCandidate

    struct FsCandidate {
      gchar *foundation;
      guint component_id;
      gchar *ip;
      guint16 port;
      gchar *base_ip;
      guint16 base_port;
      FsNetworkProtocol proto;
      guint32 priority;
      FsCandidateType type;
      gchar *username;
      gchar *password;
      guint ttl;
    };

Struct to hold information about ICE-19 compliant candidates

gchar *`foundation`; | a string representing the foundation of this candidate (maximum 32 chars)
guint `component_id`; | value between 1 and 256 indicating which component this candidate represents (1 is RTP, 2 is RTCP, FsComponentType can be used here)
gchar *`ip`; | IP in dotted format
guint16 `port`; | Port to use
gchar *`base_ip`; | IP of base in dotted format as defined in ICE-19.
guint16 `base_port`; | Port of base as defined in ICE-19.
FsNetworkProtocol `proto`; | FsNetworkProtocol for ip protocol to use as candidate
guint32 `priority`; | Value between 0 and (2^31 - 1) representing the priority
FsCandidateType `type`; | The FsCandidateType of the candidate
gchar *`username`; | Username to use to connect to client if necessary, NULL otherwise
gchar *`password`; | Username to use to connect to client if necessary, NULL otherwise
guint `ttl`; | The TTL used when sending Multicast packet (0 = auto)

### enum FsCandidateType

    typedef enum {
      FS_CANDIDATE_TYPE_HOST,
      FS_CANDIDATE_TYPE_SRFLX,
      FS_CANDIDATE_TYPE_PRFLX,
      FS_CANDIDATE_TYPE_RELAY,    /* An external stream relay */
      FS_CANDIDATE_TYPE_MULTICAST
    } FsCandidateType;

An enum for the type of candidate used/reported

`FS_CANDIDATE_TYPE_HOST` | A host candidate (local)
`FS_CANDIDATE_TYPE_SRFLX` | A server reflexive candidate.
`FS_CANDIDATE_TYPE_PRFLX` | A peer reflexive candidate
`FS_CANDIDATE_TYPE_RELAY` | An relay candidate
`FS_CANDIDATE_TYPE_MULTICAST` | A multicast address

### enum FsNetworkProtocol

    typedef enum {
      FS_NETWORK_PROTOCOL_UDP,
      FS_NETWORK_PROTOCOL_TCP
    } FsNetworkProtocol;

An enum for the base IP protocol

`FS_NETWORK_PROTOCOL_UDP` | A UDP based protocol
`FS_NETWORK_PROTOCOL_TCP` | A TCP based protocol

### enum FsComponentType

    typedef enum {
      FS_COMPONENT_NONE = 0,
      FS_COMPONENT_RTP = 1,
      FS_COMPONENT_RTCP = 2
    } FsComponentType;

This enum contains the component IDs defined in ICE-19

`FS_COMPONENT_NONE` | Use this when specifying a component is innapropriate
`FS_COMPONENT_RTP` | This component is for RTP data
`FS_COMPONENT_RTCP` | This component is for RTCP control

### fs_candidate_new ()

    FsCandidate *       fs_candidate_new                    (const gchar *foundation,
                                                             guint component_id,
                                                             FsCandidateType type,
                                                             FsNetworkProtocol proto,
                                                             const gchar *ip,
                                                             guint port);

Allocates a new FsCandidate, the rest of the fields can be optionally filled manually. See also `fs_candidate_new_full()`

`foundation` : | The foundation of the candidate
`component_id` : | The component this candidate is for
`type` : | The type of candidate
`proto` : | The protocol this component is for
`ip` : | The IP address of this component (can be NULL for local candidate to mean any address)
`port` : | the UDP/TCP port
Returns : | a newly-allocated FsCandidate

### fs_candidate_new_full ()

    FsCandidate *       fs_candidate_new_full               (const gchar *foundation,
                                                             guint component_id,
                                                             const gchar *ip,
                                                             guint16 port,
                                                             const gchar *base_ip,
                                                             guint16 base_port,
                                                             FsNetworkProtocol proto,
                                                             guint32 priority,
                                                             FsCandidateType type,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             guint ttl);

Allocates a new FsCandidate, filling all the fields. See also `fs_candidate_new()`

`foundation` : | The foundation of the candidate
`component_id` : | The component this candidate is for
`ip` : | The IP address of this component (can be NULL for local candidate to mean any address)
`port` : | the UDP/TCP port
`base_ip` : | IP of base in dotted format as defined in ICE-19.
`base_port` : | Port of base as defined in ICE-19.
`proto` : | The protocol this component is for
`priority` : | Value between 0 and (2^31 - 1) representing the priority
`type` : | The type of candidate
`username` : | Username to use to connect to client if necessary, NULL otherwise
`password` : | Username to use to connect to client if necessary, NULL otherwise
`ttl` : | The TTL used when sending Multicast packet (0 = auto)
Returns : | a newly-allocated FsCandidate

### fs_candidate_destroy ()

    void                fs_candidate_destroy                (FsCandidate *cand);

Frees a FsCandidate and all its contents

`cand` : | a FsCandidate to delete

### fs_candidate_copy ()

    FsCandidate *       fs_candidate_copy                   (const FsCandidate *cand);

Copies a FsCandidate and its contents.

`cand` : | a FsCandidate to copy
Returns : | a new FsCandidate

### fs_candidate_list_destroy ()

    void                fs_candidate_list_destroy           (GList *candidate_list);

Deletes a GList of FsCandidate and its contents

`candidate_list` : | A GList of FsCandidate

### fs_candidate_list_copy ()

    GList *             fs_candidate_list_copy              (const GList *candidate_list);

Copies a GList of FsCandidate and its contents

`candidate_list` : | A GList of FsCandidate. [element-type FsCodec]
Returns : | a new GList of FsCandidate. [element-type FsCodec][transfer full]