/contrib/bind9/lib/lwres/man/lwres_gabn.html
HTML | 324 lines | 304 code | 3 blank | 17 comment | 0 complexity | 6a51675abdb0c0fde5c7b5dd65a44877 MD5 | raw file
1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000, 2001 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<!-- $Id$ --> 18<html> 19<head> 20<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21<title>lwres_gabn</title> 22<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23</head> 24<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25<a name="id2476275"></a><div class="titlepage"></div> 26<div class="refnamediv"> 27<h2>Name</h2> 28<p>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 32<div class="funcsynopsis"> 33<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre> 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 35<tr> 36<td><code class="funcdef"> 37lwres_result_t 38<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td> 39<td>lwres_context_t * </td> 40<td> 41<var class="pdparam">ctx</var>, </td> 42</tr> 43<tr> 44<td> </td> 45<td>lwres_gabnrequest_t * </td> 46<td> 47<var class="pdparam">req</var>, </td> 48</tr> 49<tr> 50<td> </td> 51<td>lwres_lwpacket_t * </td> 52<td> 53<var class="pdparam">pkt</var>, </td> 54</tr> 55<tr> 56<td> </td> 57<td>lwres_buffer_t * </td> 58<td> 59<var class="pdparam">b</var><code>)</code>;</td> 60</tr> 61</table> 62<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 63<tr> 64<td><code class="funcdef"> 65lwres_result_t 66<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td> 67<td>lwres_context_t * </td> 68<td> 69<var class="pdparam">ctx</var>, </td> 70</tr> 71<tr> 72<td> </td> 73<td>lwres_gabnresponse_t * </td> 74<td> 75<var class="pdparam">req</var>, </td> 76</tr> 77<tr> 78<td> </td> 79<td>lwres_lwpacket_t * </td> 80<td> 81<var class="pdparam">pkt</var>, </td> 82</tr> 83<tr> 84<td> </td> 85<td>lwres_buffer_t * </td> 86<td> 87<var class="pdparam">b</var><code>)</code>;</td> 88</tr> 89</table> 90<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 91<tr> 92<td><code class="funcdef"> 93lwres_result_t 94<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td> 95<td>lwres_context_t * </td> 96<td> 97<var class="pdparam">ctx</var>, </td> 98</tr> 99<tr> 100<td> </td> 101<td>lwres_buffer_t * </td> 102<td> 103<var class="pdparam">b</var>, </td> 104</tr> 105<tr> 106<td> </td> 107<td>lwres_lwpacket_t * </td> 108<td> 109<var class="pdparam">pkt</var>, </td> 110</tr> 111<tr> 112<td> </td> 113<td>lwres_gabnrequest_t ** </td> 114<td> 115<var class="pdparam">structp</var><code>)</code>;</td> 116</tr> 117</table> 118<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 119<tr> 120<td><code class="funcdef"> 121lwres_result_t 122<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td> 123<td>lwres_context_t * </td> 124<td> 125<var class="pdparam">ctx</var>, </td> 126</tr> 127<tr> 128<td> </td> 129<td>lwres_buffer_t * </td> 130<td> 131<var class="pdparam">b</var>, </td> 132</tr> 133<tr> 134<td> </td> 135<td>lwres_lwpacket_t * </td> 136<td> 137<var class="pdparam">pkt</var>, </td> 138</tr> 139<tr> 140<td> </td> 141<td>lwres_gabnresponse_t ** </td> 142<td> 143<var class="pdparam">structp</var><code>)</code>;</td> 144</tr> 145</table> 146<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 147<tr> 148<td><code class="funcdef"> 149void 150<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td> 151<td>lwres_context_t * </td> 152<td> 153<var class="pdparam">ctx</var>, </td> 154</tr> 155<tr> 156<td> </td> 157<td>lwres_gabnresponse_t ** </td> 158<td> 159<var class="pdparam">structp</var><code>)</code>;</td> 160</tr> 161</table> 162<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> 163<tr> 164<td><code class="funcdef"> 165void 166<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td> 167<td>lwres_context_t * </td> 168<td> 169<var class="pdparam">ctx</var>, </td> 170</tr> 171<tr> 172<td> </td> 173<td>lwres_gabnrequest_t ** </td> 174<td> 175<var class="pdparam">structp</var><code>)</code>;</td> 176</tr> 177</table> 178</div> 179</div> 180<div class="refsect1" lang="en"> 181<a name="id2543526"></a><h2>DESCRIPTION</h2> 182<p> 183 These are low-level routines for creating and parsing 184 lightweight resolver name-to-address lookup request and 185 response messages. 186 </p> 187<p> 188 There are four main functions for the getaddrbyname opcode. 189 One render function converts a getaddrbyname request structure — 190 <span class="type">lwres_gabnrequest_t</span> — 191 to the lighweight resolver's canonical format. 192 It is complemented by a parse function that converts a packet in this 193 canonical format to a getaddrbyname request structure. 194 Another render function converts the getaddrbyname response structure 195 — <span class="type">lwres_gabnresponse_t</span> — 196 to the canonical format. 197 This is complemented by a parse function which converts a packet in 198 canonical format to a getaddrbyname response structure. 199 </p> 200<p> 201 These structures are defined in 202 <code class="filename"><lwres/lwres.h></code>. 203 They are shown below. 204 </p> 205<pre class="programlisting"> 206#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U 207</pre> 208<p> 209 </p> 210<pre class="programlisting"> 211typedef struct lwres_addr lwres_addr_t; 212typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; 213</pre> 214<p> 215 </p> 216<pre class="programlisting"> 217typedef struct { 218 lwres_uint32_t flags; 219 lwres_uint32_t addrtypes; 220 lwres_uint16_t namelen; 221 char *name; 222} lwres_gabnrequest_t; 223</pre> 224<p> 225 </p> 226<pre class="programlisting"> 227typedef struct { 228 lwres_uint32_t flags; 229 lwres_uint16_t naliases; 230 lwres_uint16_t naddrs; 231 char *realname; 232 char **aliases; 233 lwres_uint16_t realnamelen; 234 lwres_uint16_t *aliaslen; 235 lwres_addrlist_t addrs; 236 void *base; 237 size_t baselen; 238} lwres_gabnresponse_t; 239</pre> 240<p> 241 </p> 242<p><code class="function">lwres_gabnrequest_render()</code> 243 uses resolver context <em class="parameter"><code>ctx</code></em> to convert 244 getaddrbyname request structure <em class="parameter"><code>req</code></em> to 245 canonical format. The packet header structure 246 <em class="parameter"><code>pkt</code></em> is initialised and transferred to 247 buffer <em class="parameter"><code>b</code></em>. 248 249 The contents of <em class="parameter"><code>*req</code></em> are then appended to 250 the buffer in canonical format. 251 <code class="function">lwres_gabnresponse_render()</code> performs the 252 same task, except it converts a getaddrbyname response structure 253 <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's 254 canonical format. 255 </p> 256<p><code class="function">lwres_gabnrequest_parse()</code> 257 uses context <em class="parameter"><code>ctx</code></em> to convert the contents 258 of packet <em class="parameter"><code>pkt</code></em> to a 259 <span class="type">lwres_gabnrequest_t</span> structure. Buffer 260 <em class="parameter"><code>b</code></em> provides space to be used for storing 261 this structure. When the function succeeds, the resulting 262 <span class="type">lwres_gabnrequest_t</span> is made available through 263 <em class="parameter"><code>*structp</code></em>. 264 265 <code class="function">lwres_gabnresponse_parse()</code> offers the same 266 semantics as <code class="function">lwres_gabnrequest_parse()</code> 267 except it yields a <span class="type">lwres_gabnresponse_t</span> structure. 268 </p> 269<p><code class="function">lwres_gabnresponse_free()</code> 270 and <code class="function">lwres_gabnrequest_free()</code> release the 271 memory in resolver context <em class="parameter"><code>ctx</code></em> that was 272 allocated to the <span class="type">lwres_gabnresponse_t</span> or 273 <span class="type">lwres_gabnrequest_t</span> structures referenced via 274 <em class="parameter"><code>structp</code></em>. 275 276 Any memory associated with ancillary buffers and strings for 277 those structures is also discarded. 278 </p> 279</div> 280<div class="refsect1" lang="en"> 281<a name="id2543671"></a><h2>RETURN VALUES</h2> 282<p> 283 The getaddrbyname opcode functions 284 <code class="function">lwres_gabnrequest_render()</code>, 285 <code class="function">lwres_gabnresponse_render()</code> 286 <code class="function">lwres_gabnrequest_parse()</code> 287 and 288 <code class="function">lwres_gabnresponse_parse()</code> 289 all return 290 <span class="errorcode">LWRES_R_SUCCESS</span> 291 on success. 292 They return 293 <span class="errorcode">LWRES_R_NOMEMORY</span> 294 if memory allocation fails. 295 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 296 is returned if the available space in the buffer 297 <em class="parameter"><code>b</code></em> 298 is too small to accommodate the packet header or the 299 <span class="type">lwres_gabnrequest_t</span> 300 and 301 <span class="type">lwres_gabnresponse_t</span> 302 structures. 303 <code class="function">lwres_gabnrequest_parse()</code> 304 and 305 <code class="function">lwres_gabnresponse_parse()</code> 306 will return 307 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 308 if the buffer is not empty after decoding the received packet. 309 These functions will return 310 <span class="errorcode">LWRES_R_FAILURE</span> 311 if 312 <em class="structfield"><code>pktflags</code></em> 313 in the packet header structure 314 <span class="type">lwres_lwpacket_t</span> 315 indicate that the packet is not a response to an earlier query. 316 </p> 317</div> 318<div class="refsect1" lang="en"> 319<a name="id2543737"></a><h2>SEE ALSO</h2> 320<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span> 321 </p> 322</div> 323</div></body> 324</html>