contrib/bind-9.2.4rc7/lib/lwres/man/lwres_gnba.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and 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
  18 <!-- $Id: lwres_gnba.html,v 1.6.2.2 2004/03/15 04:45:03 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_gnba</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres_gnba</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free&nbsp;--&nbsp;lightweight resolver getnamebyaddress message handling</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN16"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN17"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/lwres.h&gt;</PRE
  65 ><P
  66 ><CODE
  67 ><CODE
  68 CLASS="FUNCDEF"
  69 >lwres_result_t
  70 lwres_gnbarequest_render</CODE
  71 >(lwres_context_t *ctx, lwres_gnbarequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
  72 ></P
  73 ><P
  74 ><CODE
  75 ><CODE
  76 CLASS="FUNCDEF"
  77 >lwres_result_t
  78 lwres_gnbaresponse_render</CODE
  79 >(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
  80 ></P
  81 ><P
  82 ><CODE
  83 ><CODE
  84 CLASS="FUNCDEF"
  85 >lwres_result_t
  86 lwres_gnbarequest_parse</CODE
  87 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);</CODE
  88 ></P
  89 ><P
  90 ><CODE
  91 ><CODE
  92 CLASS="FUNCDEF"
  93 >lwres_result_t
  94 lwres_gnbaresponse_parse</CODE
  95 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp);</CODE
  96 ></P
  97 ><P
  98 ><CODE
  99 ><CODE
 100 CLASS="FUNCDEF"
 101 >void
 102 lwres_gnbaresponse_free</CODE
 103 >(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);</CODE
 104 ></P
 105 ><P
 106 ><CODE
 107 ><CODE
 108 CLASS="FUNCDEF"
 109 >void
 110 lwres_gnbarequest_free</CODE
 111 >(lwres_context_t *ctx, lwres_gnbarequest_t **structp);</CODE
 112 ></P
 113 ><P
 114 ></P
 115 ></DIV
 116 ></DIV
 117 ><DIV
 118 CLASS="REFSECT1"
 119 ><A
 120 NAME="AEN61"
 121 ></A
 122 ><H2
 123 >DESCRIPTION</H2
 124 ><P
 125 >These are low-level routines for creating and parsing
 126 lightweight resolver address-to-name lookup request and
 127 response messages.</P
 128 ><P
 129 >There are four main functions for the getnamebyaddr opcode.
 130 One render function converts a getnamebyaddr request structure &mdash;
 131 <SPAN
 132 CLASS="TYPE"
 133 >lwres_gnbarequest_t</SPAN
 134 > &mdash;
 135 to the lightweight resolver's canonical format.
 136 It is complemented by a parse function that converts a packet in this
 137 canonical format to a getnamebyaddr request structure.
 138 Another render function converts the getnamebyaddr response structure &mdash;
 139 <SPAN
 140 CLASS="TYPE"
 141 >lwres_gnbaresponse_t</SPAN
 142 >
 143 to the canonical format.
 144 This is complemented by a parse function which converts a packet in
 145 canonical format to a getnamebyaddr response structure.</P
 146 ><P
 147 >These structures are defined in
 148 <TT
 149 CLASS="FILENAME"
 150 >lwres/lwres.h</TT
 151 >.
 152 They are shown below.
 153 <PRE
 154 CLASS="PROGRAMLISTING"
 155 >#define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 156
 157 typedef struct {
 158         lwres_uint32_t  flags;
 159         lwres_addr_t    addr;
 160 } lwres_gnbarequest_t;
 161
 162 typedef struct {
 163         lwres_uint32_t  flags;
 164         lwres_uint16_t  naliases;
 165         char           *realname;
 166         char          **aliases;
 167         lwres_uint16_t  realnamelen;
 168         lwres_uint16_t *aliaslen;
 169         void           *base;
 170         size_t          baselen;
 171 } lwres_gnbaresponse_t;</PRE
 172 ></P
 173 ><P
 174 ><TT
 175 CLASS="FUNCTION"
 176 >lwres_gnbarequest_render()</TT
 177 >
 178 uses resolver context
 179 <TT
 180 CLASS="VARNAME"
 181 >ctx</TT
 182 >
 183 to convert getnamebyaddr request structure
 184 <TT
 185 CLASS="VARNAME"
 186 >req</TT
 187 >
 188 to canonical format.
 189 The packet header structure
 190 <TT
 191 CLASS="VARNAME"
 192 >pkt</TT
 193 >
 194 is initialised and transferred to
 195 buffer
 196 <TT
 197 CLASS="VARNAME"
 198 >b</TT
 199 >.
 200 The contents of
 201 <TT
 202 CLASS="VARNAME"
 203 >*req</TT
 204 >
 205 are then appended to the buffer in canonical format.
 206 <TT
 207 CLASS="FUNCTION"
 208 >lwres_gnbaresponse_render()</TT
 209 >
 210 performs the same task, except it converts a getnamebyaddr response structure
 211 <SPAN
 212 CLASS="TYPE"
 213 >lwres_gnbaresponse_t</SPAN
 214 >
 215 to the lightweight resolver's canonical format.</P
 216 ><P
 217 ><TT
 218 CLASS="FUNCTION"
 219 >lwres_gnbarequest_parse()</TT
 220 >
 221 uses context
 222 <TT
 223 CLASS="VARNAME"
 224 >ctx</TT
 225 >
 226 to convert the contents of packet
 227 <TT
 228 CLASS="VARNAME"
 229 >pkt</TT
 230 >
 231 to a
 232 <SPAN
 233 CLASS="TYPE"
 234 >lwres_gnbarequest_t</SPAN
 235 >
 236 structure.
 237 Buffer
 238 <TT
 239 CLASS="VARNAME"
 240 >b</TT
 241 >
 242 provides space to be used for storing this structure.
 243 When the function succeeds, the resulting
 244 <SPAN
 245 CLASS="TYPE"
 246 >lwres_gnbarequest_t</SPAN
 247 >
 248 is made available through
 249 <TT
 250 CLASS="VARNAME"
 251 >*structp</TT
 252 >.
 253 <TT
 254 CLASS="FUNCTION"
 255 >lwres_gnbaresponse_parse()</TT
 256 >
 257 offers the same semantics as
 258 <TT
 259 CLASS="FUNCTION"
 260 >lwres_gnbarequest_parse()</TT
 261 >
 262 except it yields a
 263 <SPAN
 264 CLASS="TYPE"
 265 >lwres_gnbaresponse_t</SPAN
 266 >
 267 structure.</P
 268 ><P
 269 ><TT
 270 CLASS="FUNCTION"
 271 >lwres_gnbaresponse_free()</TT
 272 >
 273 and
 274 <TT
 275 CLASS="FUNCTION"
 276 >lwres_gnbarequest_free()</TT
 277 >
 278 release the memory in resolver context
 279 <TT
 280 CLASS="VARNAME"
 281 >ctx</TT
 282 >
 283 that was allocated to the
 284 <SPAN
 285 CLASS="TYPE"
 286 >lwres_gnbaresponse_t</SPAN
 287 >
 288 or
 289 <SPAN
 290 CLASS="TYPE"
 291 >lwres_gnbarequest_t</SPAN
 292 >
 293 structures referenced via
 294 <TT
 295 CLASS="VARNAME"
 296 >structp</TT
 297 >.
 298 Any memory associated with ancillary buffers and strings for those
 299 structures is also discarded.</P
 300 ></DIV
 301 ><DIV
 302 CLASS="REFSECT1"
 303 ><A
 304 NAME="AEN97"
 305 ></A
 306 ><H2
 307 >RETURN VALUES</H2
 308 ><P
 309 >The getnamebyaddr opcode functions
 310 <TT
 311 CLASS="FUNCTION"
 312 >lwres_gnbarequest_render()</TT
 313 >,
 314 <TT
 315 CLASS="FUNCTION"
 316 >lwres_gnbaresponse_render()</TT
 317 >
 318 <TT
 319 CLASS="FUNCTION"
 320 >lwres_gnbarequest_parse()</TT
 321 >
 322 and
 323 <TT
 324 CLASS="FUNCTION"
 325 >lwres_gnbaresponse_parse()</TT
 326 >
 327 all return
 328 <SPAN
 329 CLASS="ERRORCODE"
 330 >LWRES_R_SUCCESS</SPAN
 331 >
 332 on success.
 333 They return
 334 <SPAN
 335 CLASS="ERRORCODE"
 336 >LWRES_R_NOMEMORY</SPAN
 337 >
 338 if memory allocation fails.
 339 <SPAN
 340 CLASS="ERRORCODE"
 341 >LWRES_R_UNEXPECTEDEND</SPAN
 342 >
 343 is returned if the available space in the buffer
 344 <TT
 345 CLASS="VARNAME"
 346 >b</TT
 347 >
 348 is too small to accommodate the packet header or the
 349 <SPAN
 350 CLASS="TYPE"
 351 >lwres_gnbarequest_t</SPAN
 352 >
 353 and
 354 <SPAN
 355 CLASS="TYPE"
 356 >lwres_gnbaresponse_t</SPAN
 357 >
 358 structures.
 359 <TT
 360 CLASS="FUNCTION"
 361 >lwres_gnbarequest_parse()</TT
 362 >
 363 and
 364 <TT
 365 CLASS="FUNCTION"
 366 >lwres_gnbaresponse_parse()</TT
 367 >
 368 will return
 369 <SPAN
 370 CLASS="ERRORCODE"
 371 >LWRES_R_UNEXPECTEDEND</SPAN
 372 >
 373 if the buffer is not empty after decoding the received packet.
 374 These functions will return
 375 <SPAN
 376 CLASS="ERRORCODE"
 377 >LWRES_R_FAILURE</SPAN
 378 >
 379 if
 380 <TT
 381 CLASS="STRUCTFIELD"
 382 ><I
 383 >pktflags</I
 384 ></TT
 385 >
 386 in the packet header structure
 387 <SPAN
 388 CLASS="TYPE"
 389 >lwres_lwpacket_t</SPAN
 390 >
 391 indicate that the packet is not a response to an earlier query.</P
 392 ></DIV
 393 ><DIV
 394 CLASS="REFSECT1"
 395 ><A
 396 NAME="AEN116"
 397 ></A
 398 ><H2
 399 >SEE ALSO</H2
 400 ><P
 401 ><SPAN
 402 CLASS="CITEREFENTRY"
 403 ><SPAN
 404 CLASS="REFENTRYTITLE"
 405 >lwres_packet</SPAN
 406 >(3)</SPAN
 407 >.</P
 408 ></DIV
 409 ></BODY
 410 ></HTML
 411 >