← Back to branch summary

~ubuntu-branches/debian/jessie/libnice/jessie

« back to all changes in this revision

Viewing changes to docs/reference/libnice/xml/timer.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sjoerd Simons
  • Date: 2010-05-20 14:38:50 UTC
  • mfrom: (1.2.4 upstream) (5.1.6 sid)
  • Revision ID: james.westby@ubuntu.com-20100520143850-413jycrqvl22ukg5
Tags: 0.0.12-1
New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/libnice/xml/timer.xml
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
 
<refentry id="libnice-Timer">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="libnice-Timer.top_of_page">Timer</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>LIBNICE Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>Timer</refname>
13
 
<refpurpose>STUN timer Usage</refpurpose>
14
 
</refnamediv>
15
 
<refsect1 id="libnice-Timer.stability-level">
16
 
<title>Stability Level</title>
17
 
Stable, unless otherwise indicated
18
 
</refsect1>
19
 
 
20
 
<refsynopsisdiv id="libnice-Timer.synopsis" role="synopsis">
21
 
<title role="synopsis.title">Synopsis</title>
22
 
 
23
 
<synopsis>
24
 
 
25
 
#include &lt;stun/usages/timer.h&gt;
26
 
 
27
 
typedef             <link linkend="StunTimer">StunTimer</link>;
28
 
enum                <link linkend="StunUsageTimerReturn">StunUsageTimerReturn</link>;
29
 
<link linkend="void">void</link>                <link linkend="stun-timer-start">stun_timer_start</link>                    (<link linkend="StunTimer">StunTimer</link> *timer);
30
 
<link linkend="void">void</link>                <link linkend="stun-timer-start-reliable">stun_timer_start_reliable</link>           (<link linkend="StunTimer">StunTimer</link> *timer);
31
 
<link linkend="StunUsageTimerReturn">StunUsageTimerReturn</link>  <link linkend="stun-timer-refresh">stun_timer_refresh</link>                (<link linkend="StunTimer">StunTimer</link> *timer);
32
 
<link linkend="unsigned">unsigned</link>            <link linkend="stun-timer-remainder">stun_timer_remainder</link>                (const <link linkend="StunTimer">StunTimer</link> *timer);
33
 
</synopsis>
34
 
</refsynopsisdiv>
35
 
 
36
 
 
37
 
 
38
 
 
39
 
 
40
 
 
41
 
 
42
 
 
43
 
 
44
 
<refsect1 id="libnice-Timer.description" role="desc">
45
 
<title role="desc.title">Description</title>
46
 
<para>
47
 
The STUN timer usage is a set of helpful utility functions that allows you
48
 
to easily track when a STUN message should be retransmitted or considered
49
 
as timed out.
50
 
</para>
51
 
<para>
52
 
 <example>
53
 
   <title>Simple example on how to use the timer usage</title>
54
 
   <programlisting>
55
 
   StunTimer timer;
56
 
   unsigned remainder;
57
 
   StunUsageTimerReturn ret;
58
 
 
59
 
   // Build the message, etc..
60
 
   ...
61
 
 
62
 
   // Send the message and start the timer
63
 
   send(socket, request, sizeof(request));
64
 
   stun_timer_start(&amp;timer);
65
 
 
66
 
   // Loop until we get the response
67
 
   for (;;) {
68
 
     remainder = stun_timer_remainder(&amp;timer);
69
 
 
70
 
     // Poll the socket until data is received or the timer expires
71
 
     if (poll (&amp;pollfd, 1, delay) &lt;= 0) {
72
 
       // Time out and no response was received
73
 
       ret = stun_timer_refresh (&amp;timer);
74
 
       if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
75
 
         // Transaction timed out
76
 
         break;
77
 
       } else if (ret == STUN_USAGE_TIMER_RETURN_RETRANSMIT) {
78
 
         // A retransmission is necessary
79
 
         send(socket, request, sizeof(request));
80
 
         continue;
81
 
       } else if (ret == STUN_USAGE_TIMER_RETURN_SUCCESS) {
82
 
         // The refresh succeeded and nothing has to be done, continue polling
83
 
         continue;
84
 
       }
85
 
     } else {
86
 
       // We received a response, read it
87
 
       recv(socket, response, sizeof(response));
88
 
       break;
89
 
     }
90
 
   }
91
 
 
92
 
   // Check if the transaction timed out or not
93
 
   if (ret == STUN_USAGE_TIMER_RETURN_TIMEOUT) {
94
 
     // do whatever needs to be done in that case
95
 
   } else {
96
 
     // Parse the response
97
 
   }
98
 
 
99
 
   </programlisting>
100
 
 </example></para>
101
 
<para>
102
 
</para>
103
 
</refsect1>
104
 
 
105
 
<refsect1 id="libnice-Timer.details" role="details">
106
 
<title role="details.title">Details</title>
107
 
<refsect2 id="StunTimer" role="typedef">
108
 
<title>StunTimer</title>
109
 
<indexterm zone="StunTimer"><primary sortas="StunTimer">StunTimer</primary></indexterm><programlisting>typedef struct stun_timer_s StunTimer;
110
 
</programlisting>
111
 
<para>
112
 
An opaque structure representing a STUN transaction retransmission timer</para>
113
 
<para>
114
 
</para></refsect2>
115
 
<refsect2 id="StunUsageTimerReturn" role="enum">
116
 
<title>enum StunUsageTimerReturn</title>
117
 
<indexterm zone="StunUsageTimerReturn"><primary sortas="StunUsageTimerReturn">StunUsageTimerReturn</primary></indexterm><programlisting>typedef enum {
118
 
  STUN_USAGE_TIMER_RETURN_SUCCESS,
119
 
  STUN_USAGE_TIMER_RETURN_RETRANSMIT,
120
 
  STUN_USAGE_TIMER_RETURN_TIMEOUT
121
 
} StunUsageTimerReturn;
122
 
</programlisting>
123
 
<para>
124
 
Return value of <link linkend="stun-usage-timer-refresh"><function>stun_usage_timer_refresh()</function></link> which provides you with status
125
 
information on the timer.</para>
126
 
<para>
127
 
</para><variablelist role="enum">
128
 
<varlistentry id="STUN-USAGE-TIMER-RETURN-SUCCESS--CAPS" role="constant">
129
 
<term><literal>STUN_USAGE_TIMER_RETURN_SUCCESS</literal></term>
130
 
<listitem><simpara> The timer was refreshed successfully
131
 
and there is nothing to be done
132
 
</simpara></listitem>
133
 
</varlistentry>
134
 
<varlistentry id="STUN-USAGE-TIMER-RETURN-RETRANSMIT--CAPS" role="constant">
135
 
<term><literal>STUN_USAGE_TIMER_RETURN_RETRANSMIT</literal></term>
136
 
<listitem><simpara> The timer expired and the message
137
 
should be retransmitted now.
138
 
</simpara></listitem>
139
 
</varlistentry>
140
 
<varlistentry id="STUN-USAGE-TIMER-RETURN-TIMEOUT--CAPS" role="constant">
141
 
<term><literal>STUN_USAGE_TIMER_RETURN_TIMEOUT</literal></term>
142
 
<listitem><simpara> The timer expired as well as all the
143
 
retransmissions, the transaction timed out
144
 
</simpara></listitem>
145
 
</varlistentry>
146
 
</variablelist></refsect2>
147
 
<refsect2 id="stun-timer-start" role="function">
148
 
<title>stun_timer_start ()</title>
149
 
<indexterm zone="stun-timer-start"><primary sortas="stun_timer_start">stun_timer_start</primary></indexterm><programlisting><link linkend="void">void</link>                stun_timer_start                    (<link linkend="StunTimer">StunTimer</link> *timer);</programlisting>
150
 
<para>
151
 
Starts a STUN transaction retransmission timer.
152
 
This should be called as soon as you send the message for the first time on
153
 
a UDP socket</para>
154
 
<para>
155
 
</para><variablelist role="params">
156
 
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
157
 
<listitem><simpara> The <link linkend="StunTimer"><type>StunTimer</type></link> to start
158
 
</simpara></listitem></varlistentry>
159
 
</variablelist></refsect2>
160
 
<refsect2 id="stun-timer-start-reliable" role="function">
161
 
<title>stun_timer_start_reliable ()</title>
162
 
<indexterm zone="stun-timer-start-reliable"><primary sortas="stun_timer_start_reliable">stun_timer_start_reliable</primary></indexterm><programlisting><link linkend="void">void</link>                stun_timer_start_reliable           (<link linkend="StunTimer">StunTimer</link> *timer);</programlisting>
163
 
<para>
164
 
Starts a STUN transaction retransmission timer for a reliable transport.
165
 
This should be called as soon as you send the message for the first time on
166
 
a TCP socket</para>
167
 
<para>
168
 
</para><variablelist role="params">
169
 
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
170
 
<listitem><simpara> The <link linkend="StunTimer"><type>StunTimer</type></link> to start
171
 
</simpara></listitem></varlistentry>
172
 
</variablelist></refsect2>
173
 
<refsect2 id="stun-timer-refresh" role="function">
174
 
<title>stun_timer_refresh ()</title>
175
 
<indexterm zone="stun-timer-refresh"><primary sortas="stun_timer_refresh">stun_timer_refresh</primary></indexterm><programlisting><link linkend="StunUsageTimerReturn">StunUsageTimerReturn</link>  stun_timer_refresh                (<link linkend="StunTimer">StunTimer</link> *timer);</programlisting>
176
 
<para>
177
 
Updates a STUN transaction retransmission timer.</para>
178
 
<para>
179
 
</para><variablelist role="params">
180
 
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
181
 
<listitem><simpara> The <link linkend="StunTimer"><type>StunTimer</type></link> to refresh
182
 
</simpara></listitem></varlistentry>
183
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A <link linkend="StunUsageTimerReturn"><type>StunUsageTimerReturn</type></link> telling you what to do next
184
 
</simpara></listitem></varlistentry>
185
 
</variablelist></refsect2>
186
 
<refsect2 id="stun-timer-remainder" role="function">
187
 
<title>stun_timer_remainder ()</title>
188
 
<indexterm zone="stun-timer-remainder"><primary sortas="stun_timer_remainder">stun_timer_remainder</primary></indexterm><programlisting><link linkend="unsigned">unsigned</link>            stun_timer_remainder                (const <link linkend="StunTimer">StunTimer</link> *timer);</programlisting>
189
 
<para>
190
 
Query the timer on the time left before the next refresh should be done</para>
191
 
<para>
192
 
</para><variablelist role="params">
193
 
<varlistentry><term><parameter>timer</parameter>&#160;:</term>
194
 
<listitem><simpara> The <link linkend="StunTimer"><type>StunTimer</type></link> to query
195
 
</simpara></listitem></varlistentry>
196
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The time remaining for the timer to expire in milliseconds
197
 
</simpara></listitem></varlistentry>
198
 
</variablelist></refsect2>
199
 
 
200
 
</refsect1>
201
 
 
202
 
 
203
 
 
204
 
 
205
 
</refentry>