docs/reference/libnice/html/libnice-TURN.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>TURN: libnice Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="libnice Reference Manual">
   8 <link rel="up" href="ch04.html" title="STUN usages">
   9 <link rel="prev" href="libnice-ICE.html" title="ICE">
  10 <link rel="next" href="libnice-Timer.html" title="Timer">
  11 <meta name="generator" content="GTK-Doc V1.29 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts">
  17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span>
  18                   <a href="#libnice-TURN.description" class="shortcut">Description</a></span>
  19 </td>
  20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  21 <td><a accesskey="u" href="ch04.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="libnice-ICE.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="libnice-Timer.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  24 </tr></table>
  25 <div class="refentry">
  26 <a name="libnice-TURN"></a><div class="titlepage"></div>
  27 <div class="refnamediv"><table width="100%"><tr>
  28 <td valign="top">
  29 <h2><span class="refentrytitle"><a name="libnice-TURN.top_of_page"></a>TURN</span></h2>
  30 <p>TURN — TURN Allocation Usage</p>
  31 </td>
  32 <td class="gallery_image" valign="top" align="right"></td>
  33 </tr></table></div>
  34 <div class="refsect1">
  35 <a name="libnice-TURN.stability-level"></a><h2>Stability Level</h2>
  36 <acronym title="The intention of a Stable interface is to enable arbitrary third parties to
  37 develop applications to these interfaces, release them, and have confidence that
  38 they will run on all minor releases of the product (after the one in which the
  39 interface was introduced, and within the same major release). Even at a major
  40 release, incompatible changes are expected to be rare, and to have strong
  41 justifications.
  42 "><span class="acronym">Stable</span></acronym>, unless otherwise indicated
  43 </div>
  44 <div class="refsect1">
  45 <a name="libnice-TURN.functions"></a><h2>Functions</h2>
  46 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  47 <colgroup>
  48 <col width="150px" class="functions_return">
  49 <col class="functions_name">
  50 </colgroup>
  51 <tbody>
  52 <tr>
  53 <td class="function_type">
  54 <span class="returnvalue">size_t</span>
  55 </td>
  56 <td class="function_name">
  57 <a class="link" href="libnice-TURN.html#stun-usage-turn-create" title="stun_usage_turn_create ()">stun_usage_turn_create</a> <span class="c_punctuation">()</span>
  58 </td>
  59 </tr>
  60 <tr>
  61 <td class="function_type">
  62 <span class="returnvalue">size_t</span>
  63 </td>
  64 <td class="function_name">
  65 <a class="link" href="libnice-TURN.html#stun-usage-turn-create-refresh" title="stun_usage_turn_create_refresh ()">stun_usage_turn_create_refresh</a> <span class="c_punctuation">()</span>
  66 </td>
  67 </tr>
  68 <tr>
  69 <td class="function_type">
  70 <a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="returnvalue">StunUsageTurnReturn</span></a>
  71 </td>
  72 <td class="function_name">
  73 <a class="link" href="libnice-TURN.html#stun-usage-turn-process" title="stun_usage_turn_process ()">stun_usage_turn_process</a> <span class="c_punctuation">()</span>
  74 </td>
  75 </tr>
  76 <tr>
  77 <td class="function_type">
  78 <a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="returnvalue">StunUsageTurnReturn</span></a>
  79 </td>
  80 <td class="function_name">
  81 <a class="link" href="libnice-TURN.html#stun-usage-turn-refresh-process" title="stun_usage_turn_refresh_process ()">stun_usage_turn_refresh_process</a> <span class="c_punctuation">()</span>
  82 </td>
  83 </tr>
  84 <tr>
  85 <td class="function_type">
  86 <span class="returnvalue">size_t</span>
  87 </td>
  88 <td class="function_name">
  89 <a class="link" href="libnice-TURN.html#stun-usage-turn-create-permission" title="stun_usage_turn_create_permission ()">stun_usage_turn_create_permission</a> <span class="c_punctuation">()</span>
  90 </td>
  91 </tr>
  92 </tbody>
  93 </table></div>
  94 </div>
  95 <div class="refsect1">
  96 <a name="libnice-TURN.other"></a><h2>Types and Values</h2>
  97 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  98 <colgroup>
  99 <col width="150px" class="name">
 100 <col class="description">
 101 </colgroup>
 102 <tbody>
 103 <tr>
 104 <td class="datatype_keyword">enum</td>
 105 <td class="function_name"><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility">StunUsageTurnCompatibility</a></td>
 106 </tr>
 107 <tr>
 108 <td class="datatype_keyword">enum</td>
 109 <td class="function_name"><a class="link" href="libnice-TURN.html#StunUsageTurnRequestPorts" title="enum StunUsageTurnRequestPorts">StunUsageTurnRequestPorts</a></td>
 110 </tr>
 111 <tr>
 112 <td class="datatype_keyword">enum</td>
 113 <td class="function_name"><a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn">StunUsageTurnReturn</a></td>
 114 </tr>
 115 </tbody>
 116 </table></div>
 117 </div>
 118 <div class="refsect1">
 119 <a name="libnice-TURN.includes"></a><h2>Includes</h2>
 120 <pre class="synopsis">#include &lt;stun/usages/turn.h&gt;
 121 </pre>
 122 </div>
 123 <div class="refsect1">
 124 <a name="libnice-TURN.description"></a><h2>Description</h2>
 125 <p>The STUN TURN usage allows for easily creating and parsing STUN Allocate
 126 requests and responses used for TURN. The API allows you to create a new
 127 allocation or refresh an existing one as well as to parse a response to
 128 an allocate or refresh request.</p>
 129 </div>
 130 <div class="refsect1">
 131 <a name="libnice-TURN.functions_details"></a><h2>Functions</h2>
 132 <div class="refsect2">
 133 <a name="stun-usage-turn-create"></a><h3>stun_usage_turn_create ()</h3>
 134 <pre class="programlisting"><span class="returnvalue">size_t</span>
 135 stun_usage_turn_create (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 136                         <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 137                         <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 138                         <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 139                         <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *previous_response</code></em>,
 140                         <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnRequestPorts" title="enum StunUsageTurnRequestPorts"><span class="type">StunUsageTurnRequestPorts</span></a> request_ports</code></em>,
 141                         <em class="parameter"><code><span class="type">int32_t</span> bandwidth</code></em>,
 142                         <em class="parameter"><code><span class="type">int32_t</span> lifetime</code></em>,
 143                         <em class="parameter"><code><span class="type">uint8_t</span> *username</code></em>,
 144                         <em class="parameter"><code><span class="type">size_t</span> username_len</code></em>,
 145                         <em class="parameter"><code><span class="type">uint8_t</span> *password</code></em>,
 146                         <em class="parameter"><code><span class="type">size_t</span> password_len</code></em>,
 147                         <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility"><span class="type">StunUsageTurnCompatibility</span></a> compatibility</code></em>);</pre>
 148 <p>Create a new TURN Allocation request</p>
 149 <div class="refsect3">
 150 <a name="stun-usage-turn-create.parameters"></a><h4>Parameters</h4>
 151 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 152 <colgroup>
 153 <col width="150px" class="parameters_name">
 154 <col class="parameters_description">
 155 <col width="200px" class="parameters_annotations">
 156 </colgroup>
 157 <tbody>
 158 <tr>
 159 <td class="parameter_name"><p>agent</p></td>
 160 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> to use to build the request</p></td>
 161 <td class="parameter_annotations"> </td>
 162 </tr>
 163 <tr>
 164 <td class="parameter_name"><p>msg</p></td>
 165 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> to build</p></td>
 166 <td class="parameter_annotations"> </td>
 167 </tr>
 168 <tr>
 169 <td class="parameter_name"><p>buffer</p></td>
 170 <td class="parameter_description"><p>The buffer to use for creating the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 171 <td class="parameter_annotations"> </td>
 172 </tr>
 173 <tr>
 174 <td class="parameter_name"><p>buffer_len</p></td>
 175 <td class="parameter_description"><p>The size of the <em class="parameter"><code>buffer</code></em>
 176 </p></td>
 177 <td class="parameter_annotations"> </td>
 178 </tr>
 179 <tr>
 180 <td class="parameter_name"><p>previous_response</p></td>
 181 <td class="parameter_description"><p>If this is the first request you are sending, set this
 182 argument to NULL, if it's a subsequent request you are building, then set this
 183 argument to the response you have received. This argument is used for building
 184 long term credentials (using the REALM and NONCE attributes) as well as for
 185 getting the RESERVATION-TOKEN attribute when you previously requested an
 186 allocation which reserved two ports</p></td>
 187 <td class="parameter_annotations"> </td>
 188 </tr>
 189 <tr>
 190 <td class="parameter_name"><p>request_ports</p></td>
 191 <td class="parameter_description">
 192 <p>Specify how you want to request the allocated port(s).
 193 This is only used if the compatibility is set to
 194 <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-COMPATIBILITY-DRAFT9:CAPS"><span class="type">STUN_USAGE_TURN_COMPATIBILITY_DRAFT9</span></a></p>
 195 <p>See <a class="link" href="libnice-TURN.html#StunUsageTurnRequestPorts" title="enum StunUsageTurnRequestPorts"><span class="type">StunUsageTurnRequestPorts</span></a> </p>
 196 </td>
 197 <td class="parameter_annotations"> </td>
 198 </tr>
 199 <tr>
 200 <td class="parameter_name"><p>bandwidth</p></td>
 201 <td class="parameter_description"><p>The bandwidth to request from the server for the allocation. If
 202 this value is negative, then no BANDWIDTH attribute is added to the request.
 203 This is only used if the compatibility is set to
 204 <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-COMPATIBILITY-DRAFT9:CAPS"><span class="type">STUN_USAGE_TURN_COMPATIBILITY_DRAFT9</span></a></p></td>
 205 <td class="parameter_annotations"> </td>
 206 </tr>
 207 <tr>
 208 <td class="parameter_name"><p>lifetime</p></td>
 209 <td class="parameter_description"><p>The lifetime of the allocation to request from the server. If
 210 this value is negative, then no LIFETIME attribute is added to the request.
 211 This is only used if the compatibility is set to
 212 <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-COMPATIBILITY-DRAFT9:CAPS"><span class="type">STUN_USAGE_TURN_COMPATIBILITY_DRAFT9</span></a></p></td>
 213 <td class="parameter_annotations"> </td>
 214 </tr>
 215 <tr>
 216 <td class="parameter_name"><p>username</p></td>
 217 <td class="parameter_description"><p>The username to use in the request</p></td>
 218 <td class="parameter_annotations"> </td>
 219 </tr>
 220 <tr>
 221 <td class="parameter_name"><p>username_len</p></td>
 222 <td class="parameter_description"><p>The length of <em class="parameter"><code>username</code></em>
 223 </p></td>
 224 <td class="parameter_annotations"> </td>
 225 </tr>
 226 <tr>
 227 <td class="parameter_name"><p>password</p></td>
 228 <td class="parameter_description"><p>The key to use for building the MESSAGE-INTEGRITY</p></td>
 229 <td class="parameter_annotations"> </td>
 230 </tr>
 231 <tr>
 232 <td class="parameter_name"><p>password_len</p></td>
 233 <td class="parameter_description"><p>The length of <em class="parameter"><code>password</code></em>
 234 </p></td>
 235 <td class="parameter_annotations"> </td>
 236 </tr>
 237 <tr>
 238 <td class="parameter_name"><p>compatibility</p></td>
 239 <td class="parameter_description"><p>The compatibility mode to use for building the Allocation
 240 request</p></td>
 241 <td class="parameter_annotations"> </td>
 242 </tr>
 243 </tbody>
 244 </table></div>
 245 </div>
 246 <div class="refsect3">
 247 <a name="stun-usage-turn-create.returns"></a><h4>Returns</h4>
 248 <p> The length of the message to send</p>
 249 </div>
 250 </div>
 251 <hr>
 252 <div class="refsect2">
 253 <a name="stun-usage-turn-create-refresh"></a><h3>stun_usage_turn_create_refresh ()</h3>
 254 <pre class="programlisting"><span class="returnvalue">size_t</span>
 255 stun_usage_turn_create_refresh (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 256                                 <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 257                                 <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 258                                 <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 259                                 <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *previous_response</code></em>,
 260                                 <em class="parameter"><code><span class="type">int32_t</span> lifetime</code></em>,
 261                                 <em class="parameter"><code><span class="type">uint8_t</span> *username</code></em>,
 262                                 <em class="parameter"><code><span class="type">size_t</span> username_len</code></em>,
 263                                 <em class="parameter"><code><span class="type">uint8_t</span> *password</code></em>,
 264                                 <em class="parameter"><code><span class="type">size_t</span> password_len</code></em>,
 265                                 <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility"><span class="type">StunUsageTurnCompatibility</span></a> compatibility</code></em>);</pre>
 266 <p>Create a new TURN Refresh request</p>
 267 <div class="refsect3">
 268 <a name="stun-usage-turn-create-refresh.parameters"></a><h4>Parameters</h4>
 269 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 270 <colgroup>
 271 <col width="150px" class="parameters_name">
 272 <col class="parameters_description">
 273 <col width="200px" class="parameters_annotations">
 274 </colgroup>
 275 <tbody>
 276 <tr>
 277 <td class="parameter_name"><p>agent</p></td>
 278 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> to use to build the request</p></td>
 279 <td class="parameter_annotations"> </td>
 280 </tr>
 281 <tr>
 282 <td class="parameter_name"><p>msg</p></td>
 283 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> to build</p></td>
 284 <td class="parameter_annotations"> </td>
 285 </tr>
 286 <tr>
 287 <td class="parameter_name"><p>buffer</p></td>
 288 <td class="parameter_description"><p>The buffer to use for creating the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 289 <td class="parameter_annotations"> </td>
 290 </tr>
 291 <tr>
 292 <td class="parameter_name"><p>buffer_len</p></td>
 293 <td class="parameter_description"><p>The size of the <em class="parameter"><code>buffer</code></em>
 294 </p></td>
 295 <td class="parameter_annotations"> </td>
 296 </tr>
 297 <tr>
 298 <td class="parameter_name"><p>previous_response</p></td>
 299 <td class="parameter_description"><p>If this is the first request you are sending, set this
 300 argument to NULL, if it's a subsequent request you are building, then set this
 301 argument to the response you have received. This argument is used for building
 302 long term credentials (using the REALM and NONCE attributes)</p></td>
 303 <td class="parameter_annotations"> </td>
 304 </tr>
 305 <tr>
 306 <td class="parameter_name"><p>lifetime</p></td>
 307 <td class="parameter_description"><p>The lifetime of the allocation to request from the server. If
 308 this value is negative, then no LIFETIME attribute is added to the request.
 309 This is only used if the compatibility is set to
 310 <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-COMPATIBILITY-DRAFT9:CAPS"><span class="type">STUN_USAGE_TURN_COMPATIBILITY_DRAFT9</span></a></p></td>
 311 <td class="parameter_annotations"> </td>
 312 </tr>
 313 <tr>
 314 <td class="parameter_name"><p>username</p></td>
 315 <td class="parameter_description"><p>The username to use in the request</p></td>
 316 <td class="parameter_annotations"> </td>
 317 </tr>
 318 <tr>
 319 <td class="parameter_name"><p>username_len</p></td>
 320 <td class="parameter_description"><p>The length of <em class="parameter"><code>username</code></em>
 321 </p></td>
 322 <td class="parameter_annotations"> </td>
 323 </tr>
 324 <tr>
 325 <td class="parameter_name"><p>password</p></td>
 326 <td class="parameter_description"><p>The key to use for building the MESSAGE-INTEGRITY</p></td>
 327 <td class="parameter_annotations"> </td>
 328 </tr>
 329 <tr>
 330 <td class="parameter_name"><p>password_len</p></td>
 331 <td class="parameter_description"><p>The length of <em class="parameter"><code>password</code></em>
 332 </p></td>
 333 <td class="parameter_annotations"> </td>
 334 </tr>
 335 <tr>
 336 <td class="parameter_name"><p>compatibility</p></td>
 337 <td class="parameter_description"><p>The compatibility mode to use for building the Allocation
 338 request</p></td>
 339 <td class="parameter_annotations"> </td>
 340 </tr>
 341 </tbody>
 342 </table></div>
 343 </div>
 344 <div class="refsect3">
 345 <a name="stun-usage-turn-create-refresh.returns"></a><h4>Returns</h4>
 346 <p> The length of the message to send</p>
 347 </div>
 348 </div>
 349 <hr>
 350 <div class="refsect2">
 351 <a name="stun-usage-turn-process"></a><h3>stun_usage_turn_process ()</h3>
 352 <pre class="programlisting"><a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="returnvalue">StunUsageTurnReturn</span></a>
 353 stun_usage_turn_process (<em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 354                          <em class="parameter"><code><span class="type">struct sockaddr_storage</span> *relay_addr</code></em>,
 355                          <em class="parameter"><code><a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#socklen-t"><span class="type">socklen_t</span></a> *relay_addrlen</code></em>,
 356                          <em class="parameter"><code><span class="type">struct sockaddr_storage</span> *addr</code></em>,
 357                          <em class="parameter"><code><a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#socklen-t"><span class="type">socklen_t</span></a> *addrlen</code></em>,
 358                          <em class="parameter"><code><span class="type">struct sockaddr_storage</span> *alternate_server</code></em>,
 359                          <em class="parameter"><code><a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#socklen-t"><span class="type">socklen_t</span></a> *alternate_server_len</code></em>,
 360                          <em class="parameter"><code><span class="type">uint32_t</span> *bandwidth</code></em>,
 361                          <em class="parameter"><code><span class="type">uint32_t</span> *lifetime</code></em>,
 362                          <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility"><span class="type">StunUsageTurnCompatibility</span></a> compatibility</code></em>);</pre>
 363 <p>Process a TURN Allocate response and extract the necessary information from
 364 the message</p>
 365 <div class="refsect3">
 366 <a name="stun-usage-turn-process.parameters"></a><h4>Parameters</h4>
 367 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 368 <colgroup>
 369 <col width="150px" class="parameters_name">
 370 <col class="parameters_description">
 371 <col width="200px" class="parameters_annotations">
 372 </colgroup>
 373 <tbody>
 374 <tr>
 375 <td class="parameter_name"><p>msg</p></td>
 376 <td class="parameter_description"><p>The message containing the response</p></td>
 377 <td class="parameter_annotations"> </td>
 378 </tr>
 379 <tr>
 380 <td class="parameter_name"><p>relay_addr</p></td>
 381 <td class="parameter_description"><p>A pointer to a <a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#sockaddr"><span class="type">sockaddr</span></a> structure to fill with the relay address
 382 that the TURN server allocated for us</p></td>
 383 <td class="parameter_annotations"> </td>
 384 </tr>
 385 <tr>
 386 <td class="parameter_name"><p>relay_addrlen</p></td>
 387 <td class="parameter_description"><p>The length of <em class="parameter"><code>relay_addr</code></em>
 388 </p></td>
 389 <td class="parameter_annotations"> </td>
 390 </tr>
 391 <tr>
 392 <td class="parameter_name"><p>addr</p></td>
 393 <td class="parameter_description"><p>A pointer to a <a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#sockaddr"><span class="type">sockaddr</span></a> structure to fill with the mapped address
 394 that the STUN response contains.
 395 This argument will only be filled if the return value
 396 of the function is <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-RETURN-MAPPED-SUCCESS:CAPS"><span class="type">STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS</span></a></p></td>
 397 <td class="parameter_annotations"> </td>
 398 </tr>
 399 <tr>
 400 <td class="parameter_name"><p>addrlen</p></td>
 401 <td class="parameter_description"><p>The length of <em class="parameter"><code>addr</code></em>
 402 </p></td>
 403 <td class="parameter_annotations"> </td>
 404 </tr>
 405 <tr>
 406 <td class="parameter_name"><p>alternate_server</p></td>
 407 <td class="parameter_description"><p>A pointer to a <a href="/usr/share/gtk-doc/html/camel/camel-camel-net-utils.html#sockaddr"><span class="type">sockaddr</span></a> structure to fill with the
 408 address of an alternate server to which we should send our new STUN
 409 Allocate request, in case the currently used TURN server is requesting the use
 410 of an alternate server. This argument will only be filled if the return value
 411 of the function is <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-RETURN-ALTERNATE-SERVER:CAPS"><span class="type">STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER</span></a>
 412 In the case of <em class="parameter"><code>STUN_USAGE_TURN_COMPATIBILITY_OC2007</code></em>
 413 compatibility, the
 414 <em class="parameter"><code>alternate_server</code></em>
 415 could be filled at any time, and should only be considered
 416 if the request was sent to a different server than the address returned
 417 in the <em class="parameter"><code>alternate_server</code></em>
 418 field</p></td>
 419 <td class="parameter_annotations"> </td>
 420 </tr>
 421 <tr>
 422 <td class="parameter_name"><p>alternate_server_len</p></td>
 423 <td class="parameter_description"><p>The length of <em class="parameter"><code>alternate_server</code></em>
 424 </p></td>
 425 <td class="parameter_annotations"> </td>
 426 </tr>
 427 <tr>
 428 <td class="parameter_name"><p>bandwidth</p></td>
 429 <td class="parameter_description"><p>A pointer to fill with the bandwidth the TURN server allocated us</p></td>
 430 <td class="parameter_annotations"> </td>
 431 </tr>
 432 <tr>
 433 <td class="parameter_name"><p>lifetime</p></td>
 434 <td class="parameter_description"><p>A pointer to fill with the lifetime of the allocation</p></td>
 435 <td class="parameter_annotations"> </td>
 436 </tr>
 437 <tr>
 438 <td class="parameter_name"><p>compatibility</p></td>
 439 <td class="parameter_description"><p>The compatibility mode to use for processing the Allocation
 440 response</p></td>
 441 <td class="parameter_annotations"> </td>
 442 </tr>
 443 </tbody>
 444 </table></div>
 445 </div>
 446 <div class="refsect3">
 447 <a name="stun-usage-turn-process.returns"></a><h4>Returns</h4>
 448 <p> A <a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="type">StunUsageTurnReturn</span></a> value</p>
 449 </div>
 450 </div>
 451 <hr>
 452 <div class="refsect2">
 453 <a name="stun-usage-turn-refresh-process"></a><h3>stun_usage_turn_refresh_process ()</h3>
 454 <pre class="programlisting"><a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="returnvalue">StunUsageTurnReturn</span></a>
 455 stun_usage_turn_refresh_process (<em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 456                                  <em class="parameter"><code><span class="type">uint32_t</span> *lifetime</code></em>,
 457                                  <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility"><span class="type">StunUsageTurnCompatibility</span></a> compatibility</code></em>);</pre>
 458 <p>Process a TURN Refresh response and extract the necessary information from
 459 the message</p>
 460 <div class="refsect3">
 461 <a name="stun-usage-turn-refresh-process.parameters"></a><h4>Parameters</h4>
 462 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 463 <colgroup>
 464 <col width="150px" class="parameters_name">
 465 <col class="parameters_description">
 466 <col width="200px" class="parameters_annotations">
 467 </colgroup>
 468 <tbody>
 469 <tr>
 470 <td class="parameter_name"><p>msg</p></td>
 471 <td class="parameter_description"><p>The message containing the response</p></td>
 472 <td class="parameter_annotations"> </td>
 473 </tr>
 474 <tr>
 475 <td class="parameter_name"><p>lifetime</p></td>
 476 <td class="parameter_description"><p>A pointer to fill with the lifetime of the allocation</p></td>
 477 <td class="parameter_annotations"> </td>
 478 </tr>
 479 <tr>
 480 <td class="parameter_name"><p>compatibility</p></td>
 481 <td class="parameter_description"><p>The compatibility mode to use for processing the Refresh
 482 response</p></td>
 483 <td class="parameter_annotations"> </td>
 484 </tr>
 485 </tbody>
 486 </table></div>
 487 </div>
 488 <div class="refsect3">
 489 <a name="stun-usage-turn-refresh-process.returns"></a><h4>Returns</h4>
 490 <p> A <a class="link" href="libnice-TURN.html#StunUsageTurnReturn" title="enum StunUsageTurnReturn"><span class="type">StunUsageTurnReturn</span></a> value. A <a class="link" href="libnice-TURN.html#STUN-USAGE-TURN-RETURN-RELAY-SUCCESS:CAPS"><span class="type">STUN_USAGE_TURN_RETURN_RELAY_SUCCESS</span></a>
 491 means the Refresh was successful, but no relay address is given (kept the same
 492 as for the original allocation)</p>
 493 </div>
 494 </div>
 495 <hr>
 496 <div class="refsect2">
 497 <a name="stun-usage-turn-create-permission"></a><h3>stun_usage_turn_create_permission ()</h3>
 498 <pre class="programlisting"><span class="returnvalue">size_t</span>
 499 stun_usage_turn_create_permission (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 500                                    <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 501                                    <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 502                                    <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 503                                    <em class="parameter"><code><span class="type">uint8_t</span> *username</code></em>,
 504                                    <em class="parameter"><code><span class="type">size_t</span> username_len</code></em>,
 505                                    <em class="parameter"><code><span class="type">uint8_t</span> *password</code></em>,
 506                                    <em class="parameter"><code><span class="type">size_t</span> password_len</code></em>,
 507                                    <em class="parameter"><code><span class="type">uint8_t</span> *realm</code></em>,
 508                                    <em class="parameter"><code><span class="type">size_t</span> realm_len</code></em>,
 509                                    <em class="parameter"><code><span class="type">uint8_t</span> *nonce</code></em>,
 510                                    <em class="parameter"><code><span class="type">size_t</span> nonce_len</code></em>,
 511                                    <em class="parameter"><code><span class="type">struct sockaddr_storage</span> *peer</code></em>,
 512                                    <em class="parameter"><code><a class="link" href="libnice-TURN.html#StunUsageTurnCompatibility" title="enum StunUsageTurnCompatibility"><span class="type">StunUsageTurnCompatibility</span></a> compatibility</code></em>);</pre>
 513 <p>Create a new TURN CreatePermission request</p>
 514 <div class="refsect3">
 515 <a name="stun-usage-turn-create-permission.parameters"></a><h4>Parameters</h4>
 516 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 517 <colgroup>
 518 <col width="150px" class="parameters_name">
 519 <col class="parameters_description">
 520 <col width="200px" class="parameters_annotations">
 521 </colgroup>
 522 <tbody>
 523 <tr>
 524 <td class="parameter_name"><p>agent</p></td>
 525 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> to use to build the request</p></td>
 526 <td class="parameter_annotations"> </td>
 527 </tr>
 528 <tr>
 529 <td class="parameter_name"><p>msg</p></td>
 530 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> to build</p></td>
 531 <td class="parameter_annotations"> </td>
 532 </tr>
 533 <tr>
 534 <td class="parameter_name"><p>buffer</p></td>
 535 <td class="parameter_description"><p>The buffer to use for creating the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 536 <td class="parameter_annotations"> </td>
 537 </tr>
 538 <tr>
 539 <td class="parameter_name"><p>buffer_len</p></td>
 540 <td class="parameter_description"><p>The size of the <em class="parameter"><code>buffer</code></em>
 541 </p></td>
 542 <td class="parameter_annotations"> </td>
 543 </tr>
 544 <tr>
 545 <td class="parameter_name"><p>username</p></td>
 546 <td class="parameter_description"><p>The username to use in the request</p></td>
 547 <td class="parameter_annotations"> </td>
 548 </tr>
 549 <tr>
 550 <td class="parameter_name"><p>username_len</p></td>
 551 <td class="parameter_description"><p>The length of <em class="parameter"><code>username</code></em>
 552 </p></td>
 553 <td class="parameter_annotations"> </td>
 554 </tr>
 555 <tr>
 556 <td class="parameter_name"><p>password</p></td>
 557 <td class="parameter_description"><p>The key to use for building the MESSAGE-INTEGRITY</p></td>
 558 <td class="parameter_annotations"> </td>
 559 </tr>
 560 <tr>
 561 <td class="parameter_name"><p>password_len</p></td>
 562 <td class="parameter_description"><p>The length of <em class="parameter"><code>password</code></em>
 563 </p></td>
 564 <td class="parameter_annotations"> </td>
 565 </tr>
 566 <tr>
 567 <td class="parameter_name"><p>realm</p></td>
 568 <td class="parameter_description"><p>The realm identifier to use in the request</p></td>
 569 <td class="parameter_annotations"> </td>
 570 </tr>
 571 <tr>
 572 <td class="parameter_name"><p>realm_len</p></td>
 573 <td class="parameter_description"><p>The length of <em class="parameter"><code>realm</code></em>
 574 </p></td>
 575 <td class="parameter_annotations"> </td>
 576 </tr>
 577 <tr>
 578 <td class="parameter_name"><p>nonce</p></td>
 579 <td class="parameter_description"><p>Unique and securely random nonce to use in the request</p></td>
 580 <td class="parameter_annotations"> </td>
 581 </tr>
 582 <tr>
 583 <td class="parameter_name"><p>nonce_len</p></td>
 584 <td class="parameter_description"><p>The length of <em class="parameter"><code>nonce</code></em>
 585 </p></td>
 586 <td class="parameter_annotations"> </td>
 587 </tr>
 588 <tr>
 589 <td class="parameter_name"><p>peer</p></td>
 590 <td class="parameter_description"><p>Server-reflexive host address to request permission for</p></td>
 591 <td class="parameter_annotations"> </td>
 592 </tr>
 593 <tr>
 594 <td class="parameter_name"><p>compatibility</p></td>
 595 <td class="parameter_description"><p>The compatibility mode to use for building the
 596 CreatePermission request</p></td>
 597 <td class="parameter_annotations"> </td>
 598 </tr>
 599 </tbody>
 600 </table></div>
 601 </div>
 602 <div class="refsect3">
 603 <a name="stun-usage-turn-create-permission.returns"></a><h4>Returns</h4>
 604 <p> The length of the message to send</p>
 605 </div>
 606 </div>
 607 </div>
 608 <div class="refsect1">
 609 <a name="libnice-TURN.other_details"></a><h2>Types and Values</h2>
 610 <div class="refsect2">
 611 <a name="StunUsageTurnCompatibility"></a><h3>enum StunUsageTurnCompatibility</h3>
 612 <p>Specifies which TURN specification compatibility to use</p>
 613 <div class="refsect3">
 614 <a name="StunUsageTurnCompatibility.members"></a><h4>Members</h4>
 615 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 616 <colgroup>
 617 <col width="300px" class="enum_members_name">
 618 <col class="enum_members_description">
 619 <col width="200px" class="enum_members_annotations">
 620 </colgroup>
 621 <tbody>
 622 <tr>
 623 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-COMPATIBILITY-DRAFT9:CAPS"></a>STUN_USAGE_TURN_COMPATIBILITY_DRAFT9</p></td>
 624 <td class="enum_member_description">
 625 <p>Use the specification compatible with
 626 TURN Draft 09</p>
 627 </td>
 628 <td class="enum_member_annotations"> </td>
 629 </tr>
 630 <tr>
 631 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-COMPATIBILITY-GOOGLE:CAPS"></a>STUN_USAGE_TURN_COMPATIBILITY_GOOGLE</p></td>
 632 <td class="enum_member_description">
 633 <p>Use the specification compatible with
 634 Google Talk's relay server</p>
 635 </td>
 636 <td class="enum_member_annotations"> </td>
 637 </tr>
 638 <tr>
 639 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-COMPATIBILITY-MSN:CAPS"></a>STUN_USAGE_TURN_COMPATIBILITY_MSN</p></td>
 640 <td class="enum_member_description">
 641 <p>Use the specification compatible with
 642 MSN TURN servers</p>
 643 </td>
 644 <td class="enum_member_annotations"> </td>
 645 </tr>
 646 <tr>
 647 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-COMPATIBILITY-OC2007:CAPS"></a>STUN_USAGE_TURN_COMPATIBILITY_OC2007</p></td>
 648 <td class="enum_member_description">
 649 <p>Use the specification compatible with
 650 Microsoft Office Communicator 2007</p>
 651 </td>
 652 <td class="enum_member_annotations"> </td>
 653 </tr>
 654 <tr>
 655 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-COMPATIBILITY-RFC5766:CAPS"></a>STUN_USAGE_TURN_COMPATIBILITY_RFC5766</p></td>
 656 <td class="enum_member_description">
 657 <p>Use the specification compatible with
 658 RFC 5766 (the final, canonical TURN standard)</p>
 659 </td>
 660 <td class="enum_member_annotations"> </td>
 661 </tr>
 662 </tbody>
 663 </table></div>
 664 </div>
 665 </div>
 666 <hr>
 667 <div class="refsect2">
 668 <a name="StunUsageTurnRequestPorts"></a><h3>enum StunUsageTurnRequestPorts</h3>
 669 <p>This enum is used to specify which port configuration you want when creating
 670 a new Allocation</p>
 671 <div class="refsect3">
 672 <a name="StunUsageTurnRequestPorts.members"></a><h4>Members</h4>
 673 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 674 <colgroup>
 675 <col width="300px" class="enum_members_name">
 676 <col class="enum_members_description">
 677 <col width="200px" class="enum_members_annotations">
 678 </colgroup>
 679 <tbody>
 680 <tr>
 681 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-REQUEST-PORT-NORMAL:CAPS"></a>STUN_USAGE_TURN_REQUEST_PORT_NORMAL</p></td>
 682 <td class="enum_member_description">
 683 <p>Request a normal port</p>
 684 </td>
 685 <td class="enum_member_annotations"> </td>
 686 </tr>
 687 <tr>
 688 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-REQUEST-PORT-EVEN:CAPS"></a>STUN_USAGE_TURN_REQUEST_PORT_EVEN</p></td>
 689 <td class="enum_member_description">
 690 <p>Request an even port</p>
 691 </td>
 692 <td class="enum_member_annotations"> </td>
 693 </tr>
 694 <tr>
 695 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-REQUEST-PORT-EVEN-AND-RESERVE:CAPS"></a>STUN_USAGE_TURN_REQUEST_PORT_EVEN_AND_RESERVE</p></td>
 696 <td class="enum_member_description">
 697 <p>Request an even port and
 698 reserve the next higher port</p>
 699 </td>
 700 <td class="enum_member_annotations"> </td>
 701 </tr>
 702 </tbody>
 703 </table></div>
 704 </div>
 705 </div>
 706 <hr>
 707 <div class="refsect2">
 708 <a name="StunUsageTurnReturn"></a><h3>enum StunUsageTurnReturn</h3>
 709 <p>Return value of <a class="link" href="libnice-TURN.html#stun-usage-turn-process" title="stun_usage_turn_process ()"><code class="function">stun_usage_turn_process()</code></a> and
 710 <a class="link" href="libnice-TURN.html#stun-usage-turn-refresh-process" title="stun_usage_turn_refresh_process ()"><code class="function">stun_usage_turn_refresh_process()</code></a> which allows you to see what status the
 711 function call returned.</p>
 712 <div class="refsect3">
 713 <a name="StunUsageTurnReturn.members"></a><h4>Members</h4>
 714 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 715 <colgroup>
 716 <col width="300px" class="enum_members_name">
 717 <col class="enum_members_description">
 718 <col width="200px" class="enum_members_annotations">
 719 </colgroup>
 720 <tbody>
 721 <tr>
 722 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-RETURN-RELAY-SUCCESS:CAPS"></a>STUN_USAGE_TURN_RETURN_RELAY_SUCCESS</p></td>
 723 <td class="enum_member_description">
 724 <p>The response was successful and a relay
 725 address is provided</p>
 726 </td>
 727 <td class="enum_member_annotations"> </td>
 728 </tr>
 729 <tr>
 730 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-RETURN-MAPPED-SUCCESS:CAPS"></a>STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS</p></td>
 731 <td class="enum_member_description">
 732 <p>The response was successful and a
 733 relay address as well as a mapped address are provided</p>
 734 </td>
 735 <td class="enum_member_annotations"> </td>
 736 </tr>
 737 <tr>
 738 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-RETURN-ERROR:CAPS"></a>STUN_USAGE_TURN_RETURN_ERROR</p></td>
 739 <td class="enum_member_description">
 740 <p>The response resulted in an error</p>
 741 </td>
 742 <td class="enum_member_annotations"> </td>
 743 </tr>
 744 <tr>
 745 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-RETURN-INVALID:CAPS"></a>STUN_USAGE_TURN_RETURN_INVALID</p></td>
 746 <td class="enum_member_description">
 747 <p>The response is not a valid response</p>
 748 </td>
 749 <td class="enum_member_annotations"> </td>
 750 </tr>
 751 <tr>
 752 <td class="enum_member_name"><p><a name="STUN-USAGE-TURN-RETURN-ALTERNATE-SERVER:CAPS"></a>STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER</p></td>
 753 <td class="enum_member_description">
 754 <p>The server requests the message
 755 to be sent to an alternate server</p>
 756 </td>
 757 <td class="enum_member_annotations"> </td>
 758 </tr>
 759 </tbody>
 760 </table></div>
 761 </div>
 762 </div>
 763 </div>
 764 </div>
 765 <div class="footer">
 766 <hr>Generated by GTK-Doc V1.29</div>
 767 </body>
 768 </html>