lwres_packet.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem - Copyright (C) 2000, 2001 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and/or distribute this software for any
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - purpose with or without fee is hereby granted, provided that the above
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
4da61833a1cbbca94094f9653fd970582b97a72etrawick - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
4da61833a1cbbca94094f9653fd970582b97a72etrawick - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
4da61833a1cbbca94094f9653fd970582b97a72etrawick - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
4789804be088bcd86ae637a29cdb7fda25169521jailletc - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
4789804be088bcd86ae637a29cdb7fda25169521jailletc - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
4789804be088bcd86ae637a29cdb7fda25169521jailletc - PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- Converted by db4-upgrade version 1.0 -->
e50c3026198fd496f183cda4c32a202925476778covener<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic <refentryinfo>
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic </refentryinfo>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza <copyright>
d58a848a016d401b965111e50ef829e1641f7834minfrin <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
d58a848a016d401b965111e50ef829e1641f7834minfrin </copyright>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf <copyright>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic </copyright>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <refnamediv>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic <refpurpose>lightweight resolver packet handling functions</refpurpose>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic </refnamediv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <refsynopsisdiv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <funcsynopsis>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylaviclwres_result_t
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener<function>lwres_lwpacket_renderheader</function></funcdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener </funcprototype>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener<funcprototype>
44ff304057225e944e220e981d434a046d14cf06covenerlwres_result_t
44ff304057225e944e220e981d434a046d14cf06covener<function>lwres_lwpacket_parseheader</function></funcdef>
44ff304057225e944e220e981d434a046d14cf06covener <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
5d1ba75b8794925e67591c209085a49279791de9covener <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
5d1ba75b8794925e67591c209085a49279791de9covener </funcprototype>
5d1ba75b8794925e67591c209085a49279791de9covener</funcsynopsis>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand </refsynopsisdiv>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic These functions rely on a
caad2986f81ab263f7af41467dd622dc9add17f3ylavic which is defined in
2165214331e4afafca4048f66f303d0253d7b001covenertypedef struct lwres_lwpacket lwres_lwpacket_t;
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem </programlisting>
1e2d421a36999d292042a5539971070d54aa6c63ylavicstruct lwres_lwpacket {
1e2d421a36999d292042a5539971070d54aa6c63ylavic lwres_uint32_t length;
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh lwres_uint16_t version;
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh lwres_uint16_t pktflags;
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh lwres_uint32_t serial;
0b67eb8568cd58bb77082703951679b42cf098actrawick lwres_uint32_t opcode;
0b67eb8568cd58bb77082703951679b42cf098actrawick lwres_uint32_t result;
0b67eb8568cd58bb77082703951679b42cf098actrawick lwres_uint32_t recvlength;
0b67eb8568cd58bb77082703951679b42cf098actrawick lwres_uint16_t authtype;
5ef3c61605a3a021ff71f488983cb0065f8e1a79covener lwres_uint16_t authlength;
09c87c777bed1655621bb20e1c46cb6b1a63279dcovener</programlisting>
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic The elements of this structure are:
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic <variablelist>
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic <varlistentry>
e466c40e1801982602ee0200c9e8b61cc148742djailletc the overall packet length, including the entire packet header.
457468b82e59d01eba00dd9d0817309c8f5e414ejim This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton </listitem>
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton </varlistentry>
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem <varlistentry>
49dacedb6c387b786b7911082ff35121a45f414bcovener the header format. There is currently only one format,
cfd9415521847b2f9394fad04fb701cfb955f503rjung This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe </listitem>
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe </varlistentry>
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe <varlistentry>
63b9f1f5880391261705f696d7d65507bbe9ace3covener library-defined flags for this packet: for instance whether the
49dacedb6c387b786b7911082ff35121a45f414bcovener is a request or a reply. Flag values can be set, but not defined
49dacedb6c387b786b7911082ff35121a45f414bcovener the caller.
3c990331fc6702119e4f5b8ba9eae3021aea5265jim This field is filled in by the application wit the exception of
3c990331fc6702119e4f5b8ba9eae3021aea5265jim LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
fc42512879dd0504532f52fe5d0d0383dda96a1eniq lwres_gabn_*() and lwres_gnba_*() calls.
fc42512879dd0504532f52fe5d0d0383dda96a1eniq </listitem>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq </varlistentry>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq <varlistentry>
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc is set by the requestor and is returned in all replies. If two
06b8f183140c8e02e0974e938a05078b511d1603covener packets from the same source have the same serial number and are
06b8f183140c8e02e0974e938a05078b511d1603covener the same source, they are assumed to be duplicates and the
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem latter ones
259878293a997ff49f5ddfc53d3739cbdc25444ecovener may be dropped.
259878293a997ff49f5ddfc53d3739cbdc25444ecovener This field must be set by the application.
259878293a997ff49f5ddfc53d3739cbdc25444ecovener </listitem>
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem </varlistentry>
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin <varlistentry>
65967d05f839dbf27cf91d91fa79585eeae19660minfrin indicates the operation.
65967d05f839dbf27cf91d91fa79585eeae19660minfrin Opcodes between 0x00000000 and 0x03ffffff are
65967d05f839dbf27cf91d91fa79585eeae19660minfrin reserved for use by the lightweight resolver library. Opcodes
8152945ae46857b170cb227e79bb799f4fc7710dminfrin 0x04000000 and 0xffffffff are application defined.
8152945ae46857b170cb227e79bb799f4fc7710dminfrin This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
75f5c2db254c0167a0e396254460de09b775d203trawick </listitem>
75f5c2db254c0167a0e396254460de09b775d203trawick </varlistentry>
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph <varlistentry>
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick is only valid for replies.
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick Results between 0x04000000 and 0xffffffff are application
54d750a84a175d8e338880514d440773eb986b50covener Results between 0x00000000 and 0x03ffffff are reserved for
54d750a84a175d8e338880514d440773eb986b50covener library use.
54d750a84a175d8e338880514d440773eb986b50covener This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
54d750a84a175d8e338880514d440773eb986b50covener </listitem>
54d750a84a175d8e338880514d440773eb986b50covener </varlistentry>
54d750a84a175d8e338880514d440773eb986b50covener <varlistentry>
83b50288fa7d306324bba68832011ea08f5c7832covener is the maximum buffer size that the receiver can handle on
83b50288fa7d306324bba68832011ea08f5c7832covener and the size of the buffer needed to satisfy a request when the
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick is too large for replies.
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick This field is supplied by the application.
2e15620d724fb8e3a5be183b917359a2fd6e9468covener </listitem>
2e15620d724fb8e3a5be183b917359a2fd6e9468covener </varlistentry>
2e15620d724fb8e3a5be183b917359a2fd6e9468covener <varlistentry>
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener defines the packet level authentication that is used.
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener Authorisation types between 0x1000 and 0xffff are application
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener and types between 0x0000 and 0x0fff are reserved for library
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd Currently these are not used and must be zero.
179565be4043d7e5f9161aa75271fa0a001866d9covener </listitem>
179565be4043d7e5f9161aa75271fa0a001866d9covener </varlistentry>
179565be4043d7e5f9161aa75271fa0a001866d9covener <varlistentry>
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener gives the length of the authentication data.
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener Since packet authentication is currently not used, this must be
7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick </listitem>
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz </varlistentry>
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz </variablelist>
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza The following opcodes are currently defined:
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <variablelist>
efe780dcf13b2b95effabf897d694d8f23feac74trawick <varlistentry>
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza Success is always returned and the packet contents are echoed.
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza The lwres_noop_*() functions should be used for this type.
ba050a6f942b9fa0e81ed73437588005c569655ccovener </listitem>
ba050a6f942b9fa0e81ed73437588005c569655ccovener </varlistentry>
ba050a6f942b9fa0e81ed73437588005c569655ccovener <varlistentry>
135ddda3a989215d2bedbcf1529bfb269c3eda23niq <listitem>
135ddda3a989215d2bedbcf1529bfb269c3eda23niq returns all known addresses for a given name.
001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh The lwres_gabn_*() functions should be used for this type.
efe780dcf13b2b95effabf897d694d8f23feac74trawick </varlistentry>
793214f67dede32edfd9ee96c664ead04d175cbbjfclere <varlistentry>
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener return the hostname for the given address.
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza The lwres_gnba_*() functions should be used for this type.
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </listitem>
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </varlistentry>
56589be3d7a3e9343370df240010c6928cc78b39jkaluza </variablelist>
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc <para><function>lwres_lwpacket_renderheader()</function>
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc transfers the contents of lightweight resolver packet structure
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc network byte order to the lightweight resolver buffer,
4d12805e6c18253040223ea637acd6b3b3c18f60jorton <para><function>lwres_lwpacket_parseheader()</function>
4d12805e6c18253040223ea637acd6b3b3c18f60jorton performs the converse operation. It transfers data in network
4d12805e6c18253040223ea637acd6b3b3c18f60jorton byte order from buffer <parameter>*b</parameter> to resolver
85eacfc96a04547ef25aabbc06440039715084c2jorton packet <parameter>*pkt</parameter>. The contents of the buffer
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener </refsection>
cb666b29f81df1d11d65002250153353568021fccovener <refsection><info><title>RETURN VALUES</title></info>
1c2cab00d988fc48cbe59032cf76cc0bab20d6f7covener Successful calls to
6a80c3c6f4b8ea7ba5e89402b8b779b09ce020e0covener <function>lwres_lwpacket_renderheader()</function> and
75a230a728338d84dcfe81edd375352f34de22d0covener <function>lwres_lwpacket_parseheader()</function> return
75a230a728338d84dcfe81edd375352f34de22d0covener <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
75a230a728338d84dcfe81edd375352f34de22d0covener space to copy data between the buffer <parameter>*b</parameter> and
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener lightweight resolver packet <parameter>*pkt</parameter> both
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
63a5ea80bddcc84a462e40f402b4f330e0e05411covener </refsection>