/contrib/bind9/lib/lwres/man/lwres_gnba.html
HTML | 316 lines | 299 code | 0 blank | 17 comment | 0 complexity | 6ddf738a975187f206a7cfcc918994f5 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_gnba</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_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free — lightweight resolver getnamebyaddress message handling</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 32<div class="funcsynopsis"> 33<pre class="funcsynopsisinfo"> 34#include <lwres/lwres.h> 35</pre> 36<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 37<tr> 38<td><code class="funcdef"> 39lwres_result_t 40<b class="fsfunc">lwres_gnbarequest_render</b> 41(</code></td> 42<td>lwres_context_t * </td> 43<td> 44<var class="pdparam">ctx</var>, </td> 45</tr> 46<tr> 47<td> </td> 48<td>lwres_gnbarequest_t * </td> 49<td> 50<var class="pdparam">req</var>, </td> 51</tr> 52<tr> 53<td> </td> 54<td>lwres_lwpacket_t * </td> 55<td> 56<var class="pdparam">pkt</var>, </td> 57</tr> 58<tr> 59<td> </td> 60<td>lwres_buffer_t * </td> 61<td> 62<var class="pdparam">b</var><code>)</code>;</td> 63</tr> 64</table> 65<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 66<tr> 67<td><code class="funcdef"> 68lwres_result_t 69<b class="fsfunc">lwres_gnbaresponse_render</b> 70(</code></td> 71<td>lwres_context_t * </td> 72<td> 73<var class="pdparam">ctx</var>, </td> 74</tr> 75<tr> 76<td> </td> 77<td>lwres_gnbaresponse_t * </td> 78<td> 79<var class="pdparam">req</var>, </td> 80</tr> 81<tr> 82<td> </td> 83<td>lwres_lwpacket_t * </td> 84<td> 85<var class="pdparam">pkt</var>, </td> 86</tr> 87<tr> 88<td> </td> 89<td>lwres_buffer_t * </td> 90<td> 91<var class="pdparam">b</var><code>)</code>;</td> 92</tr> 93</table> 94<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 95<tr> 96<td><code class="funcdef"> 97lwres_result_t 98<b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td> 99<td>lwres_context_t * </td> 100<td> 101<var class="pdparam">ctx</var>, </td> 102</tr> 103<tr> 104<td> </td> 105<td>lwres_buffer_t * </td> 106<td> 107<var class="pdparam">b</var>, </td> 108</tr> 109<tr> 110<td> </td> 111<td>lwres_lwpacket_t * </td> 112<td> 113<var class="pdparam">pkt</var>, </td> 114</tr> 115<tr> 116<td> </td> 117<td>lwres_gnbarequest_t ** </td> 118<td> 119<var class="pdparam">structp</var><code>)</code>;</td> 120</tr> 121</table> 122<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 123<tr> 124<td><code class="funcdef"> 125lwres_result_t 126<b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td> 127<td>lwres_context_t * </td> 128<td> 129<var class="pdparam">ctx</var>, </td> 130</tr> 131<tr> 132<td> </td> 133<td>lwres_buffer_t * </td> 134<td> 135<var class="pdparam">b</var>, </td> 136</tr> 137<tr> 138<td> </td> 139<td>lwres_lwpacket_t * </td> 140<td> 141<var class="pdparam">pkt</var>, </td> 142</tr> 143<tr> 144<td> </td> 145<td>lwres_gnbaresponse_t ** </td> 146<td> 147<var class="pdparam">structp</var><code>)</code>;</td> 148</tr> 149</table> 150<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 151<tr> 152<td><code class="funcdef"> 153void 154<b class="fsfunc">lwres_gnbaresponse_free</b> 155(</code></td> 156<td>lwres_context_t * </td> 157<td> 158<var class="pdparam">ctx</var>, </td> 159</tr> 160<tr> 161<td> </td> 162<td>lwres_gnbaresponse_t ** </td> 163<td> 164<var class="pdparam">structp</var><code>)</code>;</td> 165</tr> 166</table> 167<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> 168<tr> 169<td><code class="funcdef"> 170void 171<b class="fsfunc">lwres_gnbarequest_free</b>(</code></td> 172<td>lwres_context_t * </td> 173<td> 174<var class="pdparam">ctx</var>, </td> 175</tr> 176<tr> 177<td> </td> 178<td>lwres_gnbarequest_t ** </td> 179<td> 180<var class="pdparam">structp</var><code>)</code>;</td> 181</tr> 182</table> 183</div> 184</div> 185<div class="refsect1" lang="en"> 186<a name="id2543529"></a><h2>DESCRIPTION</h2> 187<p> 188 These are low-level routines for creating and parsing 189 lightweight resolver address-to-name lookup request and 190 response messages. 191 </p> 192<p> 193 There are four main functions for the getnamebyaddr opcode. 194 One render function converts a getnamebyaddr request structure — 195 <span class="type">lwres_gnbarequest_t</span> — 196 to the lightweight resolver's canonical format. 197 It is complemented by a parse function that converts a packet in this 198 canonical format to a getnamebyaddr request structure. 199 Another render function converts the getnamebyaddr response structure 200 — 201 <span class="type">lwres_gnbaresponse_t</span> 202 to the canonical format. 203 This is complemented by a parse function which converts a packet in 204 canonical format to a getnamebyaddr response structure. 205 </p> 206<p> 207 These structures are defined in 208 <code class="filename">lwres/lwres.h</code>. 209 They are shown below. 210 </p> 211<pre class="programlisting"> 212#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U 213</pre> 214<p> 215 </p> 216<pre class="programlisting"> 217typedef struct { 218 lwres_uint32_t flags; 219 lwres_addr_t addr; 220} lwres_gnbarequest_t; 221</pre> 222<p> 223 </p> 224<pre class="programlisting"> 225typedef struct { 226 lwres_uint32_t flags; 227 lwres_uint16_t naliases; 228 char *realname; 229 char **aliases; 230 lwres_uint16_t realnamelen; 231 lwres_uint16_t *aliaslen; 232 void *base; 233 size_t baselen; 234} lwres_gnbaresponse_t; 235</pre> 236<p> 237 </p> 238<p><code class="function">lwres_gnbarequest_render()</code> 239 uses resolver context <code class="varname">ctx</code> to convert 240 getnamebyaddr request structure <code class="varname">req</code> to 241 canonical format. The packet header structure 242 <code class="varname">pkt</code> is initialised and transferred to buffer 243 <code class="varname">b</code>. The contents of <code class="varname">*req</code> 244 are then appended to the buffer in canonical format. 245 <code class="function">lwres_gnbaresponse_render()</code> performs the 246 same task, except it converts a getnamebyaddr response structure 247 <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's 248 canonical format. 249 </p> 250<p><code class="function">lwres_gnbarequest_parse()</code> 251 uses context <code class="varname">ctx</code> to convert the contents of 252 packet <code class="varname">pkt</code> to a 253 <span class="type">lwres_gnbarequest_t</span> structure. Buffer 254 <code class="varname">b</code> provides space to be used for storing this 255 structure. When the function succeeds, the resulting 256 <span class="type">lwres_gnbarequest_t</span> is made available through 257 <code class="varname">*structp</code>. 258 <code class="function">lwres_gnbaresponse_parse()</code> offers the same 259 semantics as <code class="function">lwres_gnbarequest_parse()</code> 260 except it yields a <span class="type">lwres_gnbaresponse_t</span> structure. 261 </p> 262<p><code class="function">lwres_gnbaresponse_free()</code> 263 and <code class="function">lwres_gnbarequest_free()</code> release the 264 memory in resolver context <code class="varname">ctx</code> that was 265 allocated to the <span class="type">lwres_gnbaresponse_t</span> or 266 <span class="type">lwres_gnbarequest_t</span> structures referenced via 267 <code class="varname">structp</code>. Any memory associated with 268 ancillary buffers and strings for those structures is also 269 discarded. 270 </p> 271</div> 272<div class="refsect1" lang="en"> 273<a name="id2543669"></a><h2>RETURN VALUES</h2> 274<p> 275 The getnamebyaddr opcode functions 276 <code class="function">lwres_gnbarequest_render()</code>, 277 <code class="function">lwres_gnbaresponse_render()</code> 278 <code class="function">lwres_gnbarequest_parse()</code> 279 and 280 <code class="function">lwres_gnbaresponse_parse()</code> 281 all return 282 <span class="errorcode">LWRES_R_SUCCESS</span> 283 on success. 284 They return 285 <span class="errorcode">LWRES_R_NOMEMORY</span> 286 if memory allocation fails. 287 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 288 is returned if the available space in the buffer 289 <code class="varname">b</code> 290 is too small to accommodate the packet header or the 291 <span class="type">lwres_gnbarequest_t</span> 292 and 293 <span class="type">lwres_gnbaresponse_t</span> 294 structures. 295 <code class="function">lwres_gnbarequest_parse()</code> 296 and 297 <code class="function">lwres_gnbaresponse_parse()</code> 298 will return 299 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 300 if the buffer is not empty after decoding the received packet. 301 These functions will return 302 <span class="errorcode">LWRES_R_FAILURE</span> 303 if 304 <em class="structfield"><code>pktflags</code></em> 305 in the packet header structure 306 <span class="type">lwres_lwpacket_t</span> 307 indicate that the packet is not a response to an earlier query. 308 </p> 309</div> 310<div class="refsect1" lang="en"> 311<a name="id2543735"></a><h2>SEE ALSO</h2> 312<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>. 313 </p> 314</div> 315</div></body> 316</html>