lwres_noop.docbook revision ec5347e2c775f027573ce5648b910361aa926c01
adb8c5e5291be5943122bbff404bc1018c79d555ianh<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
910df8b3f50a0515b430b999d4750de94c509f2atrawick "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
910df8b3f50a0515b430b999d4750de94c509f2atrawick [<!ENTITY mdash "—">]>
910df8b3f50a0515b430b999d4750de94c509f2atrawick - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
910df8b3f50a0515b430b999d4750de94c509f2atrawick - Copyright (C) 2000, 2001 Internet Software Consortium.
0d628dd174dd6de13463b10d2599f6cac24e9fe8brianp - Permission to use, copy, modify, and/or distribute this software for any
0d628dd174dd6de13463b10d2599f6cac24e9fe8brianp - purpose with or without fee is hereby granted, provided that the above
2fee4fe267fa3577fd71d8c314fe9b527e2b90c0brianp - copyright notice and this permission notice appear in all copies.
2fee4fe267fa3577fd71d8c314fe9b527e2b90c0brianp - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
2fee4fe267fa3577fd71d8c314fe9b527e2b90c0brianp - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
7bf77d70b6830636bc36e6b76a228c301be23ff7brianp - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
7bf77d70b6830636bc36e6b76a228c301be23ff7brianp - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
7bf77d70b6830636bc36e6b76a228c301be23ff7brianp - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
185b73b1f914e5d8f99f31225cc656b882dcbf73ianh - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
6ef713e25735887d4a59a879b97a68bd575ecb92trawick - PERFORMANCE OF THIS SOFTWARE.
cef5cb47e2ea4c174c01762d4430613db0f41e5cstoddard<!-- $Id: lwres_noop.docbook,v 1.11 2007/06/18 23:47:51 tbox Exp $ -->
8abd60101b9794e224795ccf68b8ba984efbc94astoddard <refentryinfo>
ca47a2b6bcea23e8af185c68f256dcbbfd2a0f9dtrawick </refentryinfo>
2b31ac2c6342d2afcf67b7b0f08c928a87f98c74wrowe <copyright>
d472f67198d6b15dd1270136f180cca9c9263243trawick <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
d472f67198d6b15dd1270136f180cca9c9263243trawick </copyright>
d472f67198d6b15dd1270136f180cca9c9263243trawick <copyright>
a3bb95a3600153c7f09f62749e32093658943c32brianp </copyright>
b760518cc17e7124ba546ed63063603f1ab82a40aaron <refnamediv>
23d8f62856c1531526042e1c5edf44557cadd2e5trawick <refpurpose>lightweight resolver no-op message handling</refpurpose>
23d8f62856c1531526042e1c5edf44557cadd2e5trawick </refnamediv>
705c8ed3ef608706c91ca12483d7b54ff9007cc9jerenkrantz <refsynopsisdiv>
705c8ed3ef608706c91ca12483d7b54ff9007cc9jerenkrantz <funcsynopsis>
705c8ed3ef608706c91ca12483d7b54ff9007cc9jerenkrantz<funcsynopsisinfo>
ef154948c97c53cdc1ad5329cb83c32ad26cf416aaron<funcprototype>
c6741d11357aace4c9ba39535d3cb2d751f46114trawicklwres_result_t
c6741d11357aace4c9ba39535d3cb2d751f46114trawick<function>lwres_nooprequest_render</function></funcdef>
c6741d11357aace4c9ba39535d3cb2d751f46114trawick <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
c6741d11357aace4c9ba39535d3cb2d751f46114trawick <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
7230f1eb017a35b7d20e0e9ec0d234766f2a732dtrawick <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
7230f1eb017a35b7d20e0e9ec0d234766f2a732dtrawick <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawick </funcprototype>
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawick<funcprototype>
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawicklwres_result_t
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawick<function>lwres_noopresponse_render</function></funcdef>
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawick <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
86a5d34400b7f586ad2cca97c8b33b2f55bac61btrawick <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
6b477c0a238733ca8fd156629310513d29dc7e02trawick <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
6b477c0a238733ca8fd156629310513d29dc7e02trawick <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
6b477c0a238733ca8fd156629310513d29dc7e02trawick </funcprototype>
6b477c0a238733ca8fd156629310513d29dc7e02trawick<funcprototype>
2b31ac2c6342d2afcf67b7b0f08c928a87f98c74wrowelwres_result_t
557eb8d48357657fa898250560f089c65539c634gregames<function>lwres_nooprequest_parse</function></funcdef>
557eb8d48357657fa898250560f089c65539c634gregames <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
557eb8d48357657fa898250560f089c65539c634gregames <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
adb8c5e5291be5943122bbff404bc1018c79d555ianh <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
25b715e9687f82ea055fdea2a9761c7e5f1ac6eetrawick <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
25b715e9687f82ea055fdea2a9761c7e5f1ac6eetrawick </funcprototype>
25b715e9687f82ea055fdea2a9761c7e5f1ac6eetrawick<funcprototype>
51ced3b28ef430a96586284d4320f7dbdaf7225ebrianplwres_result_t
51ced3b28ef430a96586284d4320f7dbdaf7225ebrianp<function>lwres_noopresponse_parse</function></funcdef>
51ced3b28ef430a96586284d4320f7dbdaf7225ebrianp <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a222035458f89e2db231450ba6d5fae8052da5f5aaron <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
a222035458f89e2db231450ba6d5fae8052da5f5aaron <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
a222035458f89e2db231450ba6d5fae8052da5f5aaron <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
a222035458f89e2db231450ba6d5fae8052da5f5aaron </funcprototype>
4a872628ca5bf20847f442a625c255b643120db0wrowe<funcprototype>
74528257888620220641cd28366731539a37e1f3ianh <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
74528257888620220641cd28366731539a37e1f3ianh <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
0cc82c261350ab8dc8a9992cad7197c4d22d597eianh </funcprototype>
f2afeedf074acc1a698a9527154eacd138e6c5a1trawick<funcprototype>
855e263a93fde2e30d10a48a9ffc047039bfc9d9brianp <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
54b3b7946d22324cea615d7c8a4ff0c9eadd1f8crbb <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
54b3b7946d22324cea615d7c8a4ff0c9eadd1f8crbb </funcprototype>
54b3b7946d22324cea615d7c8a4ff0c9eadd1f8crbb</funcsynopsis>
54b3b7946d22324cea615d7c8a4ff0c9eadd1f8crbb </refsynopsisdiv>
54b3b7946d22324cea615d7c8a4ff0c9eadd1f8crbb <refsect1>
e28c02dc08247d3fcb71e81791cac2311a248dfdrbb These are low-level routines for creating and parsing
e28c02dc08247d3fcb71e81791cac2311a248dfdrbb lightweight resolver no-op request and response messages.
e28c02dc08247d3fcb71e81791cac2311a248dfdrbb The no-op message is analogous to a <command>ping</command>
f9f506f0686ad065b4c6fe14dd962cdd478350dbianh a packet is sent to the resolver daemon and is simply echoed back.
f9f506f0686ad065b4c6fe14dd962cdd478350dbianh The opcode is intended to allow a client to determine if the server is
9d0665da83d1e22c0ea0e5f6f940f70f75bf5237ianh operational or not.
9d0665da83d1e22c0ea0e5f6f940f70f75bf5237ianh There are four main functions for the no-op opcode.
9d0665da83d1e22c0ea0e5f6f940f70f75bf5237ianh One render function converts a no-op request structure —
47c2fb4c1f155ddb6954e46e7f6d125eef78b3bbaaron to the lighweight resolver's canonical format.
47c2fb4c1f155ddb6954e46e7f6d125eef78b3bbaaron It is complemented by a parse function that converts a packet in this
47c2fb4c1f155ddb6954e46e7f6d125eef78b3bbaaron canonical format to a no-op request structure.
9ca934cec0a1cc3c425fde5dc51956bce6cd3183brianp Another render function converts the no-op response structure —
9ca934cec0a1cc3c425fde5dc51956bce6cd3183brianp to the canonical format.
0cdca1e056a05a09fe16fe736abcf79969c9767ejerenkrantz This is complemented by a parse function which converts a packet in
0cdca1e056a05a09fe16fe736abcf79969c9767ejerenkrantz canonical format to a no-op response structure.
f2afeedf074acc1a698a9527154eacd138e6c5a1trawick These structures are defined in
0a2d57d962bef3a8898723925b3fb02d2e836994dougm They are shown below.
06461d67f387ea068187e6dfa036875a8205c04cjerenkrantz#define LWRES_OPCODE_NOOP 0x00000000U
900127764fb985c340ee4979cac97146a330c694trawick</programlisting>
1a6a0072a95887164091e366ba0e89c2b39a954abrianptypedef struct {
1a6a0072a95887164091e366ba0e89c2b39a954abrianp lwres_uint16_t datalength;
6f4c27ba6e152792f3729069e8d8313ebc87cc60jwoolley unsigned char *data;
6f4c27ba6e152792f3729069e8d8313ebc87cc60jwoolley} lwres_nooprequest_t;
6f4c27ba6e152792f3729069e8d8313ebc87cc60jwoolley</programlisting>
23ce412bd50a47accab4dd26019b78810bbf46ebtrawicktypedef struct {
6865813dee5d3c1ebf12dd810368171792a0190atrawick lwres_uint16_t datalength;
6865813dee5d3c1ebf12dd810368171792a0190atrawick unsigned char *data;
6865813dee5d3c1ebf12dd810368171792a0190atrawick} lwres_noopresponse_t;
97719ad970d779ac48af9364ab0ea9fdcc27470ajwoolley</programlisting>
5ad238c42b1e159ee8f164515e0c4ee6c727c2fdtrawick Although the structures have different types, they are identical.
5ad238c42b1e159ee8f164515e0c4ee6c727c2fdtrawick This is because the no-op opcode simply echos whatever data was sent:
5ad238c42b1e159ee8f164515e0c4ee6c727c2fdtrawick the response is therefore identical to the request.
ba00c3b7c20f00ce631b89ae3b1cd3bae8d1b165rbb uses resolver context <parameter>ctx</parameter> to convert
ba00c3b7c20f00ce631b89ae3b1cd3bae8d1b165rbb no-op request structure <parameter>req</parameter> to canonical
ba00c3b7c20f00ce631b89ae3b1cd3bae8d1b165rbb format. The packet header structure <parameter>pkt</parameter>
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb is initialised and transferred to buffer
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb <parameter>*req</parameter> are then appended to the buffer in
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb canonical format.
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb <function>lwres_noopresponse_render()</function> performs the
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb same task, except it converts a no-op response structure
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb <type>lwres_noopresponse_t</type> to the lightweight resolver's
6e954603b02f2b7d4ad80af17d9b3cc6f0bacf69rbb canonical format.
fa449f5bc87c5d87c4c60e778c9c882e7254de7ejwoolley <para><function>lwres_nooprequest_parse()</function>
fa449f5bc87c5d87c4c60e778c9c882e7254de7ejwoolley uses context <parameter>ctx</parameter> to convert the contents
227d23a7db41dd89f52391c9356dbb1adcd675e0jwoolley <parameter>b</parameter> provides space to be used for storing
227d23a7db41dd89f52391c9356dbb1adcd675e0jwoolley this structure. When the function succeeds, the resulting
227d23a7db41dd89f52391c9356dbb1adcd675e0jwoolley <type>lwres_nooprequest_t</type> is made available through
227d23a7db41dd89f52391c9356dbb1adcd675e0jwoolley <function>lwres_noopresponse_parse()</function> offers the same
227d23a7db41dd89f52391c9356dbb1adcd675e0jwoolley semantics as <function>lwres_nooprequest_parse()</function>
1c0b7c3bdace07946457fa7ba04b7f97b6599792rbb except it yields a <type>lwres_noopresponse_t</type> structure.
17bc0e8f2e3816e25bc8fd3fadf39357340aebd0jerenkrantz <para><function>lwres_noopresponse_free()</function>
17bc0e8f2e3816e25bc8fd3fadf39357340aebd0jerenkrantz and <function>lwres_nooprequest_free()</function> release the
17bc0e8f2e3816e25bc8fd3fadf39357340aebd0jerenkrantz memory in resolver context <parameter>ctx</parameter> that was
e6cc28a5eb3371ba0c38e941855e71ff0054f50erbb <type>lwres_nooprequest_t</type> structures referenced via
e6cc28a5eb3371ba0c38e941855e71ff0054f50erbb </refsect1>
e6cc28a5eb3371ba0c38e941855e71ff0054f50erbb <refsect1>
cf233fb4b439415a2bf7bab7e622afd994e0bebftrawick The no-op opcode functions
2a20a2f8432a15b530e0a6b0998c32f40aef82a8gregames on success.
2a20a2f8432a15b530e0a6b0998c32f40aef82a8gregames They return
2a20a2f8432a15b530e0a6b0998c32f40aef82a8gregames if memory allocation fails.
2a20a2f8432a15b530e0a6b0998c32f40aef82a8gregames is returned if the available space in the buffer
f99bffd6087564cf9c05cc29d1c6b38d94e0ed30gregames is too small to accommodate the packet header or the
8458877c9ba0af86acd590eea531476adde3d02dmartin structures.
8458877c9ba0af86acd590eea531476adde3d02dmartin will return
644be6f54749d2d9950d2c4d2ac448f7af016d26martin if the buffer is not empty after decoding the received packet.
644be6f54749d2d9950d2c4d2ac448f7af016d26martin These functions will return
b30b04f639d479b96cc08c43ffa34c92ba275676ianh in the packet header structure
c4fbc4018fd2b6716673a38ee27eeb36cba41c5djwoolley indicate that the packet is not a response to an earlier query.
c4fbc4018fd2b6716673a38ee27eeb36cba41c5djwoolley </refsect1>
f4e4643c309e5b5da60e13f9a25984d54b307caawrowe <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
2548497d480c4f3e9b3fe14711bd510aa2157434gregames </citerefentry>
2548497d480c4f3e9b3fe14711bd510aa2157434gregames </refsect1>
0e58e92812f2f679d6bf2ff66cbcfa6c1d1e14bbjerenkrantz - Local variables:
da6e93dca0222159650783802e23172e3160605egregames - mode: sgml