~ubuntu-branches/debian/squeeze/libnice/squeeze : revision 1

1

<?xml version="1.0"?>

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

3

"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

4

5

6

<refentrytitle role="top_of_page" id="libnice-NiceAgent.top_of_page">NiceAgent</refentrytitle>

7

8

<refmiscinfo>LIBNICE Library</refmiscinfo>

9

</refmeta>

10

11

12

<refname>NiceAgent</refname>

13

<refpurpose>ICE agent API implementation</refpurpose>

14

15

</refnamediv>

16

17

<title>Stability Level</title>

18

Stable, unless otherwise indicated

19

</refsect1>

20

21

22

<title role="synopsis.title">Synopsis</title>

23

24

25

26

#include <agent.h>

27

28

#define <link linkend="NICE-AGENT-MAX-REMOTE-CANDIDATES:CAPS">NICE_AGENT_MAX_REMOTE_CANDIDATES</link>

29

enum <link linkend="NiceComponentState">NiceComponentState</link>;

30

enum <link linkend="NiceComponentType">NiceComponentType</link>;

31

enum <link linkend="NiceCompatibility">NiceCompatibility</link>;

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

const <link linkend="gchar">gchar</link> *server_ip,

51

52

const <link linkend="gchar">gchar</link> *username,

53

const <link linkend="gchar">gchar</link> *password,

54

55

56

57

58

59

const <link linkend="gchar">gchar</link> *ufrag,

60

const <link linkend="gchar">gchar</link> *pwd);

61

62

63

64

65

66

67

68

const <link linkend="GSList">GSList</link> *candidates);

69

70

71

72

73

const <link linkend="gchar">gchar</link> *buf);

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

const <link linkend="gchar">gchar</link> *lfoundation,

91

const <link linkend="gchar">gchar</link> *rfoundation);

92

93

(<link linkend="NiceAgent">NiceAgent</link> *agent,

94

95

96

97

</synopsis>

98

</refsynopsisdiv>

99

100

101

102

103

104

105

106

<title role="properties.title">Properties</title>

107

108

"<link linkend="NiceAgent--compatibility">compatibility</link>" <link linkend="guint">guint</link> : Read / Write / Construct Only

109

"<link linkend="NiceAgent--controlling-mode">controlling-mode</link>" <link linkend="gboolean">gboolean</link> : Read / Write

110

"<link linkend="NiceAgent--full-mode">full-mode</link>" <link linkend="gboolean">gboolean</link> : Read / Write / Construct Only

111

"<link linkend="NiceAgent--main-context">main-context</link>" <link linkend="gpointer">gpointer</link> : Read / Write / Construct Only

112

"<link linkend="NiceAgent--max-connectivity-checks">max-connectivity-checks</link>" <link linkend="guint">guint</link> : Read / Write

113

"<link linkend="NiceAgent--proxy-ip">proxy-ip</link>" <link linkend="gchar">gchar</link>* : Read / Write

114

"<link linkend="NiceAgent--proxy-password">proxy-password</link>" <link linkend="gchar">gchar</link>* : Read / Write

115

"<link linkend="NiceAgent--proxy-port">proxy-port</link>" <link linkend="guint">guint</link> : Read / Write

116

"<link linkend="NiceAgent--proxy-type">proxy-type</link>" <link linkend="guint">guint</link> : Read / Write

117

"<link linkend="NiceAgent--proxy-username">proxy-username</link>" <link linkend="gchar">gchar</link>* : Read / Write

118

"<link linkend="NiceAgent--stun-pacing-timer">stun-pacing-timer</link>" <link linkend="guint">guint</link> : Read / Write / Construct Only

119

"<link linkend="NiceAgent--stun-server">stun-server</link>" <link linkend="gchar">gchar</link>* : Read / Write

120

"<link linkend="NiceAgent--stun-server-port">stun-server-port</link>" <link linkend="guint">guint</link> : Read / Write

121

</synopsis>

122

</refsect1>

123

124

125

<title role="signal_proto.title">Signals</title>

126

127

"<link linkend="NiceAgent-candidate-gathering-done">candidate-gathering-done</link>" : Run Last

128

"<link linkend="NiceAgent-component-state-changed">component-state-changed</link>" : Run Last

129

"<link linkend="NiceAgent-initial-binding-request-received">initial-binding-request-received</link>" : Run Last

130

"<link linkend="NiceAgent-new-candidate">new-candidate</link>" : Run Last

131

"<link linkend="NiceAgent-new-remote-candidate">new-remote-candidate</link>" : Run Last

132

"<link linkend="NiceAgent-new-selected-pair">new-selected-pair</link>" : Run Last

133

</synopsis>

134

</refsect1>

135

136

137

138

<title role="desc.title">Description</title>

139

<para>

140

The <link linkend="NiceAgent"><type>NiceAgent</type></link> is your main object when using libnice.

141

It is the agent that will take care of everything relating to ICE.

142

It will take care of discovering your local candidates and do

143

connectivity checks to create a stream of data between you and your peer.

144

</para>

145

<para>

146

147

<title>Simple example on how to use libnice</title>

148

149

NiceAddress base_addr;

150

guint stream_id;

151

gchar buffer[] = "hello world!";

152

GSList *lcands = NULL;

153

154

// Create a nice agent

155

NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_DRAFT19);

156

157

// Specify which local interface to use

158

nice_address_set_from_string (&base_addr, "127.0.0.1");

159

nice_agent_add_local_address (agent, &base_addr);

160

161

// Connect the signals

162

g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",

163

G_CALLBACK (cb_candidate_gathering_done), NULL);

164

g_signal_connect (G_OBJECT (lagent), "component-state-changed",

165

G_CALLBACK (cb_component_state_changed), NULL);

166

g_signal_connect (G_OBJECT (lagent), "new-selected-pair",

167

G_CALLBACK (cb_new_selected_pair), NULL);

168

169

// Create a new stream with one component and start gathering candidates

170

stream_id = nice_agent_add_stream (agent, 1);

171

nice_agent_gather_candidates (agent, stream_id);

172

173

// Attach to the component to receive the data

174

nice_agent_attach_recv (agent, stream_id, 1, NULL,

175

cb_nice_recv, NULL);

176

177

// ... Wait until the signal candidate-gathering-done is fired ...

178

lcands = nice_agent_get_local_candidates(agent, stream_id, 1);

179

180

// ... Send local candidates to the peer and set the peer's remote candidates

181

nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);

182

183

// ... Wait until the signal new-selected-pair is fired ...

184

// Send our message!

185

nice_agent_send (lagent, ls_id, 1, sizeof(buffer), buffer);

186

187

// Anything received will be received through the cb_nice_recv callback

188

189

// Destroy the object

190

g_object_unref(agent);

191

192

</programlisting>

193

</example></para>

194

<para>

195

196

</para>

197

</refsect1>

198

199

200

<title role="details.title">Details</title>

201

202

<title>NICE_AGENT_MAX_REMOTE_CANDIDATES</title>

203

<indexterm zone="NICE-AGENT-MAX-REMOTE-CANDIDATES:CAPS"><primary>NICE_AGENT_MAX_REMOTE_CANDIDATES</primary></indexterm><programlisting>#define NICE_AGENT_MAX_REMOTE_CANDIDATES 25

204

</programlisting>

205

<para>

206

A hard limit for number for remote candidates. This

207

limit is enforced to protect against malevolent remote

208

clients.</para>

209

<para>

210

211

</para></refsect2>

212

213

<title>enum NiceComponentState</title>

214

<indexterm zone="NiceComponentState"><primary>NiceComponentState</primary></indexterm><programlisting>typedef enum

215

{

216

NICE_COMPONENT_STATE_DISCONNECTED,

217

NICE_COMPONENT_STATE_GATHERING,

218

NICE_COMPONENT_STATE_CONNECTING,

219

NICE_COMPONENT_STATE_CONNECTED,

220

NICE_COMPONENT_STATE_READY,

221

NICE_COMPONENT_STATE_FAILED,

222

NICE_COMPONENT_STATE_LAST

223

} NiceComponentState;

224

</programlisting>

225

<para>

226

An enum representing the state of a component.

227

See <link linkend="NiceAgent-component-state-changed"><type>"component-state-changed"</type></link></para>

228

<para>

229

230

</para><variablelist role="enum">

231

232

<term><literal>NICE_COMPONENT_STATE_DISCONNECTED</literal></term>

233

<listitem><simpara> No activity scheduled

234

</simpara></listitem>

235

</varlistentry>

236

237

<term><literal>NICE_COMPONENT_STATE_GATHERING</literal></term>

238

<listitem><simpara> Gathering local candidates

239

</simpara></listitem>

240

</varlistentry>

241

242

<term><literal>NICE_COMPONENT_STATE_CONNECTING</literal></term>

243

<listitem><simpara> Establishing connectivity

244

</simpara></listitem>

245

</varlistentry>

246

247

<term><literal>NICE_COMPONENT_STATE_CONNECTED</literal></term>

248

<listitem><simpara> At least one working candidate pair

249

</simpara></listitem>

250

</varlistentry>

251

252

<term><literal>NICE_COMPONENT_STATE_READY</literal></term>

253

<listitem><simpara> ICE concluded, candidate pair selection

254

is now final

255

</simpara></listitem>

256

</varlistentry>

257

258

<term><literal>NICE_COMPONENT_STATE_FAILED</literal></term>

259

<listitem><simpara> Connectivity checks have been completed,

260

but connectivity was not established

261

</simpara></listitem>

262

</varlistentry>

263

264

<term><literal>NICE_COMPONENT_STATE_LAST</literal></term>

265

<listitem><simpara> Dummy state

266

</simpara></listitem>

267

</varlistentry>

268

</variablelist></refsect2>

269

270

<title>enum NiceComponentType</title>

271

<indexterm zone="NiceComponentType"><primary>NiceComponentType</primary></indexterm><programlisting>typedef enum

272

{

273

NICE_COMPONENT_TYPE_RTP = 1,

274

NICE_COMPONENT_TYPE_RTCP = 2

275

} NiceComponentType;

276

</programlisting>

277

<para>

278

Convenience enum representing the type of a component for use as the

279

component_id for RTP/RTCP usages.

280

281

<title>Example of use.</title>

282

283

nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);

284

</programlisting>

285

</example></para>

286

<para>

287

288

</para><variablelist role="enum">

289

290

<term><literal>NICE_COMPONENT_TYPE_RTP</literal></term>

291

<listitem><simpara> RTP Component type

292

</simpara></listitem>

293

</varlistentry>

294

295

<term><literal>NICE_COMPONENT_TYPE_RTCP</literal></term>

296

<listitem><simpara> RTCP Component type

297

</simpara></listitem>

298

</varlistentry>

299

</variablelist></refsect2>

300

301

<title>enum NiceCompatibility</title>

302

<indexterm zone="NiceCompatibility"><primary>NiceCompatibility</primary></indexterm><programlisting>typedef enum

303

{

304

NICE_COMPATIBILITY_DRAFT19 = 0,

305

NICE_COMPATIBILITY_GOOGLE,

306

NICE_COMPATIBILITY_MSN,

307

NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_MSN

308

} NiceCompatibility;

309

</programlisting>

310

<para>

311

An enum to specify which compatible specifications the <link linkend="NiceAgent"><type>NiceAgent</type></link> should use.

312

Use with <link linkend="nice-agent-new"><function>nice_agent_new()</function></link></para>

313

<para>

314

315

</para><variablelist role="enum">

316

317

<term><literal>NICE_COMPATIBILITY_DRAFT19</literal></term>

318

<listitem><simpara> Use compatibility for ICE Draft 19 specs

319

</simpara></listitem>

320

</varlistentry>

321

322

<term><literal>NICE_COMPATIBILITY_GOOGLE</literal></term>

323

<listitem><simpara> Use compatibility for Google Talk specs

324

</simpara></listitem>

325

</varlistentry>

326

327

<term><literal>NICE_COMPATIBILITY_MSN</literal></term>

328

<listitem><simpara> Use compatibility for MSN Messenger specs

329

</simpara></listitem>

330

</varlistentry>

331

332

<term><literal>NICE_COMPATIBILITY_LAST</literal></term>

333

<listitem><simpara> Dummy last compatibility mode

334

</simpara></listitem>

335

</varlistentry>

336

</variablelist></refsect2>

337

338

<title>NiceAgentRecvFunc ()</title>

339

<indexterm zone="NiceAgentRecvFunc"><primary>NiceAgentRecvFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*NiceAgentRecvFunc) (<link linkend="NiceAgent">NiceAgent</link> *agent,

340

341

342

343

344

345

<para>

346

Callback function when data is received on a component</para>

347

<para>

348

349

</para><variablelist role="params">

350

<varlistentry><term><parameter>agent</parameter> :</term>

351

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

352

</simpara></listitem></varlistentry>

353

<varlistentry><term><parameter>stream_id</parameter> :</term>

354

<listitem><simpara> The id of the stream

355

</simpara></listitem></varlistentry>

356

<varlistentry><term><parameter>component_id</parameter> :</term>

357

<listitem><simpara> The id of the component of the stream

358

which received the data

359

</simpara></listitem></varlistentry>

360

361

<listitem><simpara> The length of the data

362

</simpara></listitem></varlistentry>

363

364

<listitem><simpara> The buffer containing the data received

365

</simpara></listitem></varlistentry>

366

367

<listitem><simpara> The user data set in <link linkend="nice-agent-attach-recv"><function>nice_agent_attach_recv()</function></link>

368

</simpara></listitem></varlistentry>

369

</variablelist></refsect2>

370

371

<title>NiceAgent</title>

372

<indexterm zone="NiceAgent"><primary>NiceAgent</primary></indexterm><programlisting>typedef struct {

373

GObject parent; /**< gobject pointer */

374

375

gboolean full_mode; /**< property: full-mode */

376

GTimeVal next_check_tv; /**< property: next conncheck timestamp */

377

gchar *stun_server_ip; /**< property: STUN server IP */

378

guint stun_server_port; /**< property: STUN server port */

379

gchar *proxy_ip; /**< property: Proxy server IP */

380

guint proxy_port; /**< property: Proxy server port */

381

NiceProxyType proxy_type; /**< property: Proxy type */

382

gchar *proxy_username; /**< property: Proxy username */

383

gchar *proxy_password; /**< property: Proxy password */

384

gboolean controlling_mode; /**< property: controlling-mode */

385

guint timer_ta; /**< property: timer Ta */

386

guint max_conn_checks; /**< property: max connectivity checks */

387

388

GSList *local_addresses; /**< list of NiceAddresses for local

389

interfaces */

390

GSList *streams; /**< list of Stream objects */

391

GMainContext *main_context; /**< main context pointer */

392

guint next_candidate_id; /**< id of next created candidate */

393

guint next_stream_id; /**< id of next created candidate */

394

NiceRNG *rng; /**< random number generator */

395

GSList *discovery_list; /**< list of CandidateDiscovery items */

396

guint discovery_unsched_items; /**< number of discovery items unscheduled */

397

GSource *discovery_timer_source; /**< source of discovery timer */

398

GSource *conncheck_timer_source; /**< source of conncheck timer */

399

GSource *keepalive_timer_source; /**< source of keepalive timer */

400

GSList *refresh_list; /**< list of CandidateRefresh items */

401

guint64 tie_breaker; /**< tie breaker (ICE sect 5.2

402

"Determining Role" ID-19) */

403

GStaticRecMutex mutex; /* Mutex used for thread-safe lib */

404

NiceCompatibility compatibility; /* property: Compatibility mode */

405

StunAgent stun_agent; /* STUN agent */

406

/* XXX: add pointer to internal data struct for ABI-safe extensions */

407

} NiceAgent;

408

</programlisting>

409

<para>

410

The <link linkend="NiceAgent"><type>NiceAgent</type></link> is the main GObject of the libnice library and represents

411

the ICE agent.</para>

412

<para>

413

414

</para></refsect2>

415

416

<title>nice_agent_new ()</title>

417

<indexterm zone="nice-agent-new"><primary>nice_agent_new</primary></indexterm><programlisting><link linkend="NiceAgent">NiceAgent</link>* nice_agent_new (<link linkend="GMainContext">GMainContext</link> *ctx,

418

419

<para>

420

Create a new <link linkend="NiceAgent"><type>NiceAgent</type></link>.

421

The returned object must be freed with <link linkend="g-object-unref"><function>g_object_unref()</function></link></para>

422

<para>

423

424

</para><variablelist role="params">

425

426

<listitem><simpara> The Glib Mainloop Context to use for timers

427

</simpara></listitem></varlistentry>

428

<varlistentry><term><parameter>compat</parameter> :</term>

429

<listitem><simpara> The compatibility mode of the agent

430

</simpara></listitem></varlistentry>

431

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The new agent GObject

432

</simpara></listitem></varlistentry>

433

</variablelist></refsect2>

434

435

<title>nice_agent_add_local_address ()</title>

436

<indexterm zone="nice-agent-add-local-address"><primary>nice_agent_add_local_address</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_add_local_address (<link linkend="NiceAgent">NiceAgent</link> *agent,

437

438

<para>

439

Add a local address from which to derive local host candidates</para>

440

<para>

441

442

</para><variablelist role="params">

443

<varlistentry><term><parameter>agent</parameter> :</term>

444

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

445

</simpara></listitem></varlistentry>

446

447

<listitem><simpara> The address to listen to

448

If the port is 0, then a random port will be chosen by the system

449

</simpara></listitem></varlistentry>

450

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on fatal (memory allocation) errors

451

</simpara></listitem></varlistentry>

452

</variablelist></refsect2>

453

454

<title>nice_agent_add_stream ()</title>

455

<indexterm zone="nice-agent-add-stream"><primary>nice_agent_add_stream</primary></indexterm><programlisting><link linkend="guint">guint</link> nice_agent_add_stream (<link linkend="NiceAgent">NiceAgent</link> *agent,

456

457

<para>

458

Adds a data stream to <parameter>agent</parameter> containing <parameter>n_components</parameter> components.</para>

459

<para>

460

461

</para><variablelist role="params">

462

<varlistentry><term><parameter>agent</parameter> :</term>

463

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

464

</simpara></listitem></varlistentry>

465

<varlistentry><term><parameter>n_components</parameter> :</term>

466

<listitem><simpara> The number of components to add to the stream

467

</simpara></listitem></varlistentry>

468

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The ID of the new stream, 0 on failure

469

</simpara></listitem></varlistentry>

470

</variablelist></refsect2>

471

472

<title>nice_agent_remove_stream ()</title>

473

<indexterm zone="nice-agent-remove-stream"><primary>nice_agent_remove_stream</primary></indexterm><programlisting><link linkend="void">void</link> nice_agent_remove_stream (<link linkend="NiceAgent">NiceAgent</link> *agent,

474

475

<para>

476

Remove and free a previously created data stream from <parameter>agent</parameter></para>

477

<para>

478

479

</para><variablelist role="params">

480

<varlistentry><term><parameter>agent</parameter> :</term>

481

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

482

</simpara></listitem></varlistentry>

483

<varlistentry><term><parameter>stream_id</parameter> :</term>

484

<listitem><simpara> The ID of the stream to remove

485

</simpara></listitem></varlistentry>

486

</variablelist></refsect2>

487

488

<title>nice_agent_set_relay_info ()</title>

489

<indexterm zone="nice-agent-set-relay-info"><primary>nice_agent_set_relay_info</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_set_relay_info (<link linkend="NiceAgent">NiceAgent</link> *agent,

490

491

492

const <link linkend="gchar">gchar</link> *server_ip,

493

494

const <link linkend="gchar">gchar</link> *username,

495

const <link linkend="gchar">gchar</link> *password,

496

497

<para>

498

Sets the settings for using a relay server during the candidate discovery.</para>

499

<para>

500

501

</para><variablelist role="params">

502

<varlistentry><term><parameter>agent</parameter> :</term>

503

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

504

</simpara></listitem></varlistentry>

505

<varlistentry><term><parameter>stream_id</parameter> :</term>

506

<listitem><simpara> The ID of the stream

507

</simpara></listitem></varlistentry>

508

<varlistentry><term><parameter>component_id</parameter> :</term>

509

<listitem><simpara> The ID of the component

510

</simpara></listitem></varlistentry>

511

<varlistentry><term><parameter>server_ip</parameter> :</term>

512

<listitem><simpara> The IP address of the TURN server

513

</simpara></listitem></varlistentry>

514

<varlistentry><term><parameter>server_port</parameter> :</term>

515

<listitem><simpara> The port of the TURN server

516

</simpara></listitem></varlistentry>

517

<varlistentry><term><parameter>username</parameter> :</term>

518

<listitem><simpara> The TURN username to use for the allocate

519

</simpara></listitem></varlistentry>

520

<varlistentry><term><parameter>password</parameter> :</term>

521

<listitem><simpara> The TURN password to use for the allocate

522

</simpara></listitem></varlistentry>

523

524

<listitem><simpara> The type of relay to use

525

</simpara></listitem></varlistentry>

526

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the TURN settings were accepted.

527

528

</simpara></listitem></varlistentry>

529

</variablelist></refsect2>

530

531

<title>nice_agent_gather_candidates ()</title>

532

<indexterm zone="nice-agent-gather-candidates"><primary>nice_agent_gather_candidates</primary></indexterm><programlisting><link linkend="void">void</link> nice_agent_gather_candidates (<link linkend="NiceAgent">NiceAgent</link> *agent,

533

534

<para>

535

Start the candidate gathering process.

536

Once done, <link linkend="NiceAgent-candidate-gathering-done"><type>"candidate-gathering-done"</type></link> is called for the stream

537

</para>

538

<para>

539

<note>

540

<para>

541

Local addresses must be previously set with <link linkend="nice-agent-add-local-address"><function>nice_agent_add_local_address()</function></link>

542

</para>

543

</note></para>

544

<para>

545

546

</para><variablelist role="params">

547

<varlistentry><term><parameter>agent</parameter> :</term>

548

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

549

</simpara></listitem></varlistentry>

550

<varlistentry><term><parameter>stream_id</parameter> :</term>

551

<listitem><simpara> The id of the stream to start

552

</simpara></listitem></varlistentry>

553

</variablelist></refsect2>

554

555

<title>nice_agent_set_remote_credentials ()</title>

556

<indexterm zone="nice-agent-set-remote-credentials"><primary>nice_agent_set_remote_credentials</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_set_remote_credentials (<link linkend="NiceAgent">NiceAgent</link> *agent,

557

558

const <link linkend="gchar">gchar</link> *ufrag,

559

const <link linkend="gchar">gchar</link> *pwd);</programlisting>

560

<para>

561

Sets the remote credentials for stream <parameter>stream_id</parameter>.

562

</para>

563

<para>

564

<note>

565

<para>

566

Stream credentials do not override per-candidate credentials if set

567

</para>

568

</note></para>

569

<para>

570

571

</para><variablelist role="params">

572

<varlistentry><term><parameter>agent</parameter> :</term>

573

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

574

</simpara></listitem></varlistentry>

575

<varlistentry><term><parameter>stream_id</parameter> :</term>

576

<listitem><simpara> The ID of the stream

577

</simpara></listitem></varlistentry>

578

<varlistentry><term><parameter>ufrag</parameter> :</term>

579

<listitem><simpara> NULL-terminated string containing an ICE username fragment

580

(length must be between 22 and 256 chars)

581

</simpara></listitem></varlistentry>

582

583

<listitem><simpara> NULL-terminated string containing an ICE password

584

(length must be between 4 and 256 chars)

585

</simpara></listitem></varlistentry>

586

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on error.

587

</simpara></listitem></varlistentry>

588

</variablelist></refsect2>

589

590

<title>nice_agent_get_local_credentials ()</title>

591

<indexterm zone="nice-agent-get-local-credentials"><primary>nice_agent_get_local_credentials</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_get_local_credentials (<link linkend="NiceAgent">NiceAgent</link> *agent,

592

593

594

595

<para>

596

Gets the local credentials for stream <parameter>stream_id</parameter>.</para>

597

<para>

598

599

</para><variablelist role="params">

600

<varlistentry><term><parameter>agent</parameter> :</term>

601

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

602

</simpara></listitem></varlistentry>

603

<varlistentry><term><parameter>stream_id</parameter> :</term>

604

<listitem><simpara> The ID of the stream

605

</simpara></listitem></varlistentry>

606

<varlistentry><term><parameter>ufrag</parameter> :</term>

607

<listitem><simpara> a pointer to a NULL-terminated string containing

608

an ICE username fragment [OUT].

609

This string must be freed with <link linkend="g-free"><function>g_free()</function></link>

610

</simpara></listitem></varlistentry>

611

612

<listitem><simpara> a pointer to a NULL-terminated string containing an ICE

613

password [OUT]

614

This string must be freed with <link linkend="g-free"><function>g_free()</function></link>

615

</simpara></listitem></varlistentry>

616

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on error.

617

</simpara></listitem></varlistentry>

618

</variablelist></refsect2>

619

620

<title>nice_agent_set_remote_candidates ()</title>

621

<indexterm zone="nice-agent-set-remote-candidates"><primary>nice_agent_set_remote_candidates</primary></indexterm><programlisting><link linkend="int">int</link> nice_agent_set_remote_candidates (<link linkend="NiceAgent">NiceAgent</link> *agent,

622

623

624

const <link linkend="GSList">GSList</link> *candidates);</programlisting>

625

<para>

626

Sets, adds or updates the remote candidates for a component of a stream.

627

</para>

628

<para>

629

<note>

630

<para>

631

NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit

632

for remote candidates.

633

</para>

634

<para>

635

You must first call <link linkend="nice-agent-gather-candidates"><function>nice_agent_gather_candidates()</function></link> and wait for the

636

637

calling <link linkend="nice-agent-set-remote-candidates"><function>nice_agent_set_remote_candidates()</function></link>

638

</para>

639

</note></para>

640

<para>

641

642

</para><variablelist role="params">

643

<varlistentry><term><parameter>agent</parameter> :</term>

644

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

645

</simpara></listitem></varlistentry>

646

<varlistentry><term><parameter>stream_id</parameter> :</term>

647

<listitem><simpara> The ID of the stream the candidates are for

648

</simpara></listitem></varlistentry>

649

<varlistentry><term><parameter>component_id</parameter> :</term>

650

<listitem><simpara> The ID of the component the candidates are for

651

</simpara></listitem></varlistentry>

652

<varlistentry><term><parameter>candidates</parameter> :</term>

653

<listitem><simpara> a <link linkend="GList"><type>GList</type></link> of <link linkend="NiceCandidate"><type>NiceCandidate</type></link> items describing each candidate to add

654

</simpara></listitem></varlistentry>

655

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The number of candidates added, negative on errors (memory allocation

656

or if the local candidates are not done gathering yet)

657

</simpara></listitem></varlistentry>

658

</variablelist></refsect2>

659

660

<title>nice_agent_send ()</title>

661

<indexterm zone="nice-agent-send"><primary>nice_agent_send</primary></indexterm><programlisting><link linkend="gint">gint</link> nice_agent_send (<link linkend="NiceAgent">NiceAgent</link> *agent,

662

663

664

665

const <link linkend="gchar">gchar</link> *buf);</programlisting>

666

<para>

667

Sends a data payload over a stream's component.

668

</para>

669

<para>

670

<note>

671

<para>

672

Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case,

673

in any state if component was in READY state before and was then restarted

674

</para>

675

</note></para>

676

<para>

677

678

</para><variablelist role="params">

679

<varlistentry><term><parameter>agent</parameter> :</term>

680

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

681

</simpara></listitem></varlistentry>

682

<varlistentry><term><parameter>stream_id</parameter> :</term>

683

<listitem><simpara> The ID of the stream to send to

684

</simpara></listitem></varlistentry>

685

<varlistentry><term><parameter>component_id</parameter> :</term>

686

<listitem><simpara> The ID of the component to send to

687

</simpara></listitem></varlistentry>

688

689

<listitem><simpara> The length of the buffer to send

690

</simpara></listitem></varlistentry>

691

692

<listitem><simpara> The buffer of data to send

693

</simpara></listitem></varlistentry>

694

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The number of bytes sent, or negative error code

695

</simpara></listitem></varlistentry>

696

</variablelist></refsect2>

697

698

<title>nice_agent_get_local_candidates ()</title>

699

<indexterm zone="nice-agent-get-local-candidates"><primary>nice_agent_get_local_candidates</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* nice_agent_get_local_candidates (<link linkend="NiceAgent">NiceAgent</link> *agent,

700

701

702

<para>

703

Retreive from the agent the list of all local candidates

704

for a stream's component

705

</para>

706

<para>

707

<note>

708

<para>

709

The caller owns the returned GSList as well as the candidates contained

710

within it.

711

To get full results, the client should wait for the

712

713

</para>

714

</note></para>

715

<para>

716

717

</para><variablelist role="params">

718

<varlistentry><term><parameter>agent</parameter> :</term>

719

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

720

</simpara></listitem></varlistentry>

721

<varlistentry><term><parameter>stream_id</parameter> :</term>

722

<listitem><simpara> The ID of the stream

723

</simpara></listitem></varlistentry>

724

<varlistentry><term><parameter>component_id</parameter> :</term>

725

<listitem><simpara> The ID of the component

726

</simpara></listitem></varlistentry>

727

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GSList"><type>GSList</type></link> of <link linkend="NiceCandidate"><type>NiceCandidate</type></link> objects representing

728

the local candidates of <parameter>agent</parameter>

729

</simpara></listitem></varlistentry>

730

</variablelist></refsect2>

731

732

<title>nice_agent_get_remote_candidates ()</title>

733

<indexterm zone="nice-agent-get-remote-candidates"><primary>nice_agent_get_remote_candidates</primary></indexterm><programlisting><link linkend="GSList">GSList</link>* nice_agent_get_remote_candidates (<link linkend="NiceAgent">NiceAgent</link> *agent,

734

735

736

<para>

737

Get a list of the remote candidates set on a stream's component

738

</para>

739

<para>

740

<note>

741

<para>

742

The caller owns the returned GSList but not the candidates

743

contained within it.

744

</para>

745

<para>

746

The list of remote candidates can change during processing.

747

The client should register for the <link linkend="NiceAgent-new-remote-candidate"><type>"new-remote-candidate"</type></link> signal

748

to get notified of new remote candidates.

749

</para>

750

</note></para>

751

<para>

752

753

</para><variablelist role="params">

754

<varlistentry><term><parameter>agent</parameter> :</term>

755

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

756

</simpara></listitem></varlistentry>

757

<varlistentry><term><parameter>stream_id</parameter> :</term>

758

<listitem><simpara> The ID of the stream

759

</simpara></listitem></varlistentry>

760

<varlistentry><term><parameter>component_id</parameter> :</term>

761

<listitem><simpara> The ID of the component

762

</simpara></listitem></varlistentry>

763

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GSList"><type>GSList</type></link> of <link linkend="NiceCandidates"><type>NiceCandidates</type></link> objects representing

764

the remote candidates set on the <parameter>agent</parameter>

765

</simpara></listitem></varlistentry>

766

</variablelist></refsect2>

767

768

<title>nice_agent_restart ()</title>

769

<indexterm zone="nice-agent-restart"><primary>nice_agent_restart</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_restart (<link linkend="NiceAgent">NiceAgent</link> *agent);</programlisting>

770

<para>

771

Restarts the session as defined in ICE draft 19. This function

772

needs to be called both when initiating (ICE spec section 9.1.1.1.

773

"ICE Restarts"), as well as when reacting (spec section 9.2.1.1.

774

"Detecting ICE Restart") to a restart.</para>

775

<para>

776

777

</para><variablelist role="params">

778

<varlistentry><term><parameter>agent</parameter> :</term>

779

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

780

</simpara></listitem></varlistentry>

781

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on error

782

</simpara></listitem></varlistentry>

783

</variablelist></refsect2>

784

785

<title>nice_agent_attach_recv ()</title>

786

<indexterm zone="nice-agent-attach-recv"><primary>nice_agent_attach_recv</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_attach_recv (<link linkend="NiceAgent">NiceAgent</link> *agent,

787

788

789

790

791

792

<para>

793

Attaches the stream's component's sockets to the Glib Mainloop Context in

794

order to be notified whenever data becomes available for a component.</para>

795

<para>

796

797

</para><variablelist role="params">

798

<varlistentry><term><parameter>agent</parameter> :</term>

799

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

800

</simpara></listitem></varlistentry>

801

<varlistentry><term><parameter>stream_id</parameter> :</term>

802

<listitem><simpara> The ID of stream

803

</simpara></listitem></varlistentry>

804

<varlistentry><term><parameter>component_id</parameter> :</term>

805

<listitem><simpara> The ID of the component

806

</simpara></listitem></varlistentry>

807

808

<listitem><simpara> The Glib Mainloop Context to use for listening on the component

809

</simpara></listitem></varlistentry>

810

811

<listitem><simpara> The callback function to be called when data is received on

812

the stream's component

813

</simpara></listitem></varlistentry>

814

815

<listitem><simpara> user data associated with the callback

816

</simpara></listitem></varlistentry>

817

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the stream or component IDs are invalid.

818

</simpara></listitem></varlistentry>

819

</variablelist></refsect2>

820

821

<title>nice_agent_set_selected_pair ()</title>

822

<indexterm zone="nice-agent-set-selected-pair"><primary>nice_agent_set_selected_pair</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_set_selected_pair (<link linkend="NiceAgent">NiceAgent</link> *agent,

823

824

825

const <link linkend="gchar">gchar</link> *lfoundation,

826

const <link linkend="gchar">gchar</link> *rfoundation);</programlisting>

827

<para>

828

Sets the selected candidate pair for media transmission

829

for a given stream's component. Calling this function will

830

disable all further ICE processing (connection check,

831

state machine updates, etc). Note that keepalives will

832

continue to be sent.</para>

833

<para>

834

835

</para><variablelist role="params">

836

<varlistentry><term><parameter>agent</parameter> :</term>

837

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

838

</simpara></listitem></varlistentry>

839

<varlistentry><term><parameter>stream_id</parameter> :</term>

840

<listitem><simpara> The ID of the stream

841

</simpara></listitem></varlistentry>

842

<varlistentry><term><parameter>component_id</parameter> :</term>

843

<listitem><simpara> The ID of the component

844

</simpara></listitem></varlistentry>

845

<varlistentry><term><parameter>lfoundation</parameter> :</term>

846

<listitem><simpara> The local foundation of the candidate to use

847

</simpara></listitem></varlistentry>

848

<varlistentry><term><parameter>rfoundation</parameter> :</term>

849

<listitem><simpara> The remote foundation of the candidate to use

850

</simpara></listitem></varlistentry>

851

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the candidate pair cannot be found

852

</simpara></listitem></varlistentry>

853

</variablelist></refsect2>

854

855

<title>nice_agent_set_selected_remote_candidate ()</title>

856

<indexterm zone="nice-agent-set-selected-remote-candidate"><primary>nice_agent_set_selected_remote_candidate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> nice_agent_set_selected_remote_candidate

857

(<link linkend="NiceAgent">NiceAgent</link> *agent,

858

859

860

861

<para>

862

Sets the selected remote candidate for media transmission

863

for a given stream's component. This is used to force the selection of

864

a specific remote candidate even when connectivity checks are failing

865

(e.g. non-ICE compatible candidates).

866

Calling this function will disable all further ICE processing

867

(connection check, state machine updates, etc). Note that keepalives will

868

continue to be sent.</para>

869

<para>

870

871

</para><variablelist role="params">

872

<varlistentry><term><parameter>agent</parameter> :</term>

873

<listitem><simpara> The <link linkend="NiceAgent"><type>NiceAgent</type></link> Object

874

</simpara></listitem></varlistentry>

875

<varlistentry><term><parameter>stream_id</parameter> :</term>

876

<listitem><simpara> The ID of the stream

877

</simpara></listitem></varlistentry>

878

<varlistentry><term><parameter>component_id</parameter> :</term>

879

<listitem><simpara> The ID of the component

880

</simpara></listitem></varlistentry>

881

<varlistentry><term><parameter>candidate</parameter> :</term>

882

<listitem><simpara> The <link linkend="NiceCandidate"><type>NiceCandidate</type></link> to select

883

</simpara></listitem></varlistentry>

884

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on failure

885

</simpara></listitem></varlistentry>

886

</variablelist></refsect2>

887

888

</refsect1>

889

890

<title role="property_details.title">Property Details</title>

891

<refsect2 id="NiceAgent--compatibility"><title>The <literal>"compatibility"</literal> property</title>

892

<indexterm zone="NiceAgent--compatibility"><primary>NiceAgent:compatibility</primary></indexterm><programlisting> "compatibility" <link linkend="guint">guint</link> : Read / Write / Construct Only</programlisting>

893

<para>

894

The Nice agent can work in various compatibility modes depending on

895

what the application/peer needs.

896

<para> See also: <link linkend="NiceCompatibility"><type>NiceCompatibility</type></link></para></para>

897

<para>

898

899

</para><para>Allowed values: <= 2</para>

900

<para>Default value: 0</para>

901

</refsect2>

902

<refsect2 id="NiceAgent--controlling-mode"><title>The <literal>"controlling-mode"</literal> property</title>

903

<indexterm zone="NiceAgent--controlling-mode"><primary>NiceAgent:controlling-mode</primary></indexterm><programlisting> "controlling-mode" <link linkend="gboolean">gboolean</link> : Read / Write</programlisting>

904

<para>Whether the agent is in controlling mode.</para><para>Default value: FALSE</para>

905

</refsect2>

906

<refsect2 id="NiceAgent--full-mode"><title>The <literal>"full-mode"</literal> property</title>

907

<indexterm zone="NiceAgent--full-mode"><primary>NiceAgent:full-mode</primary></indexterm><programlisting> "full-mode" <link linkend="gboolean">gboolean</link> : Read / Write / Construct Only</programlisting>

908

<para>Whether agent runs in ICE full mode.</para><para>Default value: TRUE</para>

909

</refsect2>

910

<refsect2 id="NiceAgent--main-context"><title>The <literal>"main-context"</literal> property</title>

911

<indexterm zone="NiceAgent--main-context"><primary>NiceAgent:main-context</primary></indexterm><programlisting> "main-context" <link linkend="gpointer">gpointer</link> : Read / Write / Construct Only</programlisting>

912

<para>

913

A GLib main context is needed for all timeouts used by libnice.

914

This is a property being set by the <link linkend="nice-agent-new"><function>nice_agent_new()</function></link> call.</para>

915

<para>

916

917

</para></refsect2>

918

<refsect2 id="NiceAgent--max-connectivity-checks"><title>The <literal>"max-connectivity-checks"</literal> property</title>

919

<indexterm zone="NiceAgent--max-connectivity-checks"><primary>NiceAgent:max-connectivity-checks</primary></indexterm><programlisting> "max-connectivity-checks" <link linkend="guint">guint</link> : Read / Write</programlisting>

920

<para>Upper limit for the total number of connectivity checks performed.</para><para>Default value: 0</para>

921

</refsect2>

922

<refsect2 id="NiceAgent--proxy-ip"><title>The <literal>"proxy-ip"</literal> property</title>

923

<indexterm zone="NiceAgent--proxy-ip"><primary>NiceAgent:proxy-ip</primary></indexterm><programlisting> "proxy-ip" <link linkend="gchar">gchar</link>* : Read / Write</programlisting>

924

<para>The proxy server used to bypass a proxy firewall.</para><para>Default value: NULL</para>

925

</refsect2>

926

<refsect2 id="NiceAgent--proxy-password"><title>The <literal>"proxy-password"</literal> property</title>

927

<indexterm zone="NiceAgent--proxy-password"><primary>NiceAgent:proxy-password</primary></indexterm><programlisting> "proxy-password" <link linkend="gchar">gchar</link>* : Read / Write</programlisting>

928

<para>The password used to authenticate with the proxy.</para><para>Default value: NULL</para>

929

</refsect2>

930

<refsect2 id="NiceAgent--proxy-port"><title>The <literal>"proxy-port"</literal> property</title>

931

<indexterm zone="NiceAgent--proxy-port"><primary>NiceAgent:proxy-port</primary></indexterm><programlisting> "proxy-port" <link linkend="guint">guint</link> : Read / Write</programlisting>

932

<para>The Proxy server used to bypass a proxy firewall.</para><para>Allowed values: [1,65536]</para>

933

<para>Default value: 1</para>

934

</refsect2>

935

<refsect2 id="NiceAgent--proxy-type"><title>The <literal>"proxy-type"</literal> property</title>

936

<indexterm zone="NiceAgent--proxy-type"><primary>NiceAgent:proxy-type</primary></indexterm><programlisting> "proxy-type" <link linkend="guint">guint</link> : Read / Write</programlisting>

937

<para>The type of proxy set in the proxy-ip property.</para><para>Allowed values: <= 2</para>

938

<para>Default value: 0</para>

939

</refsect2>

940

<refsect2 id="NiceAgent--proxy-username"><title>The <literal>"proxy-username"</literal> property</title>

941

<indexterm zone="NiceAgent--proxy-username"><primary>NiceAgent:proxy-username</primary></indexterm><programlisting> "proxy-username" <link linkend="gchar">gchar</link>* : Read / Write</programlisting>

942

<para>The username used to authenticate with the proxy.</para><para>Default value: NULL</para>

943

</refsect2>

944

<refsect2 id="NiceAgent--stun-pacing-timer"><title>The <literal>"stun-pacing-timer"</literal> property</title>

945

<indexterm zone="NiceAgent--stun-pacing-timer"><primary>NiceAgent:stun-pacing-timer</primary></indexterm><programlisting> "stun-pacing-timer" <link linkend="guint">guint</link> : Read / Write / Construct Only</programlisting>

946

<para>Timer 'Ta' (msecs) used in the IETF ICE specification for pacing candidate gathering and sending of connectivity checks.</para><para>Allowed values: >= 1</para>

947

<para>Default value: 20</para>

948

</refsect2>

949

<refsect2 id="NiceAgent--stun-server"><title>The <literal>"stun-server"</literal> property</title>

950

<indexterm zone="NiceAgent--stun-server"><primary>NiceAgent:stun-server</primary></indexterm><programlisting> "stun-server" <link linkend="gchar">gchar</link>* : Read / Write</programlisting>

951

<para>The STUN server used to obtain server-reflexive candidates.</para><para>Default value: NULL</para>

952

</refsect2>

953

<refsect2 id="NiceAgent--stun-server-port"><title>The <literal>"stun-server-port"</literal> property</title>

954

<indexterm zone="NiceAgent--stun-server-port"><primary>NiceAgent:stun-server-port</primary></indexterm><programlisting> "stun-server-port" <link linkend="guint">guint</link> : Read / Write</programlisting>

955

<para>The STUN server used to obtain server-reflexive candidates.</para><para>Allowed values: [1,65536]</para>

956

<para>Default value: 1</para>

957

</refsect2>

958

959

</refsect1>

960

961

962

<title role="signals.title">Signal Details</title>

963

<refsect2 id="NiceAgent-candidate-gathering-done"><title>The <literal>"candidate-gathering-done"</literal> signal</title>

964

<indexterm zone="NiceAgent-candidate-gathering-done"><primary>NiceAgent::candidate-gathering-done</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

965

966

967

<para>

968

This signal is fired whenever a stream has finished gathering its

969

candidates after a call to <link linkend="nice-agent-gather-candidates"><function>nice_agent_gather_candidates()</function></link></para>

970

<para>

971

972

</para><variablelist role="params">

973

<varlistentry><term><parameter>stream_id</parameter> :</term>

974

<listitem><simpara> The ID of the stream

975

</simpara></listitem></varlistentry>

976

977

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

978

</variablelist></refsect2><refsect2 id="NiceAgent-component-state-changed"><title>The <literal>"component-state-changed"</literal> signal</title>

979

<indexterm zone="NiceAgent-component-state-changed"><primary>NiceAgent::component-state-changed</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

980

981

982

983

984

<para>

985

This signal is fired whenever a component's state changes</para>

986

<para>

987

988

</para><variablelist role="params">

989

<varlistentry><term><parameter>stream_id</parameter> :</term>

990

<listitem><simpara> The ID of the stream

991

</simpara></listitem></varlistentry>

992

<varlistentry><term><parameter>component_id</parameter> :</term>

993

<listitem><simpara> The ID of the component

994

</simpara></listitem></varlistentry>

995

<varlistentry><term><parameter>state</parameter> :</term>

996

<listitem><simpara> The <link linkend="NiceComponentState"><type>NiceComponentState</type></link> of the component

997

</simpara></listitem></varlistentry>

998

999

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

1000

</variablelist></refsect2><refsect2 id="NiceAgent-initial-binding-request-received"><title>The <literal>"initial-binding-request-received"</literal> signal</title>

1001

<indexterm zone="NiceAgent-initial-binding-request-received"><primary>NiceAgent::initial-binding-request-received</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

1002

1003

1004

<para>

1005

This signal is fired when we received our first binding request from

1006

the peer.</para>

1007

<para>

1008

1009

</para><variablelist role="params">

1010

<varlistentry><term><parameter>stream_id</parameter> :</term>

1011

<listitem><simpara> The ID of the stream

1012

</simpara></listitem></varlistentry>

1013

1014

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

1015

</variablelist></refsect2><refsect2 id="NiceAgent-new-candidate"><title>The <literal>"new-candidate"</literal> signal</title>

1016

<indexterm zone="NiceAgent-new-candidate"><primary>NiceAgent::new-candidate</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

1017

1018

1019

1020

1021

<para>

1022

This signal is fired when the agent discovers a new candidate

1023

<para> See also: <link linkend="NiceAgent-candidates-gathering-done"><type>"candidates-gathering-done"</type></link> </para></para>

1024

<para>

1025

1026

</para><variablelist role="params">

1027

<varlistentry><term><parameter>stream_id</parameter> :</term>

1028

<listitem><simpara> The ID of the stream

1029

</simpara></listitem></varlistentry>

1030

<varlistentry><term><parameter>component_id</parameter> :</term>

1031

<listitem><simpara> The ID of the component

1032

</simpara></listitem></varlistentry>

1033

<varlistentry><term><parameter>foundation</parameter> :</term>

1034

<listitem><simpara> The foundation of the new candidate

1035

</simpara></listitem></varlistentry>

1036

1037

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

1038

</variablelist></refsect2><refsect2 id="NiceAgent-new-remote-candidate"><title>The <literal>"new-remote-candidate"</literal> signal</title>

1039

<indexterm zone="NiceAgent-new-remote-candidate"><primary>NiceAgent::new-remote-candidate</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

1040

1041

1042

1043

1044

<para>

1045

This signal is fired when the agent discovers a new remote candidate.

1046

This can happen with peer reflexive candidates.

1047

<para> See also: <link linkend="NiceAgent-candidates-gathering-done"><type>"candidates-gathering-done"</type></link> </para></para>

1048

<para>

1049

1050

</para><variablelist role="params">

1051

<varlistentry><term><parameter>stream_id</parameter> :</term>

1052

<listitem><simpara> The ID of the stream

1053

</simpara></listitem></varlistentry>

1054

<varlistentry><term><parameter>component_id</parameter> :</term>

1055

<listitem><simpara> The ID of the component

1056

</simpara></listitem></varlistentry>

1057

<varlistentry><term><parameter>foundation</parameter> :</term>

1058

<listitem><simpara> The foundation of the new candidate

1059

</simpara></listitem></varlistentry>

1060

1061

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

1062

</variablelist></refsect2><refsect2 id="NiceAgent-new-selected-pair"><title>The <literal>"new-selected-pair"</literal> signal</title>

1063

<indexterm zone="NiceAgent-new-selected-pair"><primary>NiceAgent::new-selected-pair</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="NiceAgent">NiceAgent</link> *stream_id,

1064

1065

1066

1067

1068

1069

<para>

1070

This signal is fired once a candidate pair is selected for data transfer for

1071

a stream's component</para>

1072

<para>

1073

1074

</para><variablelist role="params">

1075

<varlistentry><term><parameter>stream_id</parameter> :</term>

1076

<listitem><simpara> The ID of the stream

1077

</simpara></listitem></varlistentry>

1078

<varlistentry><term><parameter>component_id</parameter> :</term>

1079

<listitem><simpara> The ID of the component

1080

</simpara></listitem></varlistentry>

1081

<varlistentry><term><parameter>lfoundation</parameter> :</term>

1082

<listitem><simpara> The local foundation of the selected candidate pair

1083

</simpara></listitem></varlistentry>

1084

<varlistentry><term><parameter>rfoundation</parameter> :</term>

1085

<listitem><simpara> The remote foundation of the selected candidate pair

1086

</simpara></listitem></varlistentry>

1087

1088

<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>

1089

</variablelist></refsect2>

1090

</refsect1>

1091

1092

1093

1094

1095

1096

</refsect1>

1097

1098

</refentry>