docs/reference/libnice/html/libnice-StunAgent.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>StunAgent: 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="ch03.html" title="">
   9 <link rel="prev" href="ch03.html" title="">
  10 <link rel="next" href="libnice-StunMessage.html" title="StunMessage">
  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-StunAgent.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="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="ch03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="libnice-StunMessage.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-StunAgent"></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-StunAgent.top_of_page"></a>StunAgent</span></h2>
  30 <p>StunAgent — STUN agent for building and validating STUN messages</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-StunAgent.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-StunAgent.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">bool</span>
  55 </td>
  56 <td class="function_name">
  57 <span class="c_punctuation">(</span><a class="link" href="libnice-StunAgent.html#StunMessageIntegrityValidate" title="StunMessageIntegrityValidate ()">*StunMessageIntegrityValidate</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
  58 </td>
  59 </tr>
  60 <tr>
  61 <td class="function_type">
  62 <span class="returnvalue">void</span>
  63 </td>
  64 <td class="function_name">
  65 <span class="c_punctuation">(</span><a class="link" href="libnice-StunAgent.html#StunDebugHandler" title="StunDebugHandler ()">*StunDebugHandler</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
  66 </td>
  67 </tr>
  68 <tr>
  69 <td class="function_type">
  70 <span class="returnvalue">void</span>
  71 </td>
  72 <td class="function_name">
  73 <a class="link" href="libnice-StunAgent.html#stun-agent-init" title="stun_agent_init ()">stun_agent_init</a> <span class="c_punctuation">()</span>
  74 </td>
  75 </tr>
  76 <tr>
  77 <td class="function_type">
  78 <a class="link" href="libnice-StunAgent.html#StunValidationStatus" title="enum StunValidationStatus"><span class="returnvalue">StunValidationStatus</span></a>
  79 </td>
  80 <td class="function_name">
  81 <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()">stun_agent_validate</a> <span class="c_punctuation">()</span>
  82 </td>
  83 </tr>
  84 <tr>
  85 <td class="function_type">
  86 <span class="returnvalue">bool</span>
  87 </td>
  88 <td class="function_name">
  89 <a class="link" href="libnice-StunAgent.html#stun-agent-default-validater" title="stun_agent_default_validater ()">stun_agent_default_validater</a> <span class="c_punctuation">()</span>
  90 </td>
  91 </tr>
  92 <tr>
  93 <td class="function_type">
  94 <span class="returnvalue">bool</span>
  95 </td>
  96 <td class="function_name">
  97 <a class="link" href="libnice-StunAgent.html#stun-agent-init-request" title="stun_agent_init_request ()">stun_agent_init_request</a> <span class="c_punctuation">()</span>
  98 </td>
  99 </tr>
 100 <tr>
 101 <td class="function_type">
 102 <span class="returnvalue">bool</span>
 103 </td>
 104 <td class="function_name">
 105 <a class="link" href="libnice-StunAgent.html#stun-agent-init-indication" title="stun_agent_init_indication ()">stun_agent_init_indication</a> <span class="c_punctuation">()</span>
 106 </td>
 107 </tr>
 108 <tr>
 109 <td class="function_type">
 110 <span class="returnvalue">bool</span>
 111 </td>
 112 <td class="function_name">
 113 <a class="link" href="libnice-StunAgent.html#stun-agent-init-response" title="stun_agent_init_response ()">stun_agent_init_response</a> <span class="c_punctuation">()</span>
 114 </td>
 115 </tr>
 116 <tr>
 117 <td class="function_type">
 118 <span class="returnvalue">bool</span>
 119 </td>
 120 <td class="function_name">
 121 <a class="link" href="libnice-StunAgent.html#stun-agent-init-error" title="stun_agent_init_error ()">stun_agent_init_error</a> <span class="c_punctuation">()</span>
 122 </td>
 123 </tr>
 124 <tr>
 125 <td class="function_type">
 126 <span class="returnvalue">size_t</span>
 127 </td>
 128 <td class="function_name">
 129 <a class="link" href="libnice-StunAgent.html#stun-agent-build-unknown-attributes-error" title="stun_agent_build_unknown_attributes_error ()">stun_agent_build_unknown_attributes_error</a> <span class="c_punctuation">()</span>
 130 </td>
 131 </tr>
 132 <tr>
 133 <td class="function_type">
 134 <span class="returnvalue">size_t</span>
 135 </td>
 136 <td class="function_name">
 137 <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()">stun_agent_finish_message</a> <span class="c_punctuation">()</span>
 138 </td>
 139 </tr>
 140 <tr>
 141 <td class="function_type">
 142 <span class="returnvalue">bool</span>
 143 </td>
 144 <td class="function_name">
 145 <a class="link" href="libnice-StunAgent.html#stun-agent-forget-transaction" title="stun_agent_forget_transaction ()">stun_agent_forget_transaction</a> <span class="c_punctuation">()</span>
 146 </td>
 147 </tr>
 148 <tr>
 149 <td class="function_type">
 150 <span class="returnvalue">void</span>
 151 </td>
 152 <td class="function_name">
 153 <a class="link" href="libnice-StunAgent.html#stun-agent-set-software" title="stun_agent_set_software ()">stun_agent_set_software</a> <span class="c_punctuation">()</span>
 154 </td>
 155 </tr>
 156 <tr>
 157 <td class="function_type">
 158 <span class="returnvalue">void</span>
 159 </td>
 160 <td class="function_name">
 161 <a class="link" href="libnice-StunAgent.html#stun-debug-enable" title="stun_debug_enable ()">stun_debug_enable</a> <span class="c_punctuation">()</span>
 162 </td>
 163 </tr>
 164 <tr>
 165 <td class="function_type">
 166 <span class="returnvalue">void</span>
 167 </td>
 168 <td class="function_name">
 169 <a class="link" href="libnice-StunAgent.html#stun-debug-disable" title="stun_debug_disable ()">stun_debug_disable</a> <span class="c_punctuation">()</span>
 170 </td>
 171 </tr>
 172 <tr>
 173 <td class="function_type">
 174 <span class="returnvalue">void</span>
 175 </td>
 176 <td class="function_name">
 177 <a class="link" href="libnice-StunAgent.html#stun-set-debug-handler" title="stun_set_debug_handler ()">stun_set_debug_handler</a> <span class="c_punctuation">()</span>
 178 </td>
 179 </tr>
 180 </tbody>
 181 </table></div>
 182 </div>
 183 <div class="refsect1">
 184 <a name="libnice-StunAgent.other"></a><h2>Types and Values</h2>
 185 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 186 <colgroup>
 187 <col width="150px" class="name">
 188 <col class="description">
 189 </colgroup>
 190 <tbody>
 191 <tr>
 192 <td class="typedef_keyword">typedef</td>
 193 <td class="function_name"><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent">StunAgent</a></td>
 194 </tr>
 195 <tr>
 196 <td class="datatype_keyword">enum</td>
 197 <td class="function_name"><a class="link" href="libnice-StunAgent.html#StunCompatibility" title="enum StunCompatibility">StunCompatibility</a></td>
 198 </tr>
 199 <tr>
 200 <td class="datatype_keyword">enum</td>
 201 <td class="function_name"><a class="link" href="libnice-StunAgent.html#StunAgentUsageFlags" title="enum StunAgentUsageFlags">StunAgentUsageFlags</a></td>
 202 </tr>
 203 <tr>
 204 <td class="datatype_keyword">enum</td>
 205 <td class="function_name"><a class="link" href="libnice-StunAgent.html#StunValidationStatus" title="enum StunValidationStatus">StunValidationStatus</a></td>
 206 </tr>
 207 <tr>
 208 <td class="datatype_keyword"> </td>
 209 <td class="function_name"><a class="link" href="libnice-StunAgent.html#StunDefaultValidaterData" title="StunDefaultValidaterData">StunDefaultValidaterData</a></td>
 210 </tr>
 211 </tbody>
 212 </table></div>
 213 </div>
 214 <div class="refsect1">
 215 <a name="libnice-StunAgent.includes"></a><h2>Includes</h2>
 216 <pre class="synopsis">#include &lt;stun/stunagent.h&gt;
 217 </pre>
 218 </div>
 219 <div class="refsect1">
 220 <a name="libnice-StunAgent.description"></a><h2>Description</h2>
 221 <p>The STUN Agent allows you to create and validate STUN messages easily.
 222 It's main purpose is to make sure the building and validation methods used
 223 are compatible with the RFC you create it with. It also tracks the transaction
 224 ids of the requests you send, so you can validate if a STUN response you
 225 received should be processed by that agent or not.</p>
 226 </div>
 227 <div class="refsect1">
 228 <a name="libnice-StunAgent.functions_details"></a><h2>Functions</h2>
 229 <div class="refsect2">
 230 <a name="StunMessageIntegrityValidate"></a><h3>StunMessageIntegrityValidate ()</h3>
 231 <pre class="programlisting"><span class="returnvalue">bool</span>
 232 <span class="c_punctuation">(</span>*StunMessageIntegrityValidate<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 233                                  <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *message</code></em>,
 234                                  <em class="parameter"><code><span class="type">uint8_t</span> *username</code></em>,
 235                                  <em class="parameter"><code><span class="type">uint16_t</span> username_len</code></em>,
 236                                  <em class="parameter"><code><span class="type">uint8_t</span> **password</code></em>,
 237                                  <em class="parameter"><code><span class="type">size_t</span> *password_len</code></em>,
 238                                  <em class="parameter"><code><span class="type">void</span> *user_data</code></em>);</pre>
 239 <p>This is the prototype for the <em class="parameter"><code>validater</code></em>
 240  argument of the <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a>
 241 function.</p>
 242 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a> </p>
 243 <div class="refsect3">
 244 <a name="StunMessageIntegrityValidate.parameters"></a><h4>Parameters</h4>
 245 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 246 <colgroup>
 247 <col width="150px" class="parameters_name">
 248 <col class="parameters_description">
 249 <col width="200px" class="parameters_annotations">
 250 </colgroup>
 251 <tbody>
 252 <tr>
 253 <td class="parameter_name"><p>agent</p></td>
 254 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 255 <td class="parameter_annotations"> </td>
 256 </tr>
 257 <tr>
 258 <td class="parameter_name"><p>message</p></td>
 259 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> being validated</p></td>
 260 <td class="parameter_annotations"> </td>
 261 </tr>
 262 <tr>
 263 <td class="parameter_name"><p>username</p></td>
 264 <td class="parameter_description"><p>The username found in the <em class="parameter"><code>message</code></em>
 265 </p></td>
 266 <td class="parameter_annotations"> </td>
 267 </tr>
 268 <tr>
 269 <td class="parameter_name"><p>username_len</p></td>
 270 <td class="parameter_description"><p>The length of <em class="parameter"><code>username</code></em>
 271 </p></td>
 272 <td class="parameter_annotations"> </td>
 273 </tr>
 274 <tr>
 275 <td class="parameter_name"><p>password</p></td>
 276 <td class="parameter_description"><p>The password associated with that username. This argument is a
 277 pointer to a byte array that must be set by the validater function.</p></td>
 278 <td class="parameter_annotations"> </td>
 279 </tr>
 280 <tr>
 281 <td class="parameter_name"><p>password_len</p></td>
 282 <td class="parameter_description"><p>The length of <em class="parameter"><code>password</code></em>
 283 which must also be set by the
 284 validater function.</p></td>
 285 <td class="parameter_annotations"> </td>
 286 </tr>
 287 <tr>
 288 <td class="parameter_name"><p>user_data</p></td>
 289 <td class="parameter_description"><p>Data to give the function</p></td>
 290 <td class="parameter_annotations"> </td>
 291 </tr>
 292 </tbody>
 293 </table></div>
 294 </div>
 295 <div class="refsect3">
 296 <a name="StunMessageIntegrityValidate.returns"></a><h4>Returns</h4>
 297 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the authentication was successful,
 298 <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the authentication failed</p>
 299 </div>
 300 </div>
 301 <hr>
 302 <div class="refsect2">
 303 <a name="StunDebugHandler"></a><h3>StunDebugHandler ()</h3>
 304 <pre class="programlisting"><span class="returnvalue">void</span>
 305 <span class="c_punctuation">(</span>*StunDebugHandler<span class="c_punctuation">)</span> (<em class="parameter"><code>const <span class="type">char</span> *format</code></em>,
 306                      <em class="parameter"><code><span class="type">va_list</span> ap</code></em>);</pre>
 307 <p>Callback for a debug message from the STUN code.</p>
 308 <div class="refsect3">
 309 <a name="StunDebugHandler.parameters"></a><h4>Parameters</h4>
 310 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 311 <colgroup>
 312 <col width="150px" class="parameters_name">
 313 <col class="parameters_description">
 314 <col width="200px" class="parameters_annotations">
 315 </colgroup>
 316 <tbody>
 317 <tr>
 318 <td class="parameter_name"><p>format</p></td>
 319 <td class="parameter_description"><p>printf()-style debug message format string</p></td>
 320 <td class="parameter_annotations"> </td>
 321 </tr>
 322 <tr>
 323 <td class="parameter_name"><p>ap</p></td>
 324 <td class="parameter_description"><p>Parameters to substitute into message placeholders</p></td>
 325 <td class="parameter_annotations"> </td>
 326 </tr>
 327 </tbody>
 328 </table></div>
 329 </div>
 330 </div>
 331 <hr>
 332 <div class="refsect2">
 333 <a name="stun-agent-init"></a><h3>stun_agent_init ()</h3>
 334 <pre class="programlisting"><span class="returnvalue">void</span>
 335 stun_agent_init (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 336                  <em class="parameter"><code>const <span class="type">uint16_t</span> *known_attributes</code></em>,
 337                  <em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunCompatibility" title="enum StunCompatibility"><span class="type">StunCompatibility</span></a> compatibility</code></em>,
 338                  <em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgentUsageFlags" title="enum StunAgentUsageFlags"><span class="type">StunAgentUsageFlags</span></a> usage_flags</code></em>);</pre>
 339 <p>This function must be called to initialize an agent before it is being used.</p>
 340 <div class="note">
 341 <p>
 342     The <em class="parameter"><code>known_attributes</code></em> data must exist in memory as long as the <em class="parameter"><code>agent</code></em> is used
 343     </p>
 344 <p>
 345     If the <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-SHORT-TERM-CREDENTIALS:CAPS"><span class="type">STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS</span></a> and
 346     <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-LONG-TERM-CREDENTIALS:CAPS"><span class="type">STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS</span></a> usage flags are not set, then the
 347     agent will default in using the short term credentials mechanism
 348     </p>
 349 <p>
 350     The <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-USE-FINGERPRINT:CAPS"><span class="type">STUN_AGENT_USAGE_USE_FINGERPRINT</span></a> and <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-ADD-SOFTWARE:CAPS"><span class="type">STUN_AGENT_USAGE_ADD_SOFTWARE</span></a>
 351     usage flags are only valid if the <a class="link" href="libnice-StunAgent.html#STUN-COMPATIBILITY-RFC5389:CAPS"><span class="type">STUN_COMPATIBILITY_RFC5389</span></a> or
 352     <a class="link" href="libnice-StunAgent.html#STUN-COMPATIBILITY-MSICE2:CAPS"><span class="type">STUN_COMPATIBILITY_MSICE2</span></a> <em class="parameter"><code>compatibility</code></em> is used
 353     </p>
 354 </div>
 355 <div class="refsect3">
 356 <a name="stun-agent-init.parameters"></a><h4>Parameters</h4>
 357 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 358 <colgroup>
 359 <col width="150px" class="parameters_name">
 360 <col class="parameters_description">
 361 <col width="200px" class="parameters_annotations">
 362 </colgroup>
 363 <tbody>
 364 <tr>
 365 <td class="parameter_name"><p>agent</p></td>
 366 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> to initialize</p></td>
 367 <td class="parameter_annotations"> </td>
 368 </tr>
 369 <tr>
 370 <td class="parameter_name"><p>known_attributes</p></td>
 371 <td class="parameter_description"><p>An array of <span class="type">uint16_t</span> specifying which attributes should
 372 be known by the agent. Any STUN message received that contains a mandatory
 373 attribute that is not in this array will yield a
 374 <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-UNKNOWN-REQUEST-ATTRIBUTE:CAPS"><span class="type">STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE</span></a> or a
 375 <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-UNKNOWN-ATTRIBUTE:CAPS"><span class="type">STUN_VALIDATION_UNKNOWN_ATTRIBUTE</span></a> error when calling <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a></p></td>
 376 <td class="parameter_annotations"> </td>
 377 </tr>
 378 <tr>
 379 <td class="parameter_name"><p>compatibility</p></td>
 380 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunCompatibility" title="enum StunCompatibility"><span class="type">StunCompatibility</span></a> to use for this agent. This will affect
 381 how the agent builds and validates the STUN messages</p></td>
 382 <td class="parameter_annotations"> </td>
 383 </tr>
 384 <tr>
 385 <td class="parameter_name"><p>usage_flags</p></td>
 386 <td class="parameter_description"><p>A bitflag using <a class="link" href="libnice-StunAgent.html#StunAgentUsageFlags" title="enum StunAgentUsageFlags"><span class="type">StunAgentUsageFlags</span></a> values to define which
 387 STUN usages the agent should use.</p></td>
 388 <td class="parameter_annotations"> </td>
 389 </tr>
 390 </tbody>
 391 </table></div>
 392 </div>
 393 </div>
 394 <hr>
 395 <div class="refsect2">
 396 <a name="stun-agent-validate"></a><h3>stun_agent_validate ()</h3>
 397 <pre class="programlisting"><a class="link" href="libnice-StunAgent.html#StunValidationStatus" title="enum StunValidationStatus"><span class="returnvalue">StunValidationStatus</span></a>
 398 stun_agent_validate (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 399                      <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 400                      <em class="parameter"><code>const <span class="type">uint8_t</span> *buffer</code></em>,
 401                      <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 402                      <em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunMessageIntegrityValidate" title="StunMessageIntegrityValidate ()"><span class="type">StunMessageIntegrityValidate</span></a> validater</code></em>,
 403                      <em class="parameter"><code><span class="type">void</span> *validater_data</code></em>);</pre>
 404 <p>This function is used to validate an inbound STUN message and transform its
 405 data buffer into a <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a>. It will take care of various validation
 406 algorithms to make sure that the STUN message is valid and correctly
 407 authenticated.</p>
 408 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-default-validater" title="stun_agent_default_validater ()"><code class="function">stun_agent_default_validater()</code></a> </p>
 409 <div class="refsect3">
 410 <a name="stun-agent-validate.parameters"></a><h4>Parameters</h4>
 411 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 412 <colgroup>
 413 <col width="150px" class="parameters_name">
 414 <col class="parameters_description">
 415 <col width="200px" class="parameters_annotations">
 416 </colgroup>
 417 <tbody>
 418 <tr>
 419 <td class="parameter_name"><p>agent</p></td>
 420 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 421 <td class="parameter_annotations"> </td>
 422 </tr>
 423 <tr>
 424 <td class="parameter_name"><p>msg</p></td>
 425 <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>
 426 <td class="parameter_annotations"> </td>
 427 </tr>
 428 <tr>
 429 <td class="parameter_name"><p>buffer</p></td>
 430 <td class="parameter_description"><p>The data buffer of the STUN message</p></td>
 431 <td class="parameter_annotations"> </td>
 432 </tr>
 433 <tr>
 434 <td class="parameter_name"><p>buffer_len</p></td>
 435 <td class="parameter_description"><p>The length of <em class="parameter"><code>buffer</code></em>
 436 </p></td>
 437 <td class="parameter_annotations"> </td>
 438 </tr>
 439 <tr>
 440 <td class="parameter_name"><p>validater</p></td>
 441 <td class="parameter_description"><p>A <a class="link" href="libnice-StunAgent.html#StunMessageIntegrityValidate" title="StunMessageIntegrityValidate ()"><span class="type">StunMessageIntegrityValidate</span></a> function callback that will
 442 be called if the agent needs to validate a MESSAGE-INTEGRITY attribute. It
 443 will only be called if the agent finds a message that needs authentication
 444 and a USERNAME is present in the STUN message, but no password is known.
 445 The validater will not be called if the <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-IGNORE-CREDENTIALS:CAPS"><span class="type">STUN_AGENT_USAGE_IGNORE_CREDENTIALS</span></a>
 446 usage flag is set on the agent, and it will always be called if the
 447 <a class="link" href="libnice-StunAgent.html#STUN-AGENT-USAGE-FORCE-VALIDATER:CAPS"><span class="type">STUN_AGENT_USAGE_FORCE_VALIDATER</span></a> usage flag is set on the agent.</p></td>
 448 <td class="parameter_annotations"> </td>
 449 </tr>
 450 <tr>
 451 <td class="parameter_name"><p>validater_data</p></td>
 452 <td class="parameter_description"><p>A user data to give to the <em class="parameter"><code>validater</code></em>
 453 callback when it gets
 454 called.</p></td>
 455 <td class="parameter_annotations"> </td>
 456 </tr>
 457 </tbody>
 458 </table></div>
 459 </div>
 460 <div class="refsect3">
 461 <a name="stun-agent-validate.returns"></a><h4>Returns</h4>
 462 <p> A <a class="link" href="libnice-StunAgent.html#StunValidationStatus" title="enum StunValidationStatus"><span class="type">StunValidationStatus</span></a></p>
 463 <div class="note"><p>
 464 if the return value is different from <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-NOT-STUN:CAPS"><span class="type">STUN_VALIDATION_NOT_STUN</span></a> or
 465 <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-INCOMPLETE-STUN:CAPS"><span class="type">STUN_VALIDATION_INCOMPLETE_STUN</span></a>, then the <em class="parameter"><code>msg</code></em> argument will contain a valid
 466 STUN message that can be used.
 467 This means that you can use the <em class="parameter"><code>msg</code></em> variable as the <em class="parameter"><code>request</code></em> argument to
 468 functions like <a class="link" href="libnice-StunAgent.html#stun-agent-init-error" title="stun_agent_init_error ()"><code class="function">stun_agent_init_error()</code></a> or
 469 <a class="link" href="libnice-StunAgent.html#stun-agent-build-unknown-attributes-error" title="stun_agent_build_unknown_attributes_error ()"><code class="function">stun_agent_build_unknown_attributes_error()</code></a>.
 470 If the return value is <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-BAD-REQUEST:CAPS"><span class="type">STUN_VALIDATION_BAD_REQUEST</span></a>,
 471 <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-UNAUTHORIZED:CAPS"><span class="type">STUN_VALIDATION_UNAUTHORIZED</span></a> or <a class="link" href="libnice-StunAgent.html#STUN-VALIDATION-UNAUTHORIZED-BAD-REQUEST:CAPS"><span class="type">STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST</span></a>
 472 then the <em class="parameter"><code>key</code></em> in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> will not be set, so that error responses
 473 will not have a MESSAGE-INTEGRITY attribute.
 474 </p></div>
 475 </div>
 476 </div>
 477 <hr>
 478 <div class="refsect2">
 479 <a name="stun-agent-default-validater"></a><h3>stun_agent_default_validater ()</h3>
 480 <pre class="programlisting"><span class="returnvalue">bool</span>
 481 stun_agent_default_validater (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 482                               <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *message</code></em>,
 483                               <em class="parameter"><code><span class="type">uint8_t</span> *username</code></em>,
 484                               <em class="parameter"><code><span class="type">uint16_t</span> username_len</code></em>,
 485                               <em class="parameter"><code><span class="type">uint8_t</span> **password</code></em>,
 486                               <em class="parameter"><code><span class="type">size_t</span> *password_len</code></em>,
 487                               <em class="parameter"><code><span class="type">void</span> *user_data</code></em>);</pre>
 488 <p>This is a helper function to be used with <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a>. If no
 489 complicated processing of the username needs to be done, this function can
 490 be used with <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a> to quickly and easily match the username
 491 of a STUN message with its password. Its <em class="parameter"><code>user_data</code></em>
 492  argument must be an array
 493 of <a class="link" href="libnice-StunAgent.html#StunDefaultValidaterData" title="StunDefaultValidaterData"><span class="type">StunDefaultValidaterData</span></a> which will allow us to map a username to a
 494 password</p>
 495 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a> </p>
 496 <div class="refsect3">
 497 <a name="stun-agent-default-validater.parameters"></a><h4>Parameters</h4>
 498 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 499 <colgroup>
 500 <col width="150px" class="parameters_name">
 501 <col class="parameters_description">
 502 <col width="200px" class="parameters_annotations">
 503 </colgroup>
 504 <tbody>
 505 <tr>
 506 <td class="parameter_name"><p>agent</p></td>
 507 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 508 <td class="parameter_annotations"> </td>
 509 </tr>
 510 <tr>
 511 <td class="parameter_name"><p>message</p></td>
 512 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> being validated</p></td>
 513 <td class="parameter_annotations"> </td>
 514 </tr>
 515 <tr>
 516 <td class="parameter_name"><p>username</p></td>
 517 <td class="parameter_description"><p>The username found in the <em class="parameter"><code>message</code></em>
 518 </p></td>
 519 <td class="parameter_annotations"> </td>
 520 </tr>
 521 <tr>
 522 <td class="parameter_name"><p>username_len</p></td>
 523 <td class="parameter_description"><p>The length of <em class="parameter"><code>username</code></em>
 524 </p></td>
 525 <td class="parameter_annotations"> </td>
 526 </tr>
 527 <tr>
 528 <td class="parameter_name"><p>password</p></td>
 529 <td class="parameter_description"><p>The password associated with that username. This argument is a
 530 pointer to a byte array that must be set by the validater function.</p></td>
 531 <td class="parameter_annotations"> </td>
 532 </tr>
 533 <tr>
 534 <td class="parameter_name"><p>password_len</p></td>
 535 <td class="parameter_description"><p>The length of <em class="parameter"><code>password</code></em>
 536 which must also be set by the
 537 validater function.</p></td>
 538 <td class="parameter_annotations"> </td>
 539 </tr>
 540 <tr>
 541 <td class="parameter_name"><p>user_data</p></td>
 542 <td class="parameter_description"><p>This must be an array of <a class="link" href="libnice-StunAgent.html#StunDefaultValidaterData" title="StunDefaultValidaterData"><span class="type">StunDefaultValidaterData</span></a> structures.
 543 The last element in the array must have a username set to NULL</p></td>
 544 <td class="parameter_annotations"> </td>
 545 </tr>
 546 </tbody>
 547 </table></div>
 548 </div>
 549 <div class="refsect3">
 550 <a name="stun-agent-default-validater.returns"></a><h4>Returns</h4>
 551 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the authentication was successful,
 552 <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the authentication failed</p>
 553 </div>
 554 </div>
 555 <hr>
 556 <div class="refsect2">
 557 <a name="stun-agent-init-request"></a><h3>stun_agent_init_request ()</h3>
 558 <pre class="programlisting"><span class="returnvalue">bool</span>
 559 stun_agent_init_request (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 560                          <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 561                          <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 562                          <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 563                          <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMethod" title="enum StunMethod"><span class="type">StunMethod</span></a> m</code></em>);</pre>
 564 <p>Creates a new STUN message of class <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a> and with the method <em class="parameter"><code>m</code></em>
 565 </p>
 566 <div class="refsect3">
 567 <a name="stun-agent-init-request.parameters"></a><h4>Parameters</h4>
 568 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 569 <colgroup>
 570 <col width="150px" class="parameters_name">
 571 <col class="parameters_description">
 572 <col width="200px" class="parameters_annotations">
 573 </colgroup>
 574 <tbody>
 575 <tr>
 576 <td class="parameter_name"><p>agent</p></td>
 577 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 578 <td class="parameter_annotations"> </td>
 579 </tr>
 580 <tr>
 581 <td class="parameter_name"><p>msg</p></td>
 582 <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>
 583 <td class="parameter_annotations"> </td>
 584 </tr>
 585 <tr>
 586 <td class="parameter_name"><p>buffer</p></td>
 587 <td class="parameter_description"><p>The buffer to use in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 588 <td class="parameter_annotations"> </td>
 589 </tr>
 590 <tr>
 591 <td class="parameter_name"><p>buffer_len</p></td>
 592 <td class="parameter_description"><p>The length of the buffer</p></td>
 593 <td class="parameter_annotations"> </td>
 594 </tr>
 595 <tr>
 596 <td class="parameter_name"><p>m</p></td>
 597 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMethod" title="enum StunMethod"><span class="type">StunMethod</span></a> of the request</p></td>
 598 <td class="parameter_annotations"> </td>
 599 </tr>
 600 </tbody>
 601 </table></div>
 602 </div>
 603 <div class="refsect3">
 604 <a name="stun-agent-init-request.returns"></a><h4>Returns</h4>
 605 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the message was initialized correctly, <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p>
 606 </div>
 607 </div>
 608 <hr>
 609 <div class="refsect2">
 610 <a name="stun-agent-init-indication"></a><h3>stun_agent_init_indication ()</h3>
 611 <pre class="programlisting"><span class="returnvalue">bool</span>
 612 stun_agent_init_indication (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 613                             <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 614                             <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 615                             <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 616                             <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMethod" title="enum StunMethod"><span class="type">StunMethod</span></a> m</code></em>);</pre>
 617 <p>Creates a new STUN message of class <a class="link" href="libnice-StunMessage.html#STUN-INDICATION:CAPS"><span class="type">STUN_INDICATION</span></a> and with the method <em class="parameter"><code>m</code></em>
 618 </p>
 619 <div class="refsect3">
 620 <a name="stun-agent-init-indication.parameters"></a><h4>Parameters</h4>
 621 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 622 <colgroup>
 623 <col width="150px" class="parameters_name">
 624 <col class="parameters_description">
 625 <col width="200px" class="parameters_annotations">
 626 </colgroup>
 627 <tbody>
 628 <tr>
 629 <td class="parameter_name"><p>agent</p></td>
 630 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 631 <td class="parameter_annotations"> </td>
 632 </tr>
 633 <tr>
 634 <td class="parameter_name"><p>msg</p></td>
 635 <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>
 636 <td class="parameter_annotations"> </td>
 637 </tr>
 638 <tr>
 639 <td class="parameter_name"><p>buffer</p></td>
 640 <td class="parameter_description"><p>The buffer to use in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 641 <td class="parameter_annotations"> </td>
 642 </tr>
 643 <tr>
 644 <td class="parameter_name"><p>buffer_len</p></td>
 645 <td class="parameter_description"><p>The length of the buffer</p></td>
 646 <td class="parameter_annotations"> </td>
 647 </tr>
 648 <tr>
 649 <td class="parameter_name"><p>m</p></td>
 650 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMethod" title="enum StunMethod"><span class="type">StunMethod</span></a> of the indication</p></td>
 651 <td class="parameter_annotations"> </td>
 652 </tr>
 653 </tbody>
 654 </table></div>
 655 </div>
 656 <div class="refsect3">
 657 <a name="stun-agent-init-indication.returns"></a><h4>Returns</h4>
 658 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the message was initialized correctly, <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p>
 659 </div>
 660 </div>
 661 <hr>
 662 <div class="refsect2">
 663 <a name="stun-agent-init-response"></a><h3>stun_agent_init_response ()</h3>
 664 <pre class="programlisting"><span class="returnvalue">bool</span>
 665 stun_agent_init_response (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 666                           <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 667                           <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 668                           <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 669                           <em class="parameter"><code>const <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *request</code></em>);</pre>
 670 <p>Creates a new STUN message of class <a class="link" href="libnice-StunMessage.html#STUN-RESPONSE:CAPS"><span class="type">STUN_RESPONSE</span></a> and with the same method
 671 and transaction ID as the message <em class="parameter"><code>request</code></em>
 672 . This will also copy the pointer
 673 to the key that was used to authenticate the request, so you won't need to
 674 specify the key with <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a></p>
 675 <div class="refsect3">
 676 <a name="stun-agent-init-response.parameters"></a><h4>Parameters</h4>
 677 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 678 <colgroup>
 679 <col width="150px" class="parameters_name">
 680 <col class="parameters_description">
 681 <col width="200px" class="parameters_annotations">
 682 </colgroup>
 683 <tbody>
 684 <tr>
 685 <td class="parameter_name"><p>agent</p></td>
 686 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 687 <td class="parameter_annotations"> </td>
 688 </tr>
 689 <tr>
 690 <td class="parameter_name"><p>msg</p></td>
 691 <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>
 692 <td class="parameter_annotations"> </td>
 693 </tr>
 694 <tr>
 695 <td class="parameter_name"><p>buffer</p></td>
 696 <td class="parameter_description"><p>The buffer to use in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 697 <td class="parameter_annotations"> </td>
 698 </tr>
 699 <tr>
 700 <td class="parameter_name"><p>buffer_len</p></td>
 701 <td class="parameter_description"><p>The length of the buffer</p></td>
 702 <td class="parameter_annotations"> </td>
 703 </tr>
 704 <tr>
 705 <td class="parameter_name"><p>request</p></td>
 706 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> of class <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a> that this response is for</p></td>
 707 <td class="parameter_annotations"> </td>
 708 </tr>
 709 </tbody>
 710 </table></div>
 711 </div>
 712 <div class="refsect3">
 713 <a name="stun-agent-init-response.returns"></a><h4>Returns</h4>
 714 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the message was initialized correctly, <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p>
 715 </div>
 716 </div>
 717 <hr>
 718 <div class="refsect2">
 719 <a name="stun-agent-init-error"></a><h3>stun_agent_init_error ()</h3>
 720 <pre class="programlisting"><span class="returnvalue">bool</span>
 721 stun_agent_init_error (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 722                        <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 723                        <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 724                        <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 725                        <em class="parameter"><code>const <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *request</code></em>,
 726                        <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunError" title="enum StunError"><span class="type">StunError</span></a> err</code></em>);</pre>
 727 <p>Creates a new STUN message of class <a class="link" href="libnice-StunMessage.html#STUN-ERROR:CAPS"><span class="type">STUN_ERROR</span></a> and with the same method
 728 and transaction ID as the message <em class="parameter"><code>request</code></em>
 729 . This will also copy the pointer
 730 to the key that was used to authenticate the request (if authenticated),
 731 so you won't need to specify the key with <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a>.
 732 It will then add the ERROR-CODE attribute with code <em class="parameter"><code>err</code></em>
 733  and the associated
 734 string.</p>
 735 <div class="refsect3">
 736 <a name="stun-agent-init-error.parameters"></a><h4>Parameters</h4>
 737 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 738 <colgroup>
 739 <col width="150px" class="parameters_name">
 740 <col class="parameters_description">
 741 <col width="200px" class="parameters_annotations">
 742 </colgroup>
 743 <tbody>
 744 <tr>
 745 <td class="parameter_name"><p>agent</p></td>
 746 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 747 <td class="parameter_annotations"> </td>
 748 </tr>
 749 <tr>
 750 <td class="parameter_name"><p>msg</p></td>
 751 <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>
 752 <td class="parameter_annotations"> </td>
 753 </tr>
 754 <tr>
 755 <td class="parameter_name"><p>buffer</p></td>
 756 <td class="parameter_description"><p>The buffer to use in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 757 <td class="parameter_annotations"> </td>
 758 </tr>
 759 <tr>
 760 <td class="parameter_name"><p>buffer_len</p></td>
 761 <td class="parameter_description"><p>The length of the buffer</p></td>
 762 <td class="parameter_annotations"> </td>
 763 </tr>
 764 <tr>
 765 <td class="parameter_name"><p>request</p></td>
 766 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> of class <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a> that this error response
 767 is for</p></td>
 768 <td class="parameter_annotations"> </td>
 769 </tr>
 770 <tr>
 771 <td class="parameter_name"><p>err</p></td>
 772 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunError" title="enum StunError"><span class="type">StunError</span></a> to put in the ERROR-CODE attribute of the error response</p></td>
 773 <td class="parameter_annotations"> </td>
 774 </tr>
 775 </tbody>
 776 </table></div>
 777 </div>
 778 <div class="refsect3">
 779 <a name="stun-agent-init-error.returns"></a><h4>Returns</h4>
 780 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the message was initialized correctly, <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p>
 781 </div>
 782 </div>
 783 <hr>
 784 <div class="refsect2">
 785 <a name="stun-agent-build-unknown-attributes-error"></a><h3>stun_agent_build_unknown_attributes_error ()</h3>
 786 <pre class="programlisting"><span class="returnvalue">size_t</span>
 787 stun_agent_build_unknown_attributes_error
 788                                (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 789                                 <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 790                                 <em class="parameter"><code><span class="type">uint8_t</span> *buffer</code></em>,
 791                                 <em class="parameter"><code><span class="type">size_t</span> buffer_len</code></em>,
 792                                 <em class="parameter"><code>const <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *request</code></em>);</pre>
 793 <p>Creates a new STUN message of class <a class="link" href="libnice-StunMessage.html#STUN-ERROR:CAPS"><span class="type">STUN_ERROR</span></a> and with the same method
 794 and transaction ID as the message <em class="parameter"><code>request</code></em>
 795 .  It will then add the ERROR-CODE
 796 attribute with code <a class="link" href="libnice-StunMessage.html#STUN-ERROR-UNKNOWN-ATTRIBUTE:CAPS"><span class="type">STUN_ERROR_UNKNOWN_ATTRIBUTE</span></a> and add all the unknown
 797 mandatory attributes from the <em class="parameter"><code>request</code></em>
 798  STUN message in the
 799 <a class="link" href="libnice-StunMessage.html#STUN-ATTRIBUTE-UNKNOWN-ATTRIBUTES:CAPS"><span class="type">STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES</span></a> attribute, it will then finish the message
 800 by calling <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a></p>
 801 <div class="refsect3">
 802 <a name="stun-agent-build-unknown-attributes-error.parameters"></a><h4>Parameters</h4>
 803 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 804 <colgroup>
 805 <col width="150px" class="parameters_name">
 806 <col class="parameters_description">
 807 <col width="200px" class="parameters_annotations">
 808 </colgroup>
 809 <tbody>
 810 <tr>
 811 <td class="parameter_name"><p>agent</p></td>
 812 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 813 <td class="parameter_annotations"> </td>
 814 </tr>
 815 <tr>
 816 <td class="parameter_name"><p>msg</p></td>
 817 <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>
 818 <td class="parameter_annotations"> </td>
 819 </tr>
 820 <tr>
 821 <td class="parameter_name"><p>buffer</p></td>
 822 <td class="parameter_description"><p>The buffer to use in the <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p></td>
 823 <td class="parameter_annotations"> </td>
 824 </tr>
 825 <tr>
 826 <td class="parameter_name"><p>buffer_len</p></td>
 827 <td class="parameter_description"><p>The length of the buffer</p></td>
 828 <td class="parameter_annotations"> </td>
 829 </tr>
 830 <tr>
 831 <td class="parameter_name"><p>request</p></td>
 832 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> of class <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a> that this response is for</p></td>
 833 <td class="parameter_annotations"> </td>
 834 </tr>
 835 </tbody>
 836 </table></div>
 837 </div>
 838 <div class="refsect3">
 839 <a name="stun-agent-build-unknown-attributes-error.returns"></a><h4>Returns</h4>
 840 <p> The size of the message built</p>
 841 </div>
 842 </div>
 843 <hr>
 844 <div class="refsect2">
 845 <a name="stun-agent-finish-message"></a><h3>stun_agent_finish_message ()</h3>
 846 <pre class="programlisting"><span class="returnvalue">size_t</span>
 847 stun_agent_finish_message (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 848                            <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> *msg</code></em>,
 849                            <em class="parameter"><code>const <span class="type">uint8_t</span> *key</code></em>,
 850                            <em class="parameter"><code><span class="type">size_t</span> key_len</code></em>);</pre>
 851 <p>This function will 'finish' a message and make it ready to be sent. It will
 852 add the MESSAGE-INTEGRITY and FINGERPRINT attributes if necessary. If the
 853 STUN message has a <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a> class, it will save the transaction id of
 854 the message in the agent for future matching of the response.</p>
 855 <p>See also: <a class="link" href="libnice-StunAgent.html#stun-agent-forget-transaction" title="stun_agent_forget_transaction ()"><code class="function">stun_agent_forget_transaction()</code></a></p>
 856 <div class="refsect3">
 857 <a name="stun-agent-finish-message.parameters"></a><h4>Parameters</h4>
 858 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 859 <colgroup>
 860 <col width="150px" class="parameters_name">
 861 <col class="parameters_description">
 862 <col width="200px" class="parameters_annotations">
 863 </colgroup>
 864 <tbody>
 865 <tr>
 866 <td class="parameter_name"><p>agent</p></td>
 867 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 868 <td class="parameter_annotations"> </td>
 869 </tr>
 870 <tr>
 871 <td class="parameter_name"><p>msg</p></td>
 872 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a> to finish</p></td>
 873 <td class="parameter_annotations"> </td>
 874 </tr>
 875 <tr>
 876 <td class="parameter_name"><p>key</p></td>
 877 <td class="parameter_description"><p>The key to use for the MESSAGE-INTEGRITY attribute</p></td>
 878 <td class="parameter_annotations"> </td>
 879 </tr>
 880 <tr>
 881 <td class="parameter_name"><p>key_len</p></td>
 882 <td class="parameter_description"><p>The length of the <em class="parameter"><code>key</code></em>
 883 </p></td>
 884 <td class="parameter_annotations"> </td>
 885 </tr>
 886 </tbody>
 887 </table></div>
 888 </div>
 889 <div class="refsect3">
 890 <a name="stun-agent-finish-message.returns"></a><h4>Returns</h4>
 891 <p> The final size of the message built or 0 if an error occured</p>
 892 <div class="note">
 893 <p>
 894 The return value must always be checked. a value of 0 means the either
 895 the buffer's size is too small to contain the finishing attributes
 896 (MESSAGE-INTEGRITY, FINGERPRINT), or that there is no more free slots
 897 for saving the sent id in the agent's state.
 898 </p>
 899 <p>
 900 Everytime <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a> is called for a <a class="link" href="libnice-StunMessage.html#STUN-REQUEST:CAPS"><span class="type">STUN_REQUEST</span></a>
 901 message, you must make sure to call <a class="link" href="libnice-StunAgent.html#stun-agent-forget-transaction" title="stun_agent_forget_transaction ()"><code class="function">stun_agent_forget_transaction()</code></a> in
 902 case the response times out and is never received. This is to avoid
 903 filling up the <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a>'s sent ids state preventing any further
 904 use of the <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a>
 905 </p>
 906 </div>
 907 </div>
 908 </div>
 909 <hr>
 910 <div class="refsect2">
 911 <a name="stun-agent-forget-transaction"></a><h3>stun_agent_forget_transaction ()</h3>
 912 <pre class="programlisting"><span class="returnvalue">bool</span>
 913 stun_agent_forget_transaction (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 914                                <em class="parameter"><code><a class="link" href="libnice-StunMessage.html#StunTransactionId" title="StunTransactionId"><span class="type">StunTransactionId</span></a> id</code></em>);</pre>
 915 <p>This function is used to make the <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> forget about a previously
 916 created transaction.</p>
 917 <p>
 918 This function should be called when a STUN request was previously
 919 created with <a class="link" href="libnice-StunAgent.html#stun-agent-finish-message" title="stun_agent_finish_message ()"><code class="function">stun_agent_finish_message()</code></a> and for which no response was ever
 920 received (timed out). The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> keeps a list of the sent transactions
 921 in order to validate the responses received. If the response is never received
 922 this will allow the <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> to forget about the timed out transaction and
 923 free its slot for future transactions.
 924 </p>
 925 <div class="refsect3">
 926 <a name="stun-agent-forget-transaction.parameters"></a><h4>Parameters</h4>
 927 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 928 <colgroup>
 929 <col width="150px" class="parameters_name">
 930 <col class="parameters_description">
 931 <col width="200px" class="parameters_annotations">
 932 </colgroup>
 933 <tbody>
 934 <tr>
 935 <td class="parameter_name"><p>agent</p></td>
 936 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 937 <td class="parameter_annotations"> </td>
 938 </tr>
 939 <tr>
 940 <td class="parameter_name"><p>id</p></td>
 941 <td class="parameter_description"><p>The <a class="link" href="libnice-StunMessage.html#StunTransactionId" title="StunTransactionId"><span class="type">StunTransactionId</span></a> of the transaction to forget</p></td>
 942 <td class="parameter_annotations"> </td>
 943 </tr>
 944 </tbody>
 945 </table></div>
 946 </div>
 947 <div class="refsect3">
 948 <a name="stun-agent-forget-transaction.returns"></a><h4>Returns</h4>
 949 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the transaction was found, <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p>
 950 </div>
 951 <p class="since">Since: <a class="link" href="ix04.html#api-index-0.0.6">0.0.6</a></p>
 952 </div>
 953 <hr>
 954 <div class="refsect2">
 955 <a name="stun-agent-set-software"></a><h3>stun_agent_set_software ()</h3>
 956 <pre class="programlisting"><span class="returnvalue">void</span>
 957 stun_agent_set_software (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> *agent</code></em>,
 958                          <em class="parameter"><code>const <span class="type">char</span> *software</code></em>);</pre>
 959 <p>This function will set the value of the SOFTWARE attribute to be added to
 960 STUN requests, responses and error responses.</p>
 961 <p>
 962 Calling this function will automatically enable the addition of the SOFTWARE
 963 attribute for RFC5389 and MSICE2 compatibility modes.
 964
 965 </p>
 966 <div class="note">
 967 <p>
 968        The <em class="parameter"><code>software</code></em> argument must be in UTF-8 encoding and only the first
 969        128 characters will be sent.
 970      </p>
 971 <p>
 972        The value of the <em class="parameter"><code>software</code></em> argument must stay valid throughout the life of
 973        the StunAgent's life. Do not free its content.
 974      </p>
 975 </div>
 976 <div class="refsect3">
 977 <a name="stun-agent-set-software.parameters"></a><h4>Parameters</h4>
 978 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 979 <colgroup>
 980 <col width="150px" class="parameters_name">
 981 <col class="parameters_description">
 982 <col width="200px" class="parameters_annotations">
 983 </colgroup>
 984 <tbody>
 985 <tr>
 986 <td class="parameter_name"><p>agent</p></td>
 987 <td class="parameter_description"><p>The <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p></td>
 988 <td class="parameter_annotations"> </td>
 989 </tr>
 990 <tr>
 991 <td class="parameter_name"><p>software</p></td>
 992 <td class="parameter_description"><p>The value of the SOFTWARE attribute to add.</p></td>
 993 <td class="parameter_annotations"> </td>
 994 </tr>
 995 </tbody>
 996 </table></div>
 997 </div>
 998 <p class="since">Since: <a class="link" href="ix07.html#api-index-0.0.10">0.0.10</a></p>
 999 </div>
1000 <hr>
1001 <div class="refsect2">
1002 <a name="stun-debug-enable"></a><h3>stun_debug_enable ()</h3>
1003 <pre class="programlisting"><span class="returnvalue">void</span>
1004 stun_debug_enable (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1005 <p>Enable debug messages to stderr</p>
1006 </div>
1007 <hr>
1008 <div class="refsect2">
1009 <a name="stun-debug-disable"></a><h3>stun_debug_disable ()</h3>
1010 <pre class="programlisting"><span class="returnvalue">void</span>
1011 stun_debug_disable (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1012 <p>Disable debug messages to stderr</p>
1013 </div>
1014 <hr>
1015 <div class="refsect2">
1016 <a name="stun-set-debug-handler"></a><h3>stun_set_debug_handler ()</h3>
1017 <pre class="programlisting"><span class="returnvalue">void</span>
1018 stun_set_debug_handler (<em class="parameter"><code><a class="link" href="libnice-StunAgent.html#StunDebugHandler" title="StunDebugHandler ()"><span class="type">StunDebugHandler</span></a> handler</code></em>);</pre>
1019 <p>Set a callback function to be invoked for each debug message from the STUN
1020 code. The callback will only be invoked if STUN debugging is enabled using
1021 <a class="link" href="libnice-StunAgent.html#stun-debug-enable" title="stun_debug_enable ()"><code class="function">stun_debug_enable()</code></a>.</p>
1022 <p>The default callback prints the formatted debug message to stderr.</p>
1023 <div class="refsect3">
1024 <a name="stun-set-debug-handler.parameters"></a><h4>Parameters</h4>
1025 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1026 <colgroup>
1027 <col width="150px" class="parameters_name">
1028 <col class="parameters_description">
1029 <col width="200px" class="parameters_annotations">
1030 </colgroup>
1031 <tbody><tr>
1032 <td class="parameter_name"><p>handler</p></td>
1033 <td class="parameter_description"><p>Handler for STUN debug messages, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to use the
1034 default. </p></td>
1035 <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td>
1036 </tr></tbody>
1037 </table></div>
1038 </div>
1039 </div>
1040 </div>
1041 <div class="refsect1">
1042 <a name="libnice-StunAgent.other_details"></a><h2>Types and Values</h2>
1043 <div class="refsect2">
1044 <a name="StunAgent"></a><h3>StunAgent</h3>
1045 <pre class="programlisting">typedef struct stun_agent_t StunAgent;
1046 </pre>
1047 <p>An opaque structure representing the STUN agent.</p>
1048 </div>
1049 <hr>
1050 <div class="refsect2">
1051 <a name="StunCompatibility"></a><h3>enum StunCompatibility</h3>
1052 <p>Enum that specifies the STUN compatibility mode of the <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a></p>
1053 <div class="warning">
1054 <em class="parameter"><code>STUN_COMPATIBILITY_WLM2009</code></em> is deprecated and should not be used
1055 in newly-written code. It is kept for compatibility reasons and represents
1056 the same compatibility as <em class="parameter"><code>STUN_COMPATIBILITY_MSICE2</code></em>.</div>
1057 <div class="refsect3">
1058 <a name="StunCompatibility.members"></a><h4>Members</h4>
1059 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1060 <colgroup>
1061 <col width="300px" class="enum_members_name">
1062 <col class="enum_members_description">
1063 <col width="200px" class="enum_members_annotations">
1064 </colgroup>
1065 <tbody>
1066 <tr>
1067 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-RFC3489:CAPS"></a>STUN_COMPATIBILITY_RFC3489</p></td>
1068 <td class="enum_member_description">
1069 <p>Use the STUN specifications compatible with
1070 RFC 3489</p>
1071 </td>
1072 <td class="enum_member_annotations"> </td>
1073 </tr>
1074 <tr>
1075 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-RFC5389:CAPS"></a>STUN_COMPATIBILITY_RFC5389</p></td>
1076 <td class="enum_member_description">
1077 <p>Use the STUN specifications compatible with
1078 RFC 5389</p>
1079 </td>
1080 <td class="enum_member_annotations"> </td>
1081 </tr>
1082 <tr>
1083 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-MSICE2:CAPS"></a>STUN_COMPATIBILITY_MSICE2</p></td>
1084 <td class="enum_member_description">
1085 <p>Use the STUN specifications compatible with
1086 [MS-ICE2] (a mix between RFC3489 and RFC5389)</p>
1087 </td>
1088 <td class="enum_member_annotations"> </td>
1089 </tr>
1090 <tr>
1091 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-OC2007:CAPS"></a>STUN_COMPATIBILITY_OC2007</p></td>
1092 <td class="enum_member_description">
1093 <p>Use the STUN specifications compatible with
1094 Microsoft Office Communicator 2007 (basically RFC3489 with swapped
1095 REALM and NONCE attribute hex IDs, attributes are not aligned)</p>
1096 </td>
1097 <td class="enum_member_annotations"> </td>
1098 </tr>
1099 <tr>
1100 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-WLM2009:CAPS"></a>STUN_COMPATIBILITY_WLM2009</p></td>
1101 <td class="enum_member_description">
1102 <p>An alias for <em class="parameter"><code>STUN_COMPATIBILITY_MSICE2</code></em>
1103 </p>
1104 </td>
1105 <td class="enum_member_annotations"> </td>
1106 </tr>
1107 <tr>
1108 <td class="enum_member_name"><p><a name="STUN-COMPATIBILITY-LAST:CAPS"></a>STUN_COMPATIBILITY_LAST</p></td>
1109 <td class="enum_member_description">
1110 <p>Dummy last compatibility mode</p>
1111 </td>
1112 <td class="enum_member_annotations"> </td>
1113 </tr>
1114 </tbody>
1115 </table></div>
1116 </div>
1117 </div>
1118 <hr>
1119 <div class="refsect2">
1120 <a name="StunAgentUsageFlags"></a><h3>enum StunAgentUsageFlags</h3>
1121 <p>This enum defines a bitflag usages for a <a class="link" href="libnice-StunAgent.html#StunAgent" title="StunAgent"><span class="type">StunAgent</span></a> and they will define how
1122 the agent should behave, independently of the compatibility mode it uses.</p>
1123 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-init" title="stun_agent_init ()"><code class="function">stun_agent_init()</code></a> </p>
1124 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a> </p>
1125 <div class="refsect3">
1126 <a name="StunAgentUsageFlags.members"></a><h4>Members</h4>
1127 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1128 <colgroup>
1129 <col width="300px" class="enum_members_name">
1130 <col class="enum_members_description">
1131 <col width="200px" class="enum_members_annotations">
1132 </colgroup>
1133 <tbody>
1134 <tr>
1135 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-SHORT-TERM-CREDENTIALS:CAPS"></a>STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS</p></td>
1136 <td class="enum_member_description">
1137 <p>The agent should be using the short
1138 term credentials mechanism for authenticating STUN messages</p>
1139 </td>
1140 <td class="enum_member_annotations"> </td>
1141 </tr>
1142 <tr>
1143 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-LONG-TERM-CREDENTIALS:CAPS"></a>STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS</p></td>
1144 <td class="enum_member_description">
1145 <p>The agent should be using the long
1146 term credentials mechanism for authenticating STUN messages</p>
1147 </td>
1148 <td class="enum_member_annotations"> </td>
1149 </tr>
1150 <tr>
1151 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-USE-FINGERPRINT:CAPS"></a>STUN_AGENT_USAGE_USE_FINGERPRINT</p></td>
1152 <td class="enum_member_description">
1153 <p>The agent should add the FINGERPRINT
1154 attribute to the STUN messages it creates.</p>
1155 </td>
1156 <td class="enum_member_annotations"> </td>
1157 </tr>
1158 <tr>
1159 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-ADD-SOFTWARE:CAPS"></a>STUN_AGENT_USAGE_ADD_SOFTWARE</p></td>
1160 <td class="enum_member_description">
1161 <p>The agent should add the SOFTWARE attribute
1162 to the STUN messages it creates. Calling <a class="link" href="NiceAgent.html#nice-agent-set-software" title="nice_agent_set_software ()"><code class="function">nice_agent_set_software()</code></a> will have
1163 the same effect as enabling this Usage. STUN Indications do not have the
1164 SOFTWARE attributes added to them though. The SOFTWARE attribute is only
1165 added for the RFC5389 and MSICE2 compatibility modes.</p>
1166 </td>
1167 <td class="enum_member_annotations"> </td>
1168 </tr>
1169 <tr>
1170 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-IGNORE-CREDENTIALS:CAPS"></a>STUN_AGENT_USAGE_IGNORE_CREDENTIALS</p></td>
1171 <td class="enum_member_description">
1172 <p>The agent should ignore any credentials
1173 in the STUN messages it receives (the MESSAGE-INTEGRITY attribute
1174 will never be validated by <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a>)</p>
1175 </td>
1176 <td class="enum_member_annotations"> </td>
1177 </tr>
1178 <tr>
1179 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-NO-INDICATION-AUTH:CAPS"></a>STUN_AGENT_USAGE_NO_INDICATION_AUTH</p></td>
1180 <td class="enum_member_description">
1181 <p>The agent should ignore credentials
1182 in the STUN messages it receives if the <a class="link" href="libnice-StunMessage.html#StunClass" title="enum StunClass"><span class="type">StunClass</span></a> of the message is
1183 <a class="link" href="libnice-StunMessage.html#STUN-INDICATION:CAPS"><span class="type">STUN_INDICATION</span></a> (some implementation require <a class="link" href="libnice-StunMessage.html#STUN-INDICATION:CAPS"><span class="type">STUN_INDICATION</span></a> messages to
1184 be authenticated, while others never add a MESSAGE-INTEGRITY attribute to a
1185 <a class="link" href="libnice-StunMessage.html#STUN-INDICATION:CAPS"><span class="type">STUN_INDICATION</span></a> message)</p>
1186 </td>
1187 <td class="enum_member_annotations"> </td>
1188 </tr>
1189 <tr>
1190 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-FORCE-VALIDATER:CAPS"></a>STUN_AGENT_USAGE_FORCE_VALIDATER</p></td>
1191 <td class="enum_member_description">
1192 <p>The agent should always try to validate
1193 the password of a STUN message, even if it already knows what the password
1194 should be (a response to a previously created request). This means that the
1195 <a class="link" href="libnice-StunAgent.html#StunMessageIntegrityValidate" title="StunMessageIntegrityValidate ()"><span class="type">StunMessageIntegrityValidate</span></a> callback will always be called when there is
1196 a MESSAGE-INTEGRITY attribute.</p>
1197 </td>
1198 <td class="enum_member_annotations"> </td>
1199 </tr>
1200 <tr>
1201 <td class="enum_member_name"><p><a name="STUN-AGENT-USAGE-NO-ALIGNED-ATTRIBUTES:CAPS"></a>STUN_AGENT_USAGE_NO_ALIGNED_ATTRIBUTES</p></td>
1202 <td class="enum_member_description">
1203 <p>The agent should not assume STUN
1204 attributes are aligned on 32-bit boundaries when parsing messages and also
1205 do not add padding when creating messages.</p>
1206 </td>
1207 <td class="enum_member_annotations"> </td>
1208 </tr>
1209 </tbody>
1210 </table></div>
1211 </div>
1212 </div>
1213 <hr>
1214 <div class="refsect2">
1215 <a name="StunValidationStatus"></a><h3>enum StunValidationStatus</h3>
1216 <p>This enum is used as the return value of <a class="link" href="libnice-StunAgent.html#stun-agent-validate" title="stun_agent_validate ()"><code class="function">stun_agent_validate()</code></a> and represents
1217 the status result of the validation of a STUN message.</p>
1218 <div class="refsect3">
1219 <a name="StunValidationStatus.members"></a><h4>Members</h4>
1220 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1221 <colgroup>
1222 <col width="300px" class="enum_members_name">
1223 <col class="enum_members_description">
1224 <col width="200px" class="enum_members_annotations">
1225 </colgroup>
1226 <tbody>
1227 <tr>
1228 <td class="enum_member_name"><p><a name="STUN-VALIDATION-SUCCESS:CAPS"></a>STUN_VALIDATION_SUCCESS</p></td>
1229 <td class="enum_member_description">
1230 <p>The message is validated</p>
1231 </td>
1232 <td class="enum_member_annotations"> </td>
1233 </tr>
1234 <tr>
1235 <td class="enum_member_name"><p><a name="STUN-VALIDATION-NOT-STUN:CAPS"></a>STUN_VALIDATION_NOT_STUN</p></td>
1236 <td class="enum_member_description">
1237 <p>This is not a valid STUN message</p>
1238 </td>
1239 <td class="enum_member_annotations"> </td>
1240 </tr>
1241 <tr>
1242 <td class="enum_member_name"><p><a name="STUN-VALIDATION-INCOMPLETE-STUN:CAPS"></a>STUN_VALIDATION_INCOMPLETE_STUN</p></td>
1243 <td class="enum_member_description">
1244 <p>The message seems to be valid but incomplete</p>
1245 </td>
1246 <td class="enum_member_annotations"> </td>
1247 </tr>
1248 <tr>
1249 <td class="enum_member_name"><p><a name="STUN-VALIDATION-BAD-REQUEST:CAPS"></a>STUN_VALIDATION_BAD_REQUEST</p></td>
1250 <td class="enum_member_description">
1251 <p>The message does not have the cookie or the
1252 fingerprint while the agent needs it with its usage</p>
1253 </td>
1254 <td class="enum_member_annotations"> </td>
1255 </tr>
1256 <tr>
1257 <td class="enum_member_name"><p><a name="STUN-VALIDATION-UNAUTHORIZED-BAD-REQUEST:CAPS"></a>STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST</p></td>
1258 <td class="enum_member_description">
1259 <p>The message is valid but
1260 unauthorized with no username and message-integrity attributes.
1261 A BAD_REQUEST error must be generated</p>
1262 </td>
1263 <td class="enum_member_annotations"> </td>
1264 </tr>
1265 <tr>
1266 <td class="enum_member_name"><p><a name="STUN-VALIDATION-UNAUTHORIZED:CAPS"></a>STUN_VALIDATION_UNAUTHORIZED</p></td>
1267 <td class="enum_member_description">
1268 <p>The message is valid but unauthorized as
1269 the username/password do not match.
1270 An UNAUTHORIZED error must be generated</p>
1271 </td>
1272 <td class="enum_member_annotations"> </td>
1273 </tr>
1274 <tr>
1275 <td class="enum_member_name"><p><a name="STUN-VALIDATION-UNMATCHED-RESPONSE:CAPS"></a>STUN_VALIDATION_UNMATCHED_RESPONSE</p></td>
1276 <td class="enum_member_description">
1277 <p>The message is valid but this is a
1278 response/error that doesn't match a previously sent request</p>
1279 </td>
1280 <td class="enum_member_annotations"> </td>
1281 </tr>
1282 <tr>
1283 <td class="enum_member_name"><p><a name="STUN-VALIDATION-UNKNOWN-REQUEST-ATTRIBUTE:CAPS"></a>STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE</p></td>
1284 <td class="enum_member_description">
1285 <p>The message is valid but
1286 contains one or more unknown comprehension attributes.
1287 <a class="link" href="libnice-StunAgent.html#stun-agent-build-unknown-attributes-error" title="stun_agent_build_unknown_attributes_error ()"><code class="function">stun_agent_build_unknown_attributes_error()</code></a> should be called</p>
1288 </td>
1289 <td class="enum_member_annotations"> </td>
1290 </tr>
1291 <tr>
1292 <td class="enum_member_name"><p><a name="STUN-VALIDATION-UNKNOWN-ATTRIBUTE:CAPS"></a>STUN_VALIDATION_UNKNOWN_ATTRIBUTE</p></td>
1293 <td class="enum_member_description">
1294 <p>The message is valid but contains one
1295 or more unknown comprehension attributes. This is a response, or error,
1296 or indication message and no error response should be sent</p>
1297 </td>
1298 <td class="enum_member_annotations"> </td>
1299 </tr>
1300 </tbody>
1301 </table></div>
1302 </div>
1303 </div>
1304 <hr>
1305 <div class="refsect2">
1306 <a name="StunDefaultValidaterData"></a><h3>StunDefaultValidaterData</h3>
1307 <pre class="programlisting">typedef struct {
1308   uint8_t *username;
1309   size_t username_len;
1310   uint8_t *password;
1311   size_t password_len;
1312 } StunDefaultValidaterData;
1313 </pre>
1314 <p>This structure is used as an element of the user_data to the
1315 <a class="link" href="libnice-StunAgent.html#stun-agent-default-validater" title="stun_agent_default_validater ()"><code class="function">stun_agent_default_validater()</code></a> function for authenticating a STUN
1316 message during validationg.</p>
1317 <p> See also: <a class="link" href="libnice-StunAgent.html#stun-agent-default-validater" title="stun_agent_default_validater ()"><code class="function">stun_agent_default_validater()</code></a> </p>
1318 <div class="refsect3">
1319 <a name="StunDefaultValidaterData.members"></a><h4>Members</h4>
1320 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1321 <colgroup>
1322 <col width="300px" class="struct_members_name">
1323 <col class="struct_members_description">
1324 <col width="200px" class="struct_members_annotations">
1325 </colgroup>
1326 <tbody>
1327 <tr>
1328 <td class="struct_member_name"><p><span class="type">uint8_t</span> *<em class="structfield"><code><a name="StunDefaultValidaterData.username"></a>username</code></em>;</p></td>
1329 <td class="struct_member_description"><p>The username</p></td>
1330 <td class="struct_member_annotations"> </td>
1331 </tr>
1332 <tr>
1333 <td class="struct_member_name"><p><span class="type">size_t</span> <em class="structfield"><code><a name="StunDefaultValidaterData.username-len"></a>username_len</code></em>;</p></td>
1334 <td class="struct_member_description"><p>The length of the <em class="parameter"><code>username</code></em>
1335 </p></td>
1336 <td class="struct_member_annotations"> </td>
1337 </tr>
1338 <tr>
1339 <td class="struct_member_name"><p><span class="type">uint8_t</span> *<em class="structfield"><code><a name="StunDefaultValidaterData.password"></a>password</code></em>;</p></td>
1340 <td class="struct_member_description"><p>The password</p></td>
1341 <td class="struct_member_annotations"> </td>
1342 </tr>
1343 <tr>
1344 <td class="struct_member_name"><p><span class="type">size_t</span> <em class="structfield"><code><a name="StunDefaultValidaterData.password-len"></a>password_len</code></em>;</p></td>
1345 <td class="struct_member_description"><p>The length of the <em class="parameter"><code>password</code></em>
1346 </p></td>
1347 <td class="struct_member_annotations"> </td>
1348 </tr>
1349 </tbody>
1350 </table></div>
1351 </div>
1352 </div>
1353 </div>
1354 <div class="refsect1">
1355 <a name="libnice-StunAgent.see-also"></a><h2>See Also</h2>
1356 <p><a class="link" href="libnice-StunMessage.html#StunMessage" title="struct StunMessage"><span class="type">StunMessage</span></a></p>
1357 </div>
1358 </div>
1359 <div class="footer">
1360 <hr>Generated by GTK-Doc V1.29</div>
1361 </body>
1362 </html>