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