lwres_packet.docbook revision 938440694b33cd752e9e4b71a526368b4811c177
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
efe780dcf13b2b95effabf897d694d8f23feac74trawick [<!ENTITY mdash "—">]>
3f414998b6d7e96a9f699621352fc61516b1a316chrisd - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
3f414998b6d7e96a9f699621352fc61516b1a316chrisd - Copyright (C) 2000, 2001 Internet Software Consortium.
9d766f93eefb9358f9a24bb99ff424ad399b9b39minfrin - Permission to use, copy, modify, and/or distribute this software for any
9d766f93eefb9358f9a24bb99ff424ad399b9b39minfrin - purpose with or without fee is hereby granted, provided that the above
5725c3eb0c6c572049ba61dedd92b4e5da078081minfrin - copyright notice and this permission notice appear in all copies.
5725c3eb0c6c572049ba61dedd92b4e5da078081minfrin - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
5725c3eb0c6c572049ba61dedd92b4e5da078081minfrin - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1122585e1e00bb81e9d0f054bf5c318cec23aa7dminfrin - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
1122585e1e00bb81e9d0f054bf5c318cec23aa7dminfrin - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1122585e1e00bb81e9d0f054bf5c318cec23aa7dminfrin - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
fd292d721a12f04a14e7f2ce30545840c041c7d5trawick - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
fd292d721a12f04a14e7f2ce30545840c041c7d5trawick - PERFORMANCE OF THIS SOFTWARE.
b95471fea55df98d7a6946c2c1826d3e2b5beebcjim <refentryinfo>
b95471fea55df98d7a6946c2c1826d3e2b5beebcjim </refentryinfo>
2021e9833981f994f862e7157cb4b96cad797362trawick <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
efe780dcf13b2b95effabf897d694d8f23feac74trawick </copyright>
793214f67dede32edfd9ee96c664ead04d175cbbjfclere <copyright>
33124689065ade0dfc8c54d8ebb734f9439cb89btrawick </copyright>
3ccfc257819b3bad063cd3ac9dd1670d5d2ae4d2kbrand <refnamediv>
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener <refpurpose>lightweight resolver packet handling functions</refpurpose>
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener </refnamediv>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza <refsynopsisdiv>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza <funcsynopsis>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza<funcprototype>
56589be3d7a3e9343370df240010c6928cc78b39jkaluzalwres_result_t
56589be3d7a3e9343370df240010c6928cc78b39jkaluza<function>lwres_lwpacket_renderheader</function></funcdef>
8c4967445b49a1612b3f98c1dada65e597ecfe26trawick <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
8c4967445b49a1612b3f98c1dada65e597ecfe26trawick <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
8c4967445b49a1612b3f98c1dada65e597ecfe26trawick </funcprototype>
61fefed8ce5211c31b44f3a38a6e76ca055e5780trawick<funcprototype>
61fefed8ce5211c31b44f3a38a6e76ca055e5780trawicklwres_result_t
61fefed8ce5211c31b44f3a38a6e76ca055e5780trawick<function>lwres_lwpacket_parseheader</function></funcdef>
6001d914962deabb83a46251001612e969bdf67ajim <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
6001d914962deabb83a46251001612e969bdf67ajim <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
6001d914962deabb83a46251001612e969bdf67ajim </funcprototype>
c4e8006db0cf457c68876d7d4c30dcc451d8cba7jkaluza</funcsynopsis>
c4e8006db0cf457c68876d7d4c30dcc451d8cba7jkaluza </refsynopsisdiv>
652bacc79dd7f980249784cc8c4838e8f1de7e8acovener These functions rely on a
f4db898517ccc6ef1a403630de56918286d3a47eminfrin which is defined in
28a723b775c7666281298eab813c63ac42270f95humbedoohtypedef struct lwres_lwpacket lwres_lwpacket_t;
067698ad30941e38ef5d7f95f1c2736c2ebc5cb9humbedooh </programlisting>
7a437ce535a5fac890296402ba483c2f41bb6500trawickstruct lwres_lwpacket {
7a437ce535a5fac890296402ba483c2f41bb6500trawick lwres_uint32_t length;
7a437ce535a5fac890296402ba483c2f41bb6500trawick lwres_uint16_t version;
d8a6de5eec06d4136839c8f7a56a6ab5acd2d3behumbedooh lwres_uint16_t pktflags;
6e1e45624d6f32110383bb0bd06c254c1dba8123humbedooh lwres_uint32_t serial;
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc lwres_uint32_t opcode;
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc lwres_uint32_t result;
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc lwres_uint32_t recvlength;
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc lwres_uint16_t authtype;
921d32d80d8271da08f12fc374a69cb36d1d63b3covener lwres_uint16_t authlength;
921d32d80d8271da08f12fc374a69cb36d1d63b3covener</programlisting>
faea99bb676ec50ece38da6b1879aa37546483a2covener The elements of this structure are:
faea99bb676ec50ece38da6b1879aa37546483a2covener <variablelist>
faea99bb676ec50ece38da6b1879aa37546483a2covener <varlistentry>
344f755169e100ea8ce51e847a0bf30a13b46917covener the overall packet length, including the entire packet header.
344f755169e100ea8ce51e847a0bf30a13b46917covener This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
fcd5c4e9e126e867eb270ed2d4138348cb1e46e5trawick </listitem>
50cfe8bbbaf4279375802531268e2bf0155215fetrawick </varlistentry>
50cfe8bbbaf4279375802531268e2bf0155215fetrawick <varlistentry>
ffaa9771884a8664f0e6267efbe9d26b40000461trawick the header format. There is currently only one format,
f87299dab99bc04b51a6b8cad51b6795db862c0atrawick This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
4d12805e6c18253040223ea637acd6b3b3c18f60jorton </listitem>
4d12805e6c18253040223ea637acd6b3b3c18f60jorton </varlistentry>
4d12805e6c18253040223ea637acd6b3b3c18f60jorton <varlistentry>
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener library-defined flags for this packet: for instance whether the
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener is a request or a reply. Flag values can be set, but not defined
cb666b29f81df1d11d65002250153353568021fccovener the caller.
cb666b29f81df1d11d65002250153353568021fccovener This field is filled in by the application wit the exception of
1c2cab00d988fc48cbe59032cf76cc0bab20d6f7covener LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
75a230a728338d84dcfe81edd375352f34de22d0covener lwres_gabn_*() and lwres_gnba_*() calls.
75a230a728338d84dcfe81edd375352f34de22d0covener </listitem>
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener </varlistentry>
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener <varlistentry>
63a5ea80bddcc84a462e40f402b4f330e0e05411covener is set by the requestor and is returned in all replies. If two
986f3ea2c314d4d4b3b937149853a0f23f6119aaminfrin packets from the same source have the same serial number and are
986f3ea2c314d4d4b3b937149853a0f23f6119aaminfrin the same source, they are assumed to be duplicates and the
65a4e663b82f8bce28ac22ab2edfd7502de36998sf latter ones
65a4e663b82f8bce28ac22ab2edfd7502de36998sf may be dropped.
65a4e663b82f8bce28ac22ab2edfd7502de36998sf This field must be set by the application.
c7de1955eb0eaeabf7042902476397692672d549sf </listitem>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin </varlistentry>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin <varlistentry>
a511a29faf2ff7ead3b67680154a624effb31aafminfrin indicates the operation.
a511a29faf2ff7ead3b67680154a624effb31aafminfrin Opcodes between 0x00000000 and 0x03ffffff are
a511a29faf2ff7ead3b67680154a624effb31aafminfrin reserved for use by the lightweight resolver library. Opcodes
63921358ef93fcb41bc71d9894221ba3d7fbb87bminfrin 0x04000000 and 0xffffffff are application defined.
63921358ef93fcb41bc71d9894221ba3d7fbb87bminfrin This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin </listitem>
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin </varlistentry>
6d601599d3d65df0410eae6e573e75b2dbfb1fb4minfrin <varlistentry>
4c02bab56a528a180bbe394d8b6e6fd9c1a3ac1esf <listitem>
4c02bab56a528a180bbe394d8b6e6fd9c1a3ac1esf is only valid for replies.
4c02bab56a528a180bbe394d8b6e6fd9c1a3ac1esf Results between 0x04000000 and 0xffffffff are application
684e0cfc200f66287a93bbd1708d1dd8a92a7eefcovener Results between 0x00000000 and 0x03ffffff are reserved for
684e0cfc200f66287a93bbd1708d1dd8a92a7eefcovener library use.
5c43d2fb853f84497b5ece2d414ef9484aa87e5fsf This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq </listitem>
26c5829347f6a355c00f1ba0301d575056b69536niq </varlistentry>
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq <varlistentry>
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq <listitem>
ef82e8fa164e0a1f8b813f7deb6b7ead96018c94niq is the maximum buffer size that the receiver can handle on
413ee814748f37be168ff12407fa6dba0ceeabe6trawick and the size of the buffer needed to satisfy a request when the
c12917da693bae4028a1d5a5e8224bceed8c739dsf is too large for replies.
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf This field is supplied by the application.
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf </listitem>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf </varlistentry>
eafcc0ebf263d0ba69855b6e10958c4c1a2361bdsf <varlistentry>
d7ffd2da16d58b1a0de212e4d56f7aebb72bef26sf <listitem>
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf defines the packet level authentication that is used.
4576c1a9ef54cd1e5555ee07d016a7f559f80338sf Authorisation types between 0x1000 and 0xffff are application
9811aed12bbc71783d2e544ccb5fecd193843eadsf and types between 0x0000 and 0x0fff are reserved for library
9811aed12bbc71783d2e544ccb5fecd193843eadsf Currently these are not used and must be zero.
1366443dc565c33e7b449ae428bbfc4c86f33935drh </listitem>
88fac54d9d64f85bbdab5d7010816f4377f95bd7rjung </varlistentry>
88fac54d9d64f85bbdab5d7010816f4377f95bd7rjung <varlistentry>
bd3f5647b96d378d9c75c954e3f13582af32c643sf <listitem>
bd3f5647b96d378d9c75c954e3f13582af32c643sf gives the length of the authentication data.
bd3f5647b96d378d9c75c954e3f13582af32c643sf Since packet authentication is currently not used, this must be
2a7beea91d46beb41f043a84eaad060047ee04aafabien </listitem>
2a7beea91d46beb41f043a84eaad060047ee04aafabien </varlistentry>
584a85dd4047e38d3ed3a29b6662fcc9d100ae4csf </variablelist>
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf The following opcodes are currently defined:
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf <variablelist>
f21e9e3d0bfb7a507ecc5bc963f2159d693503d1sf <varlistentry>
f6b9c755a0b793e8a3a3aebd327ca20a86478117sf <listitem>
132ee6ac1c26d6e8953836316ba50734eefab47bsf Success is always returned and the packet contents are echoed.
132ee6ac1c26d6e8953836316ba50734eefab47bsf The lwres_noop_*() functions should be used for this type.
85eacfc96a04547ef25aabbc06440039715084c2jorton </listitem>
85eacfc96a04547ef25aabbc06440039715084c2jorton </varlistentry>
85eacfc96a04547ef25aabbc06440039715084c2jorton <varlistentry>
536d2e7cd1fdec1255b8c3bdf41fdc714c506a54trawick returns all known addresses for a given name.
79c5787b92ac5f0e1cc82393816c77a006399316trawick The lwres_gabn_*() functions should be used for this type.
79c5787b92ac5f0e1cc82393816c77a006399316trawick </listitem>
79c5787b92ac5f0e1cc82393816c77a006399316trawick </varlistentry>
c967bf3bc89e8aa60dbd30d9da388e448ddc1cc4trawick <varlistentry>
79c5787b92ac5f0e1cc82393816c77a006399316trawick return the hostname for the given address.
79c5787b92ac5f0e1cc82393816c77a006399316trawick The lwres_gnba_*() functions should be used for this type.
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton </listitem>
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton </varlistentry>
7b395e4e878c28a4784919cfd2e704ddd14a3390jorton </variablelist>
e81785da447b469da66f218b3f0244aab507958djorton <para><function>lwres_lwpacket_renderheader()</function>
e81785da447b469da66f218b3f0244aab507958djorton transfers the contents of lightweight resolver packet structure
3e4e54d4e3fc0123c63d57aa84ac7ad7a8c73ff8jorton <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
3e4e54d4e3fc0123c63d57aa84ac7ad7a8c73ff8jorton network byte order to the lightweight resolver buffer,
53e9b27aba029b18be814df40bcf6f0428771d1efuankg <para><function>lwres_lwpacket_parseheader()</function>
53e9b27aba029b18be814df40bcf6f0428771d1efuankg performs the converse operation. It transfers data in network
53e9b27aba029b18be814df40bcf6f0428771d1efuankg byte order from buffer <parameter>*b</parameter> to resolver
6bb524f1895f30265a1431afc460977d391cb36bsf packet <parameter>*pkt</parameter>. The contents of the buffer
e6dd71992459d05a676b98b7963423dc5dc1e24aminfrin </refsect1>
23f1535d6a60817d2846bac0aea230ea475d7dccminfrin Successful calls to
23f1535d6a60817d2846bac0aea230ea475d7dccminfrin <function>lwres_lwpacket_renderheader()</function> and
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung <function>lwres_lwpacket_parseheader()</function> return
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung space to copy data between the buffer <parameter>*b</parameter> and
ec7520b24cd80d34d82bbcaca153cbb23cc04bc0rjung lightweight resolver packet <parameter>*pkt</parameter> both
6249dfa569d3b4f1f539665b979a80c6e335d93etrawick </refsect1>
0827cb14e550f6f65018431c22c2c913631c8f25kbrand - Local variables:
6249dfa569d3b4f1f539665b979a80c6e335d93etrawick - mode: sgml