contrib/bind-9.2.4rc7/lib/lwres/man/lwres_noop.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_noop.html,v 1.7.2.2 2004/03/15 04:45:04 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres_noop</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_noop</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free&nbsp;--&nbsp;lightweight resolver no-op 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_nooprequest_render</CODE
  71 >(lwres_context_t *ctx, lwres_nooprequest_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_noopresponse_render</CODE
  79 >(lwres_context_t *ctx, lwres_noopresponse_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_nooprequest_parse</CODE
  87 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);</CODE
  88 ></P
  89 ><P
  90 ><CODE
  91 ><CODE
  92 CLASS="FUNCDEF"
  93 >lwres_result_t
  94 lwres_noopresponse_parse</CODE
  95 >(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp);</CODE
  96 ></P
  97 ><P
  98 ><CODE
  99 ><CODE
 100 CLASS="FUNCDEF"
 101 >void
 102 lwres_noopresponse_free</CODE
 103 >(lwres_context_t *ctx, lwres_noopresponse_t **structp);</CODE
 104 ></P
 105 ><P
 106 ><CODE
 107 ><CODE
 108 CLASS="FUNCDEF"
 109 >void
 110 lwres_nooprequest_free</CODE
 111 >(lwres_context_t *ctx, lwres_nooprequest_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 no-op request and response messages.</P
 127 ><P
 128 >The no-op message is analogous to a <B
 129 CLASS="COMMAND"
 130 >ping</B
 131 > packet:
 132 a packet is sent to the resolver daemon and is simply echoed back.
 133 The opcode is intended to allow a client to determine if the server is
 134 operational or not.</P
 135 ><P
 136 >There are four main functions for the no-op opcode.
 137 One render function converts a no-op request structure &mdash;
 138 <SPAN
 139 CLASS="TYPE"
 140 >lwres_nooprequest_t</SPAN
 141 > &mdash;
 142 to the lighweight resolver's canonical format.
 143 It is complemented by a parse function that converts a packet in this
 144 canonical format to a no-op request structure.
 145 Another render function converts the no-op response structure &mdash;
 146 <SPAN
 147 CLASS="TYPE"
 148 >lwres_noopresponse_t</SPAN
 149 >
 150 to the canonical format.
 151 This is complemented by a parse function which converts a packet in
 152 canonical format to a no-op response structure.</P
 153 ><P
 154 >These structures are defined in
 155 <TT
 156 CLASS="FILENAME"
 157 >lwres/lwres.h</TT
 158 >.
 159
 160 They are shown below.
 161 <PRE
 162 CLASS="PROGRAMLISTING"
 163 >#define LWRES_OPCODE_NOOP       0x00000000U
 164
 165 typedef struct {
 166         lwres_uint16_t  datalength;
 167         unsigned char   *data;
 168 } lwres_nooprequest_t;
 169
 170 typedef struct {
 171         lwres_uint16_t  datalength;
 172         unsigned char   *data;
 173 } lwres_noopresponse_t;</PRE
 174 >
 175 Although the structures have different types, they are identical.
 176 This is because the no-op opcode simply echos whatever data was sent:
 177 the response is therefore identical to the request.</P
 178 ><P
 179 ><TT
 180 CLASS="FUNCTION"
 181 >lwres_nooprequest_render()</TT
 182 > uses resolver
 183 context <TT
 184 CLASS="PARAMETER"
 185 ><I
 186 >ctx</I
 187 ></TT
 188 > to convert no-op request structure
 189 <TT
 190 CLASS="PARAMETER"
 191 ><I
 192 >req</I
 193 ></TT
 194 > to canonical format.  The packet header
 195 structure <TT
 196 CLASS="PARAMETER"
 197 ><I
 198 >pkt</I
 199 ></TT
 200 > is initialised and transferred to
 201 buffer <TT
 202 CLASS="PARAMETER"
 203 ><I
 204 >b</I
 205 ></TT
 206 >.  The contents of
 207 <TT
 208 CLASS="PARAMETER"
 209 ><I
 210 >*req</I
 211 ></TT
 212 > are then appended to the buffer in
 213 canonical format.  <TT
 214 CLASS="FUNCTION"
 215 >lwres_noopresponse_render()</TT
 216 >
 217 performs the same task, except it converts a no-op response structure
 218 <SPAN
 219 CLASS="TYPE"
 220 >lwres_noopresponse_t</SPAN
 221 > to the lightweight resolver's
 222 canonical format.</P
 223 ><P
 224 ><TT
 225 CLASS="FUNCTION"
 226 >lwres_nooprequest_parse()</TT
 227 > uses context
 228 <TT
 229 CLASS="PARAMETER"
 230 ><I
 231 >ctx</I
 232 ></TT
 233 > to convert the contents of packet
 234 <TT
 235 CLASS="PARAMETER"
 236 ><I
 237 >pkt</I
 238 ></TT
 239 > to a <SPAN
 240 CLASS="TYPE"
 241 >lwres_nooprequest_t</SPAN
 242 >
 243 structure.  Buffer <TT
 244 CLASS="PARAMETER"
 245 ><I
 246 >b</I
 247 ></TT
 248 > provides space to be used
 249 for storing this structure.  When the function succeeds, the resulting
 250 <SPAN
 251 CLASS="TYPE"
 252 >lwres_nooprequest_t</SPAN
 253 > is made available through
 254 <TT
 255 CLASS="PARAMETER"
 256 ><I
 257 >*structp</I
 258 ></TT
 259 >.
 260 <TT
 261 CLASS="FUNCTION"
 262 >lwres_noopresponse_parse()</TT
 263 > offers the same
 264 semantics as <TT
 265 CLASS="FUNCTION"
 266 >lwres_nooprequest_parse()</TT
 267 > except it
 268 yields a <SPAN
 269 CLASS="TYPE"
 270 >lwres_noopresponse_t</SPAN
 271 > structure.</P
 272 ><P
 273 ><TT
 274 CLASS="FUNCTION"
 275 >lwres_noopresponse_free()</TT
 276 > and
 277 <TT
 278 CLASS="FUNCTION"
 279 >lwres_nooprequest_free()</TT
 280 > release the memory in
 281 resolver context <TT
 282 CLASS="PARAMETER"
 283 ><I
 284 >ctx</I
 285 ></TT
 286 > that was allocated to the
 287 <SPAN
 288 CLASS="TYPE"
 289 >lwres_noopresponse_t</SPAN
 290 > or <SPAN
 291 CLASS="TYPE"
 292 >lwres_nooprequest_t</SPAN
 293 >
 294 structures referenced via <TT
 295 CLASS="PARAMETER"
 296 ><I
 297 >structp</I
 298 ></TT
 299 >.</P
 300 ></DIV
 301 ><DIV
 302 CLASS="REFSECT1"
 303 ><A
 304 NAME="AEN95"
 305 ></A
 306 ><H2
 307 >RETURN VALUES</H2
 308 ><P
 309 >The no-op opcode functions
 310 <TT
 311 CLASS="FUNCTION"
 312 >lwres_nooprequest_render()</TT
 313 >,
 314
 315 <TT
 316 CLASS="FUNCTION"
 317 >lwres_noopresponse_render()</TT
 318 >
 319 <TT
 320 CLASS="FUNCTION"
 321 >lwres_nooprequest_parse()</TT
 322 >
 323 and
 324 <TT
 325 CLASS="FUNCTION"
 326 >lwres_noopresponse_parse()</TT
 327 >
 328 all return
 329 <SPAN
 330 CLASS="ERRORCODE"
 331 >LWRES_R_SUCCESS</SPAN
 332 >
 333 on success.
 334 They return
 335 <SPAN
 336 CLASS="ERRORCODE"
 337 >LWRES_R_NOMEMORY</SPAN
 338 >
 339 if memory allocation fails.
 340 <SPAN
 341 CLASS="ERRORCODE"
 342 >LWRES_R_UNEXPECTEDEND</SPAN
 343 >
 344 is returned if the available space in the buffer
 345 <TT
 346 CLASS="PARAMETER"
 347 ><I
 348 >b</I
 349 ></TT
 350 >
 351 is too small to accommodate the packet header or the
 352 <SPAN
 353 CLASS="TYPE"
 354 >lwres_nooprequest_t</SPAN
 355 >
 356 and
 357 <SPAN
 358 CLASS="TYPE"
 359 >lwres_noopresponse_t</SPAN
 360 >
 361 structures.
 362 <TT
 363 CLASS="FUNCTION"
 364 >lwres_nooprequest_parse()</TT
 365 >
 366 and
 367 <TT
 368 CLASS="FUNCTION"
 369 >lwres_noopresponse_parse()</TT
 370 >
 371 will return
 372 <SPAN
 373 CLASS="ERRORCODE"
 374 >LWRES_R_UNEXPECTEDEND</SPAN
 375 >
 376 if the buffer is not empty after decoding the received packet.
 377 These functions will return
 378 <SPAN
 379 CLASS="ERRORCODE"
 380 >LWRES_R_FAILURE</SPAN
 381 >
 382 if
 383 <TT
 384 CLASS="CONSTANT"
 385 >pktflags</TT
 386 >
 387 in the packet header structure
 388 <SPAN
 389 CLASS="TYPE"
 390 >lwres_lwpacket_t</SPAN
 391 >
 392 indicate that the packet is not a response to an earlier query.</P
 393 ></DIV
 394 ><DIV
 395 CLASS="REFSECT1"
 396 ><A
 397 NAME="AEN114"
 398 ></A
 399 ><H2
 400 >SEE ALSO</H2
 401 ><P
 402 ><SPAN
 403 CLASS="CITEREFENTRY"
 404 ><SPAN
 405 CLASS="REFENTRYTITLE"
 406 >lwres_packet</SPAN
 407 >(3)</SPAN
 408 ></P
 409 ></DIV
 410 ></BODY
 411 ></HTML
 412 >