contrib/bind-9.2.4rc7/lib/lwres/man/lwres_gabn.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_gabn.html,v 1.6.2.2 2004/03/15 04:45:01 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_gabn</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_gabn</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free&nbsp;--&nbsp;lightweight resolver getaddrbyname 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_gabnrequest_render</CODE
  71 >(lwres_context_t *ctx, lwres_gabnrequest_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_gabnresponse_render</CODE
  79 >(lwres_context_t *ctx, lwres_gabnresponse_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_gabnrequest_parse</CODE
  87 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);</CODE
  88 ></P
  89 ><P
  90 ><CODE
  91 ><CODE
  92 CLASS="FUNCDEF"
  93 >lwres_result_t
  94 lwres_gabnresponse_parse</CODE
  95 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);</CODE
  96 ></P
  97 ><P
  98 ><CODE
  99 ><CODE
 100 CLASS="FUNCDEF"
 101 >void
 102 lwres_gabnresponse_free</CODE
 103 >(lwres_context_t *ctx, lwres_gabnresponse_t **structp);</CODE
 104 ></P
 105 ><P
 106 ><CODE
 107 ><CODE
 108 CLASS="FUNCDEF"
 109 >void
 110 lwres_gabnrequest_free</CODE
 111 >(lwres_context_t *ctx, lwres_gabnrequest_t **structp);</CODE
 112 ></P
 113 ><P
 114 ></P
 115 ></DIV
 116 ></DIV
 117 ><DIV
 118 CLASS="REFSECT1"
 119 ><A
 120 NAME="AEN57"
 121 ></A
 122 ><H2
 123 >DESCRIPTION</H2
 124 ><P
 125 >These are low-level routines for creating and parsing
 126 lightweight resolver name-to-address lookup request and
 127 response messages.</P
 128 ><P
 129 >There are four main functions for the getaddrbyname opcode.
 130 One render function converts a getaddrbyname request structure &mdash;
 131 <SPAN
 132 CLASS="TYPE"
 133 >lwres_gabnrequest_t</SPAN
 134 > &mdash;
 135 to the lighweight resolver's canonical format.
 136 It is complemented by a parse function that converts a packet in this
 137 canonical format to a getaddrbyname request structure.
 138 Another render function converts the getaddrbyname response structure &mdash;
 139 <SPAN
 140 CLASS="TYPE"
 141 >lwres_gabnresponse_t</SPAN
 142 > &mdash;
 143 to the canonical format.
 144 This is complemented by a parse function which converts a packet in
 145 canonical format to a getaddrbyname response structure.</P
 146 ><P
 147 >These structures are defined in
 148 <TT
 149 CLASS="FILENAME"
 150 >&lt;lwres/lwres.h&gt;</TT
 151 >.
 152 They are shown below.
 153 <PRE
 154 CLASS="PROGRAMLISTING"
 155 >#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 156
 157 typedef struct lwres_addr lwres_addr_t;
 158 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 159
 160 typedef struct {
 161         lwres_uint32_t  flags;
 162         lwres_uint32_t  addrtypes;
 163         lwres_uint16_t  namelen;
 164         char           *name;
 165 } lwres_gabnrequest_t;
 166
 167 typedef struct {
 168         lwres_uint32_t          flags;
 169         lwres_uint16_t          naliases;
 170         lwres_uint16_t          naddrs;
 171         char                   *realname;
 172         char                  **aliases;
 173         lwres_uint16_t          realnamelen;
 174         lwres_uint16_t         *aliaslen;
 175         lwres_addrlist_t        addrs;
 176         void                   *base;
 177         size_t                  baselen;
 178 } lwres_gabnresponse_t;</PRE
 179 ></P
 180 ><P
 181 ><TT
 182 CLASS="FUNCTION"
 183 >lwres_gabnrequest_render()</TT
 184 >
 185 uses resolver context
 186 <TT
 187 CLASS="PARAMETER"
 188 ><I
 189 >ctx</I
 190 ></TT
 191 >
 192 to convert getaddrbyname request structure
 193 <TT
 194 CLASS="PARAMETER"
 195 ><I
 196 >req</I
 197 ></TT
 198 >
 199 to canonical format.
 200 The packet header structure
 201 <TT
 202 CLASS="PARAMETER"
 203 ><I
 204 >pkt</I
 205 ></TT
 206 >
 207 is initialised and transferred to
 208 buffer
 209 <TT
 210 CLASS="PARAMETER"
 211 ><I
 212 >b</I
 213 ></TT
 214 >.
 215
 216 The contents of
 217 <TT
 218 CLASS="PARAMETER"
 219 ><I
 220 >*req</I
 221 ></TT
 222 >
 223 are then appended to the buffer in canonical format.
 224 <TT
 225 CLASS="FUNCTION"
 226 >lwres_gabnresponse_render()</TT
 227 >
 228 performs the same task, except it converts a getaddrbyname response structure
 229 <SPAN
 230 CLASS="TYPE"
 231 >lwres_gabnresponse_t</SPAN
 232 >
 233 to the lightweight resolver's canonical format.</P
 234 ><P
 235 ><TT
 236 CLASS="FUNCTION"
 237 >lwres_gabnrequest_parse()</TT
 238 >
 239 uses context
 240 <TT
 241 CLASS="PARAMETER"
 242 ><I
 243 >ctx</I
 244 ></TT
 245 >
 246 to convert the contents of packet
 247 <TT
 248 CLASS="PARAMETER"
 249 ><I
 250 >pkt</I
 251 ></TT
 252 >
 253 to a
 254 <SPAN
 255 CLASS="TYPE"
 256 >lwres_gabnrequest_t</SPAN
 257 >
 258 structure.
 259 Buffer
 260 <TT
 261 CLASS="PARAMETER"
 262 ><I
 263 >b</I
 264 ></TT
 265 >
 266 provides space to be used for storing this structure.
 267 When the function succeeds, the resulting
 268 <SPAN
 269 CLASS="TYPE"
 270 >lwres_gabnrequest_t</SPAN
 271 >
 272 is made available through
 273 <TT
 274 CLASS="PARAMETER"
 275 ><I
 276 >*structp</I
 277 ></TT
 278 >.
 279
 280 <TT
 281 CLASS="FUNCTION"
 282 >lwres_gabnresponse_parse()</TT
 283 >
 284 offers the same semantics as
 285 <TT
 286 CLASS="FUNCTION"
 287 >lwres_gabnrequest_parse()</TT
 288 >
 289 except it yields a
 290 <SPAN
 291 CLASS="TYPE"
 292 >lwres_gabnresponse_t</SPAN
 293 >
 294 structure.</P
 295 ><P
 296 ><TT
 297 CLASS="FUNCTION"
 298 >lwres_gabnresponse_free()</TT
 299 >
 300 and
 301 <TT
 302 CLASS="FUNCTION"
 303 >lwres_gabnrequest_free()</TT
 304 >
 305 release the memory in resolver context
 306 <TT
 307 CLASS="PARAMETER"
 308 ><I
 309 >ctx</I
 310 ></TT
 311 >
 312 that was allocated to the
 313 <SPAN
 314 CLASS="TYPE"
 315 >lwres_gabnresponse_t</SPAN
 316 >
 317 or
 318 <SPAN
 319 CLASS="TYPE"
 320 >lwres_gabnrequest_t</SPAN
 321 >
 322 structures referenced via
 323 <TT
 324 CLASS="PARAMETER"
 325 ><I
 326 >structp</I
 327 ></TT
 328 >.
 329
 330 Any memory associated with ancillary buffers and strings for those
 331 structures is also discarded.</P
 332 ></DIV
 333 ><DIV
 334 CLASS="REFSECT1"
 335 ><A
 336 NAME="AEN93"
 337 ></A
 338 ><H2
 339 >RETURN VALUES</H2
 340 ><P
 341 >The getaddrbyname opcode functions
 342 <TT
 343 CLASS="FUNCTION"
 344 >lwres_gabnrequest_render()</TT
 345 >,
 346 <TT
 347 CLASS="FUNCTION"
 348 >lwres_gabnresponse_render()</TT
 349 >
 350 <TT
 351 CLASS="FUNCTION"
 352 >lwres_gabnrequest_parse()</TT
 353 >
 354 and
 355 <TT
 356 CLASS="FUNCTION"
 357 >lwres_gabnresponse_parse()</TT
 358 >
 359 all return
 360 <SPAN
 361 CLASS="ERRORCODE"
 362 >LWRES_R_SUCCESS</SPAN
 363 >
 364 on success.
 365 They return
 366 <SPAN
 367 CLASS="ERRORCODE"
 368 >LWRES_R_NOMEMORY</SPAN
 369 >
 370 if memory allocation fails.
 371 <SPAN
 372 CLASS="ERRORCODE"
 373 >LWRES_R_UNEXPECTEDEND</SPAN
 374 >
 375 is returned if the available space in the buffer
 376 <TT
 377 CLASS="PARAMETER"
 378 ><I
 379 >b</I
 380 ></TT
 381 >
 382 is too small to accommodate the packet header or the
 383 <SPAN
 384 CLASS="TYPE"
 385 >lwres_gabnrequest_t</SPAN
 386 >
 387 and
 388 <SPAN
 389 CLASS="TYPE"
 390 >lwres_gabnresponse_t</SPAN
 391 >
 392 structures.
 393 <TT
 394 CLASS="FUNCTION"
 395 >lwres_gabnrequest_parse()</TT
 396 >
 397 and
 398 <TT
 399 CLASS="FUNCTION"
 400 >lwres_gabnresponse_parse()</TT
 401 >
 402 will return
 403 <SPAN
 404 CLASS="ERRORCODE"
 405 >LWRES_R_UNEXPECTEDEND</SPAN
 406 >
 407 if the buffer is not empty after decoding the received packet.
 408 These functions will return
 409 <SPAN
 410 CLASS="ERRORCODE"
 411 >LWRES_R_FAILURE</SPAN
 412 >
 413 if
 414 <TT
 415 CLASS="STRUCTFIELD"
 416 ><I
 417 >pktflags</I
 418 ></TT
 419 >
 420 in the packet header structure
 421 <SPAN
 422 CLASS="TYPE"
 423 >lwres_lwpacket_t</SPAN
 424 >
 425 indicate that the packet is not a response to an earlier query.</P
 426 ></DIV
 427 ><DIV
 428 CLASS="REFSECT1"
 429 ><A
 430 NAME="AEN112"
 431 ></A
 432 ><H2
 433 >SEE ALSO</H2
 434 ><P
 435 ><SPAN
 436 CLASS="CITEREFENTRY"
 437 ><SPAN
 438 CLASS="REFENTRYTITLE"
 439 >lwres_packet</SPAN
 440 >(3)</SPAN
 441 ></P
 442 ></DIV
 443 ></BODY
 444 ></HTML
 445 >