lwres_noop.docbook revision 194e2dfffa6a167b8eef0ad11864026b423a1c30
279c6ec074be17dce62dd1b2c6ed7c2cc56a7b78David Lawrence<!ENTITY mdash "—">]>
281bfa2a98f1d1721538086e1b550185559f1d8bMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
7de2c6e6d51f38daeb2d346f3f21dc01ccece6daEvan Hunt - This Source Code Form is subject to the terms of the Mozilla Public
279c6ec074be17dce62dd1b2c6ed7c2cc56a7b78David Lawrence - License, v. 2.0. If a copy of the MPL was not distributed with this
279c6ec074be17dce62dd1b2c6ed7c2cc56a7b78David Lawrence - file, You can obtain one at http://mozilla.org/MPL/2.0/.
281bfa2a98f1d1721538086e1b550185559f1d8bMark Andrews<!-- Converted by db4-upgrade version 1.0 -->
281bfa2a98f1d1721538086e1b550185559f1d8bMark Andrews<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
281bfa2a98f1d1721538086e1b550185559f1d8bMark Andrews <refentryinfo>
279c6ec074be17dce62dd1b2c6ed7c2cc56a7b78David Lawrence <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
588f79e557cd66ef77c90378a997b0d377af9db7Tatuya JINMEI 神明達哉 </refentryinfo>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
8d4257cff01b3821abcb9a21f46c6c6a43bb1e72Bob Halley <refnamediv>
7005cfed8cd3296d356883dcb414979f22e06b13Brian Wellington <refpurpose>lightweight resolver no-op message handling</refpurpose>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refnamediv>
6f7660093e70d3a7c80738b681ac0f5c1b661c00Mark Andrews <refsynopsisdiv>
6f7660093e70d3a7c80738b681ac0f5c1b661c00Mark Andrews <funcsynopsis>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcsynopsisinfo>
d8dcd6ad4617cc8d7df979bd62101fa9c4bac1bcBob Halley<funcprototype>
baf7c7e589f313f10b29d9119811fc4d36c2e4bcMark Andrewslwres_result_t
baf7c7e589f313f10b29d9119811fc4d36c2e4bcMark Andrews<function>lwres_nooprequest_render</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a30e7fc23415fd238d067a8a871607bca36068baMichael Graff <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
a30e7fc23415fd238d067a8a871607bca36068baMichael Graff <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
6286983c506433d642b23e64845c50be30f2a7f6Mark Andrews </funcprototype>
6286983c506433d642b23e64845c50be30f2a7f6Mark Andrews<funcprototype>
8313838954d67250d0ed7edf67fba5da0790d1a7Michael Grafflwres_result_t
8313838954d67250d0ed7edf67fba5da0790d1a7Michael Graff<function>lwres_noopresponse_render</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
8313838954d67250d0ed7edf67fba5da0790d1a7Michael Graff <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
8313838954d67250d0ed7edf67fba5da0790d1a7Michael Graff <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
703e1c0bb66f3cd3d300358ca0c1fdf3cb5fb1c5Brian Wellington </funcprototype>
703e1c0bb66f3cd3d300358ca0c1fdf3cb5fb1c5Brian Wellington<funcprototype>
b15c543f7957fbb4284f0fc20b3278f2a411d272Mark Andrewslwres_result_t
b15c543f7957fbb4284f0fc20b3278f2a411d272Mark Andrews<function>lwres_nooprequest_parse</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
0eb2572d79822d02ea05448ce4e5f1759c73d171Michael Graff <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
0eb2572d79822d02ea05448ce4e5f1759c73d171Michael Graff <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
0eb2572d79822d02ea05448ce4e5f1759c73d171Michael Graff </funcprototype>
0eb2572d79822d02ea05448ce4e5f1759c73d171Michael Graff<funcprototype>
4108eed5092156cf0407a97a9bd8ab7775164694Brian Wellingtonlwres_result_t
4108eed5092156cf0407a97a9bd8ab7775164694Brian Wellington<function>lwres_noopresponse_parse</function></funcdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
3f123dcc2fe5d2cd08ca91b732741d86a4036906Brian Wellington <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
3f123dcc2fe5d2cd08ca91b732741d86a4036906Brian Wellington <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
64b92523f9333ba053f4b2860335583be455b0b3Brian Wellington </funcprototype>
64b92523f9333ba053f4b2860335583be455b0b3Brian Wellington<funcprototype>
876753d5ce1be48f3218fb4875fac501f8adfd6cDavid Lawrence<function>lwres_noopresponse_free</function></funcdef>
876753d5ce1be48f3218fb4875fac501f8adfd6cDavid Lawrence <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
876753d5ce1be48f3218fb4875fac501f8adfd6cDavid Lawrence <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
876753d5ce1be48f3218fb4875fac501f8adfd6cDavid Lawrence </funcprototype>
876753d5ce1be48f3218fb4875fac501f8adfd6cDavid Lawrence<funcprototype>
ed71ea51c6ecb5d7d659b6e6a20f6b3f5c2678c6David Lawrence<function>lwres_nooprequest_free</function></funcdef>
ed71ea51c6ecb5d7d659b6e6a20f6b3f5c2678c6David Lawrence <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ed71ea51c6ecb5d7d659b6e6a20f6b3f5c2678c6David Lawrence <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
ed71ea51c6ecb5d7d659b6e6a20f6b3f5c2678c6David Lawrence </funcprototype>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</funcsynopsis>
49a2cf8f211213712d452287ae8e121cf59e3178David Lawrence </refsynopsisdiv>
49a2cf8f211213712d452287ae8e121cf59e3178David Lawrence <refsection><info><title>DESCRIPTION</title></info>
49a2cf8f211213712d452287ae8e121cf59e3178David Lawrence These are low-level routines for creating and parsing
49a2cf8f211213712d452287ae8e121cf59e3178David Lawrence lightweight resolver no-op request and response messages.
49a2cf8f211213712d452287ae8e121cf59e3178David Lawrence The no-op message is analogous to a <command>ping</command>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews a packet is sent to the resolver daemon and is simply echoed back.
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews The opcode is intended to allow a client to determine if the server is
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews operational or not.
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews There are four main functions for the no-op opcode.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein One render function converts a no-op request structure —
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to the lightweight resolver's canonical format.
529ff4b4959fb157194f985394951108ff5286e4Brian Wellington It is complemented by a parse function that converts a packet in this
a14613fce99dee3cad5bf842fd6be78f8e463582Brian Wellington canonical format to a no-op request structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Another render function converts the no-op response structure —
489b76292622f5bc18bf1a18845f8166a73bd797Brian Wellington to the canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This is complemented by a parse function which converts a packet in
bff8ac12a8c099257bdbf7d0c55d2d5b77591926Mark Andrews canonical format to a no-op response structure.
fd837244be31850a764863688bce11df9ce972f4Andreas Gustafsson These structures are defined in
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews They are shown below.
cffc2e06f906dd048af4cc27d487deb157f5a082Mark Andrews#define LWRES_OPCODE_NOOP 0x00000000U
cffc2e06f906dd048af4cc27d487deb157f5a082Mark Andrews</programlisting>
43fe2897fc80bbec2115310ca79d432a252f3ea4Mark Andrewstypedef struct {
70e854766f5304f43e94212dc38ebaefe214148cMark Andrews lwres_uint16_t datalength;
70e854766f5304f43e94212dc38ebaefe214148cMark Andrews unsigned char *data;
70e854766f5304f43e94212dc38ebaefe214148cMark Andrews} lwres_nooprequest_t;
43501e6570e9081d459fb5c1a81b73c2c53c5df0Mark Andrews</programlisting>
43501e6570e9081d459fb5c1a81b73c2c53c5df0Mark Andrewstypedef struct {
2b66a51a7d72e9cc07917fb583ad528b0539d2a3Mark Andrews lwres_uint16_t datalength;
2b66a51a7d72e9cc07917fb583ad528b0539d2a3Mark Andrews unsigned char *data;
2b66a51a7d72e9cc07917fb583ad528b0539d2a3Mark Andrews} lwres_noopresponse_t;
8b56b8956fc1e6c70efacb4f71db28d0d1f0c577Mark Andrews</programlisting>
4e9775118dbf128dd296f01638733ba221f76c34Mark Andrews Although the structures have different types, they are identical.
4e9775118dbf128dd296f01638733ba221f76c34Mark Andrews This is because the no-op opcode simply echos whatever data was sent:
4e9775118dbf128dd296f01638733ba221f76c34Mark Andrews the response is therefore identical to the request.
9935447b51456f598b45246d0114b8006049244dMark Andrews <para><function>lwres_nooprequest_render()</function>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews uses resolver context <parameter>ctx</parameter> to convert
64b92523f9333ba053f4b2860335583be455b0b3Brian Wellington no-op request structure <parameter>req</parameter> to canonical
64b92523f9333ba053f4b2860335583be455b0b3Brian Wellington format. The packet header structure <parameter>pkt</parameter>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews is initialised and transferred to buffer
a5d43b72413db3edd6b36a58f9bdf2cf6ff692f2Bob Halley <parameter>*req</parameter> are then appended to the buffer in
289ae548d52bc8f982d9823af64cafda7bd92232Mark Andrews canonical format.
289ae548d52bc8f982d9823af64cafda7bd92232Mark Andrews <function>lwres_noopresponse_render()</function> performs the
289ae548d52bc8f982d9823af64cafda7bd92232Mark Andrews same task, except it converts a no-op response structure
289ae548d52bc8f982d9823af64cafda7bd92232Mark Andrews <type>lwres_noopresponse_t</type> to the lightweight resolver's
289ae548d52bc8f982d9823af64cafda7bd92232Mark Andrews canonical format.
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <para><function>lwres_nooprequest_parse()</function>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews uses context <parameter>ctx</parameter> to convert the contents
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <type>lwres_nooprequest_t</type> structure. Buffer
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <parameter>b</parameter> provides space to be used for storing
0415ca35ada2cac6a86127eaca64f3a997aea121Evan Hunt this structure. When the function succeeds, the resulting
0415ca35ada2cac6a86127eaca64f3a997aea121Evan Hunt <type>lwres_nooprequest_t</type> is made available through
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <function>lwres_noopresponse_parse()</function> offers the same
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews semantics as <function>lwres_nooprequest_parse()</function>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews except it yields a <type>lwres_noopresponse_t</type> structure.
d5518bf5bc1830f89f411288f39c5c9e6eb7511cMark Andrews <para><function>lwres_noopresponse_free()</function>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews and <function>lwres_nooprequest_free()</function> release the
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews memory in resolver context <parameter>ctx</parameter> that was
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews allocated to the <type>lwres_noopresponse_t</type> or
23ac30603a7639bea1d331537634b079b046b122Mark Andrews <type>lwres_nooprequest_t</type> structures referenced via
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews </refsection>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <refsection><info><title>RETURN VALUES</title></info>
c870001ae1bff0e38f622c4ed56872c7f1d2d336Mark Andrews The no-op opcode functions
186e7f37c9fc985a7a7264cc8170e48a25bed434Mark Andrews <function>lwres_nooprequest_render()</function>,
186e7f37c9fc985a7a7264cc8170e48a25bed434Mark Andrews <function>lwres_noopresponse_render()</function>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews if memory allocation fails.
9935447b51456f598b45246d0114b8006049244dMark Andrews is returned if the available space in the buffer
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews is too small to accommodate the packet header or the
38cd4d14cc341c2663e574035074788bb6f0fce2Evan Hunt if the buffer is not empty after decoding the received packet.
38cd4d14cc341c2663e574035074788bb6f0fce2Evan Hunt These functions will return
38cd4d14cc341c2663e574035074788bb6f0fce2Evan Hunt in the packet header structure
38cd4d14cc341c2663e574035074788bb6f0fce2Evan Hunt indicate that the packet is not a response to an earlier query.
38cd4d14cc341c2663e574035074788bb6f0fce2Evan Hunt </refsection>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews </citerefentry>
f54d0c9c6e65de367d4ef08f51d22a2fb4c56208Mark Andrews </refsection>