lib/liblwres/man/lwres_gabn.html

   1 <!--
   2  - Copyright (C) 2000, 2001  Internet Software Consortium.
   3  -
   4  - Permission to use, copy, modify, and distribute this software for any
   5  - purpose with or without fee is hereby granted, provided that the above
   6  - copyright notice and this permission notice appear in all copies.
   7  -
   8  - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
   9  - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  10  - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  11  - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  13  - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  14  - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  15  - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <HTML
  18 ><HEAD
  19 ><TITLE
  20 >lwres_gabn</TITLE
  21 ><META
  22 NAME="GENERATOR"
  23 CONTENT="Modular DocBook HTML Stylesheet Version 1.61
  24 "></HEAD
  25 ><BODY
  26 CLASS="REFENTRY"
  27 BGCOLOR="#FFFFFF"
  28 TEXT="#000000"
  29 LINK="#0000FF"
  30 VLINK="#840084"
  31 ALINK="#0000FF"
  32 ><H1
  33 ><A
  34 NAME="AEN1"
  35 >lwres_gabn</A
  36 ></H1
  37 ><DIV
  38 CLASS="REFNAMEDIV"
  39 ><A
  40 NAME="AEN8"
  41 ></A
  42 ><H2
  43 >Name</H2
  44 >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
  45 ><DIV
  46 CLASS="REFSYNOPSISDIV"
  47 ><A
  48 NAME="AEN16"
  49 ></A
  50 ><H2
  51 >Synopsis</H2
  52 ><DIV
  53 CLASS="FUNCSYNOPSIS"
  54 ><A
  55 NAME="AEN17"
  56 ></A
  57 ><P
  58 ></P
  59 ><PRE
  60 CLASS="FUNCSYNOPSISINFO"
  61 >#include &lt;lwres/lwres.h&gt;</PRE
  62 ><P
  63 ><CODE
  64 ><CODE
  65 CLASS="FUNCDEF"
  66 >lwres_result_t
  67 lwres_gabnrequest_render</CODE
  68 >(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
  69 ></P
  70 ><P
  71 ><CODE
  72 ><CODE
  73 CLASS="FUNCDEF"
  74 >lwres_result_t
  75 lwres_gabnresponse_render</CODE
  76 >(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
  77 ></P
  78 ><P
  79 ><CODE
  80 ><CODE
  81 CLASS="FUNCDEF"
  82 >lwres_result_t
  83 lwres_gabnrequest_parse</CODE
  84 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);</CODE
  85 ></P
  86 ><P
  87 ><CODE
  88 ><CODE
  89 CLASS="FUNCDEF"
  90 >lwres_result_t
  91 lwres_gabnresponse_parse</CODE
  92 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);</CODE
  93 ></P
  94 ><P
  95 ><CODE
  96 ><CODE
  97 CLASS="FUNCDEF"
  98 >void
  99 lwres_gabnresponse_free</CODE
 100 >(lwres_context_t *ctx, lwres_gabnresponse_t **structp);</CODE
 101 ></P
 102 ><P
 103 ><CODE
 104 ><CODE
 105 CLASS="FUNCDEF"
 106 >void
 107 lwres_gabnrequest_free</CODE
 108 >(lwres_context_t *ctx, lwres_gabnrequest_t **structp);</CODE
 109 ></P
 110 ><P
 111 ></P
 112 ></DIV
 113 ></DIV
 114 ><DIV
 115 CLASS="REFSECT1"
 116 ><A
 117 NAME="AEN57"
 118 ></A
 119 ><H2
 120 >DESCRIPTION</H2
 121 ><P
 122 >These are low-level routines for creating and parsing
 123 lightweight resolver name-to-address lookup request and
 124 response messages.</P
 125 ><P
 126 >There are four main functions for the getaddrbyname opcode.
 127 One render function converts a getaddrbyname request structure &mdash;
 128 <SPAN
 129 CLASS="TYPE"
 130 >lwres_gabnrequest_t</SPAN
 131 > &mdash;
 132 to the lighweight resolver's canonical format.
 133 It is complemented by a parse function that converts a packet in this
 134 canonical format to a getaddrbyname request structure.
 135 Another render function converts the getaddrbyname response structure &mdash;
 136 <SPAN
 137 CLASS="TYPE"
 138 >lwres_gabnresponse_t</SPAN
 139 > &mdash;
 140 to the canonical format.
 141 This is complemented by a parse function which converts a packet in
 142 canonical format to a getaddrbyname response structure.</P
 143 ><P
 144 >These structures are defined in
 145 <TT
 146 CLASS="FILENAME"
 147 >&lt;lwres/lwres.h&gt;</TT
 148 >.
 149 They are shown below.
 150 <PRE
 151 CLASS="PROGRAMLISTING"
 152 >#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 153
 154 typedef struct lwres_addr lwres_addr_t;
 155 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 156
 157 typedef struct {
 158         lwres_uint32_t  flags;
 159         lwres_uint32_t  addrtypes;
 160         lwres_uint16_t  namelen;
 161         char           *name;
 162 } lwres_gabnrequest_t;
 163
 164 typedef struct {
 165         lwres_uint32_t          flags;
 166         lwres_uint16_t          naliases;
 167         lwres_uint16_t          naddrs;
 168         char                   *realname;
 169         char                  **aliases;
 170         lwres_uint16_t          realnamelen;
 171         lwres_uint16_t         *aliaslen;
 172         lwres_addrlist_t        addrs;
 173         void                   *base;
 174         size_t                  baselen;
 175 } lwres_gabnresponse_t;</PRE
 176 ></P
 177 ><P
 178 ><TT
 179 CLASS="FUNCTION"
 180 >lwres_gabnrequest_render()</TT
 181 >
 182 uses resolver context
 183 <TT
 184 CLASS="PARAMETER"
 185 ><I
 186 >ctx</I
 187 ></TT
 188 >
 189 to convert getaddrbyname request structure
 190 <TT
 191 CLASS="PARAMETER"
 192 ><I
 193 >req</I
 194 ></TT
 195 >
 196 to canonical format.
 197 The packet header structure
 198 <TT
 199 CLASS="PARAMETER"
 200 ><I
 201 >pkt</I
 202 ></TT
 203 >
 204 is initialised and transferred to
 205 buffer
 206 <TT
 207 CLASS="PARAMETER"
 208 ><I
 209 >b</I
 210 ></TT
 211 >.
 212
 213 The contents of
 214 <TT
 215 CLASS="PARAMETER"
 216 ><I
 217 >*req</I
 218 ></TT
 219 >
 220 are then appended to the buffer in canonical format.
 221 <TT
 222 CLASS="FUNCTION"
 223 >lwres_gabnresponse_render()</TT
 224 >
 225 performs the same task, except it converts a getaddrbyname response structure
 226 <SPAN
 227 CLASS="TYPE"
 228 >lwres_gabnresponse_t</SPAN
 229 >
 230 to the lightweight resolver's canonical format.</P
 231 ><P
 232 ><TT
 233 CLASS="FUNCTION"
 234 >lwres_gabnrequest_parse()</TT
 235 >
 236 uses context
 237 <TT
 238 CLASS="PARAMETER"
 239 ><I
 240 >ctx</I
 241 ></TT
 242 >
 243 to convert the contents of packet
 244 <TT
 245 CLASS="PARAMETER"
 246 ><I
 247 >pkt</I
 248 ></TT
 249 >
 250 to a
 251 <SPAN
 252 CLASS="TYPE"
 253 >lwres_gabnrequest_t</SPAN
 254 >
 255 structure.
 256 Buffer
 257 <TT
 258 CLASS="PARAMETER"
 259 ><I
 260 >b</I
 261 ></TT
 262 >
 263 provides space to be used for storing this structure.
 264 When the function succeeds, the resulting
 265 <SPAN
 266 CLASS="TYPE"
 267 >lwres_gabnrequest_t</SPAN
 268 >
 269 is made available through
 270 <TT
 271 CLASS="PARAMETER"
 272 ><I
 273 >*structp</I
 274 ></TT
 275 >.
 276
 277 <TT
 278 CLASS="FUNCTION"
 279 >lwres_gabnresponse_parse()</TT
 280 >
 281 offers the same semantics as
 282 <TT
 283 CLASS="FUNCTION"
 284 >lwres_gabnrequest_parse()</TT
 285 >
 286 except it yields a
 287 <SPAN
 288 CLASS="TYPE"
 289 >lwres_gabnresponse_t</SPAN
 290 >
 291 structure.</P
 292 ><P
 293 ><TT
 294 CLASS="FUNCTION"
 295 >lwres_gabnresponse_free()</TT
 296 >
 297 and
 298 <TT
 299 CLASS="FUNCTION"
 300 >lwres_gabnrequest_free()</TT
 301 >
 302 release the memory in resolver context
 303 <TT
 304 CLASS="PARAMETER"
 305 ><I
 306 >ctx</I
 307 ></TT
 308 >
 309 that was allocated to the
 310 <SPAN
 311 CLASS="TYPE"
 312 >lwres_gabnresponse_t</SPAN
 313 >
 314 or
 315 <SPAN
 316 CLASS="TYPE"
 317 >lwres_gabnrequest_t</SPAN
 318 >
 319 structures referenced via
 320 <TT
 321 CLASS="PARAMETER"
 322 ><I
 323 >structp</I
 324 ></TT
 325 >.
 326
 327 Any memory associated with ancillary buffers and strings for those
 328 structures is also discarded.</P
 329 ></DIV
 330 ><DIV
 331 CLASS="REFSECT1"
 332 ><A
 333 NAME="AEN93"
 334 ></A
 335 ><H2
 336 >RETURN VALUES</H2
 337 ><P
 338 >The getaddrbyname opcode functions
 339 <TT
 340 CLASS="FUNCTION"
 341 >lwres_gabnrequest_render()</TT
 342 >,
 343 <TT
 344 CLASS="FUNCTION"
 345 >lwres_gabnresponse_render()</TT
 346 >
 347 <TT
 348 CLASS="FUNCTION"
 349 >lwres_gabnrequest_parse()</TT
 350 >
 351 and
 352 <TT
 353 CLASS="FUNCTION"
 354 >lwres_gabnresponse_parse()</TT
 355 >
 356 all return
 357 <SPAN
 358 CLASS="ERRORCODE"
 359 >LWRES_R_SUCCESS</SPAN
 360 >
 361 on success.
 362 They return
 363 <SPAN
 364 CLASS="ERRORCODE"
 365 >LWRES_R_NOMEMORY</SPAN
 366 >
 367 if memory allocation fails.
 368 <SPAN
 369 CLASS="ERRORCODE"
 370 >LWRES_R_UNEXPECTEDEND</SPAN
 371 >
 372 is returned if the available space in the buffer
 373 <TT
 374 CLASS="PARAMETER"
 375 ><I
 376 >b</I
 377 ></TT
 378 >
 379 is too small to accommodate the packet header or the
 380 <SPAN
 381 CLASS="TYPE"
 382 >lwres_gabnrequest_t</SPAN
 383 >
 384 and
 385 <SPAN
 386 CLASS="TYPE"
 387 >lwres_gabnresponse_t</SPAN
 388 >
 389 structures.
 390 <TT
 391 CLASS="FUNCTION"
 392 >lwres_gabnrequest_parse()</TT
 393 >
 394 and
 395 <TT
 396 CLASS="FUNCTION"
 397 >lwres_gabnresponse_parse()</TT
 398 >
 399 will return
 400 <SPAN
 401 CLASS="ERRORCODE"
 402 >LWRES_R_UNEXPECTEDEND</SPAN
 403 >
 404 if the buffer is not empty after decoding the received packet.
 405 These functions will return
 406 <SPAN
 407 CLASS="ERRORCODE"
 408 >LWRES_R_FAILURE</SPAN
 409 >
 410 if
 411 <TT
 412 CLASS="STRUCTFIELD"
 413 ><I
 414 >pktflags</I
 415 ></TT
 416 >
 417 in the packet header structure
 418 <SPAN
 419 CLASS="TYPE"
 420 >lwres_lwpacket_t</SPAN
 421 >
 422 indicate that the packet is not a response to an earlier query.</P
 423 ></DIV
 424 ><DIV
 425 CLASS="REFSECT1"
 426 ><A
 427 NAME="AEN112"
 428 ></A
 429 ><H2
 430 >SEE ALSO</H2
 431 ><P
 432 ><SPAN
 433 CLASS="CITEREFENTRY"
 434 ><SPAN
 435 CLASS="REFENTRYTITLE"
 436 >lwres_packet</SPAN
 437 >(3)</SPAN
 438 ></P
 439 ></DIV
 440 ></BODY
 441 ></HTML
 442 >