lwres_packet.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames - Copyright (C) 2000, 2001 Internet Software Consortium.
f0d89a5a23222e031db8113478645f28688fa748jorton - Permission to use, copy, modify, and/or distribute this software for any
f0d89a5a23222e031db8113478645f28688fa748jorton - purpose with or without fee is hereby granted, provided that the above
f0d89a5a23222e031db8113478645f28688fa748jorton - copyright notice and this permission notice appear in all copies.
f0d89a5a23222e031db8113478645f28688fa748jorton - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
f0d89a5a23222e031db8113478645f28688fa748jorton - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f0d89a5a23222e031db8113478645f28688fa748jorton - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
f0d89a5a23222e031db8113478645f28688fa748jorton - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f0d89a5a23222e031db8113478645f28688fa748jorton - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
f0d89a5a23222e031db8113478645f28688fa748jorton - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
65d743d7fbb53143636ee2dec8fe8d8a1a581a6bjerenkrantz - PERFORMANCE OF THIS SOFTWARE.
9df62ed109bd456de3e6a19b54e0ab31da3fe07ctrawick<!-- Converted by db4-upgrade version 1.0 -->
9df62ed109bd456de3e6a19b54e0ab31da3fe07ctrawick<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
a0fd132e01ab69f1c48e3d6a6791447cb6d65e51jerenkrantz <refentryinfo>
a6bb6f2fb734e488a9b6335fabea3431f9dcf253jerenkrantz <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
a6bb6f2fb734e488a9b6335fabea3431f9dcf253jerenkrantz </refentryinfo>
d5c1ba1aa5682c9a171114b76d5e21117e19ed6ctrawick <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
d5c1ba1aa5682c9a171114b76d5e21117e19ed6ctrawick </copyright>
d5c1ba1aa5682c9a171114b76d5e21117e19ed6ctrawick <copyright>
5c6cb72bfeee541644cea8177aefce1157571d3bjerenkrantz </copyright>
0894cd17fe3f614bf01dbf84f1414756bd5a34c3bnicholes <refnamediv>
0894cd17fe3f614bf01dbf84f1414756bd5a34c3bnicholes <refpurpose>lightweight resolver packet handling functions</refpurpose>
db8551deeb08fa799e7f27e8b748a9397f747bdcjorton </refnamediv>
db8551deeb08fa799e7f27e8b748a9397f747bdcjorton <refsynopsisdiv>
db8551deeb08fa799e7f27e8b748a9397f747bdcjorton <funcsynopsis>
db8551deeb08fa799e7f27e8b748a9397f747bdcjorton<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
9e3209bc06ddf32f23e4b254faa45914bc323cc9jim<funcprototype>
9e3209bc06ddf32f23e4b254faa45914bc323cc9jimlwres_result_t
45ed846f4ed90f05c084f6a33d688e642be4e623jerenkrantz<function>lwres_lwpacket_renderheader</function></funcdef>
45ed846f4ed90f05c084f6a33d688e642be4e623jerenkrantz <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
45ed846f4ed90f05c084f6a33d688e642be4e623jerenkrantz <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
54d22ed1c429b903b029bbd62621f11a9e286137minfrin </funcprototype>
54d22ed1c429b903b029bbd62621f11a9e286137minfrin<funcprototype>
54d22ed1c429b903b029bbd62621f11a9e286137minfrinlwres_result_t
54d22ed1c429b903b029bbd62621f11a9e286137minfrin<function>lwres_lwpacket_parseheader</function></funcdef>
54d22ed1c429b903b029bbd62621f11a9e286137minfrin <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
54d22ed1c429b903b029bbd62621f11a9e286137minfrin <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
54d22ed1c429b903b029bbd62621f11a9e286137minfrin </funcprototype>
92e8e44864d94866eefcbfde0a53fa3d12855149jerenkrantz</funcsynopsis>
92e8e44864d94866eefcbfde0a53fa3d12855149jerenkrantz </refsynopsisdiv>
92e8e44864d94866eefcbfde0a53fa3d12855149jerenkrantz <refsection><info><title>DESCRIPTION</title></info>
06106b6b63b112a09de1b66fa29596035c0176ffthommay These functions rely on a
e335319a08e12eb7daff9afa80e985dc53f652b8jorton which is defined in
c8794ec1e4c474ae101ce3835080f638136e7860erikabeletypedef struct lwres_lwpacket lwres_lwpacket_t;
c8794ec1e4c474ae101ce3835080f638136e7860erikabele </programlisting>
bb07ee33bce1a448bcc60ca43720b1ab1c413f87minfrinstruct lwres_lwpacket {
bb07ee33bce1a448bcc60ca43720b1ab1c413f87minfrin lwres_uint32_t length;
22dda44322067379eeba28d7ec7fc833cb04c0dfminfrin lwres_uint16_t version;
22dda44322067379eeba28d7ec7fc833cb04c0dfminfrin lwres_uint16_t pktflags;
7b6ba9c468f26bdb3492d5e8cb79628a3b04e8c8wrowe lwres_uint32_t serial;
7b6ba9c468f26bdb3492d5e8cb79628a3b04e8c8wrowe lwres_uint32_t opcode;
7b6ba9c468f26bdb3492d5e8cb79628a3b04e8c8wrowe lwres_uint32_t result;
7b6ba9c468f26bdb3492d5e8cb79628a3b04e8c8wrowe lwres_uint32_t recvlength;
77edcaaccc089335938f3844b752e1044f7eb278trawick lwres_uint16_t authtype;
77edcaaccc089335938f3844b752e1044f7eb278trawick lwres_uint16_t authlength;
77edcaaccc089335938f3844b752e1044f7eb278trawick</programlisting>
59b1b6c3fd51c83c3bb9f02a8f08751335f9fb1dminfrin The elements of this structure are:
9f1a88897168c3f1e5009acb585daf01e38a0299jim <variablelist>
9f1a88897168c3f1e5009acb585daf01e38a0299jim <varlistentry>
9f1a88897168c3f1e5009acb585daf01e38a0299jim <listitem>
616a448c1fca1648622707df5a1aae7316bb3d5djim the overall packet length, including the entire packet header.
616a448c1fca1648622707df5a1aae7316bb3d5djim This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
5a8bb5948d2a258145174320587706de3219d8a3pquerna </listitem>
5a8bb5948d2a258145174320587706de3219d8a3pquerna </varlistentry>
5a8bb5948d2a258145174320587706de3219d8a3pquerna <varlistentry>
e5abee85fe751fc27c5d4fc9a8ebe3b80f3d6603trawick the header format. There is currently only one format,
c169c5f94d61a860f3110c5d29a9fb306e762c11trawick This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ca3a25d12c5fe0926aa97550be39f0d88d0decb1pquerna </listitem>
ca3a25d12c5fe0926aa97550be39f0d88d0decb1pquerna </varlistentry>
ca3a25d12c5fe0926aa97550be39f0d88d0decb1pquerna <varlistentry>
4d553781254e46f1dfc8d86b79667a74fb8a3eb5brianp library-defined flags for this packet: for instance whether the
8f868f15482c7406db01216b6e4778ddabb26898trawick is a request or a reply. Flag values can be set, but not defined
8f868f15482c7406db01216b6e4778ddabb26898trawick the caller.
8f868f15482c7406db01216b6e4778ddabb26898trawick This field is filled in by the application wit the exception of
f902601ea431a9b56106e0f5f641dd5fd7efbc30jorton LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
f902601ea431a9b56106e0f5f641dd5fd7efbc30jorton lwres_gabn_*() and lwres_gnba_*() calls.
1e1e4f4f810b99732f06fc05141f42ca1965a9edpquerna </listitem>
1e1e4f4f810b99732f06fc05141f42ca1965a9edpquerna </varlistentry>
1e1e4f4f810b99732f06fc05141f42ca1965a9edpquerna <varlistentry>
78fcc425fc9fc58202a1693fe40dd0ce75c031ffjorton is set by the requestor and is returned in all replies. If two
78fcc425fc9fc58202a1693fe40dd0ce75c031ffjorton packets from the same source have the same serial number and are
d2ffb32434f79782ff7a364ffa31064698c5c645jorton the same source, they are assumed to be duplicates and the
d2ffb32434f79782ff7a364ffa31064698c5c645jorton latter ones
d2ffb32434f79782ff7a364ffa31064698c5c645jorton may be dropped.
01847067cfc639c14e1aa77d3b3e98f239447a12jerenkrantz This field must be set by the application.
01847067cfc639c14e1aa77d3b3e98f239447a12jerenkrantz </varlistentry>
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz <varlistentry>
dae3cb64cc6681b5f6b0fd12e7f8f6296ffaa19abnicholes indicates the operation.
d2ffb32434f79782ff7a364ffa31064698c5c645jorton Opcodes between 0x00000000 and 0x03ffffff are
9fe74ffcdea85800f04a7222f716f78ae60cce51jerenkrantz reserved for use by the lightweight resolver library. Opcodes
d2ffb32434f79782ff7a364ffa31064698c5c645jorton 0x04000000 and 0xffffffff are application defined.
81540a0eb1da2c687e22de3367d8ded55e17e330pquerna This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ce66c67eba79a20118d8664b65b0c9eeec1bebdabnicholes </varlistentry>
ce66c67eba79a20118d8664b65b0c9eeec1bebdabnicholes <varlistentry>
6cfc2ed5a8e633c5a40fec65775868d53952d992trawick is only valid for replies.
6cfc2ed5a8e633c5a40fec65775868d53952d992trawick Results between 0x04000000 and 0xffffffff are application
6cfc2ed5a8e633c5a40fec65775868d53952d992trawick Results between 0x00000000 and 0x03ffffff are reserved for
e34223f72e630187c4d8ac7c22da5096c833eb20trawick library use.
e34223f72e630187c4d8ac7c22da5096c833eb20trawick This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
5159c40648868a58745aa11981f706948ff0f0d1pquerna </listitem>
5159c40648868a58745aa11981f706948ff0f0d1pquerna </varlistentry>
a80dd6ffd7a1484e7f45e4665689bdd84fc97153jerenkrantz <varlistentry>
c178b761acd6bffa199c2fd28c4469492b989699nd is the maximum buffer size that the receiver can handle on
08b98efa42017369c679a7457c79d5220fb3431btrawick and the size of the buffer needed to satisfy a request when the
08b98efa42017369c679a7457c79d5220fb3431btrawick is too large for replies.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna This field is supplied by the application.
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna </listitem>
9c6bbd67082b5a47fb17cfa5b61b8a7e1fb01875pquerna </varlistentry>
572f5b8a84bb399e51b02a562776f4aec119aa95pquerna <varlistentry>
1b03ca18c41f51a25dcf1a623a8f558bd779e0a4jerenkrantz defines the packet level authentication that is used.
1b03ca18c41f51a25dcf1a623a8f558bd779e0a4jerenkrantz Authorisation types between 0x1000 and 0xffff are application
1b03ca18c41f51a25dcf1a623a8f558bd779e0a4jerenkrantz and types between 0x0000 and 0x0fff are reserved for library
1b03ca18c41f51a25dcf1a623a8f558bd779e0a4jerenkrantz Currently these are not used and must be zero.
1b03ca18c41f51a25dcf1a623a8f558bd779e0a4jerenkrantz </varlistentry>
db443e0132f14dac789ab97ec23ce124360d74c2nd <varlistentry>
db443e0132f14dac789ab97ec23ce124360d74c2nd <listitem>
4ac7a7c09ac5732b09f8bf28873f7e9efcab34d5bnicholes gives the length of the authentication data.
4ac7a7c09ac5732b09f8bf28873f7e9efcab34d5bnicholes Since packet authentication is currently not used, this must be
4ac7a7c09ac5732b09f8bf28873f7e9efcab34d5bnicholes </varlistentry>
4ac7a7c09ac5732b09f8bf28873f7e9efcab34d5bnicholes </variablelist>
ce8490f3812311582d1deee96b012c377311b317minfrin The following opcodes are currently defined:
ce8490f3812311582d1deee96b012c377311b317minfrin <variablelist>
38f6ebaca968b7b23c25c0b30d0be1c7aad7412bjorton <varlistentry>
cc7d8b55b16eee88be925a090473ca94b0a6e770jorton Success is always returned and the packet contents are echoed.
cc7d8b55b16eee88be925a090473ca94b0a6e770jorton The lwres_noop_*() functions should be used for this type.
f2b43354f9ac8496ab7003ae01211af739efba1atrawick </listitem>
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe </varlistentry>
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe <varlistentry>
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe returns all known addresses for a given name.
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe The lwres_gabn_*() functions should be used for this type.
2555a6b5da21d61804f47084d8fcc98eb4acbc42wrowe </listitem>
eb6e3a3e784021abc1e28247158db3a8b07186b9minfrin </varlistentry>
eb6e3a3e784021abc1e28247158db3a8b07186b9minfrin <varlistentry>
f5098e2eb6ed9dfd7052f25761bb5e97779b8460minfrin return the hostname for the given address.
f5098e2eb6ed9dfd7052f25761bb5e97779b8460minfrin The lwres_gnba_*() functions should be used for this type.
c79b5caf7c5462ef707363c69cc63ea2606310abtrawick </varlistentry>
c79b5caf7c5462ef707363c69cc63ea2606310abtrawick </variablelist>
1551c2366551d7a361bedbf7ae54f1abd74ef822minfrin <para><function>lwres_lwpacket_renderheader()</function>
1551c2366551d7a361bedbf7ae54f1abd74ef822minfrin transfers the contents of lightweight resolver packet structure
f1826b4cf1fbeb049c569761cc95b04e3496efd6bnicholes <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
f1826b4cf1fbeb049c569761cc95b04e3496efd6bnicholes network byte order to the lightweight resolver buffer,
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna <para><function>lwres_lwpacket_parseheader()</function>
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna performs the converse operation. It transfers data in network
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna byte order from buffer <parameter>*b</parameter> to resolver
87a528a7622973988232079ba02763748c9c7071pquerna packet <parameter>*pkt</parameter>. The contents of the buffer
1a986bbad9314beb8739401cac822e87bb04bbfepquerna </refsection>
1a986bbad9314beb8739401cac822e87bb04bbfepquerna <refsection><info><title>RETURN VALUES</title></info>
752ec04fdfa6e936047811b9e506cf829d7a69f7pquerna Successful calls to
752ec04fdfa6e936047811b9e506cf829d7a69f7pquerna <function>lwres_lwpacket_renderheader()</function> and
cf82d17373559b6163dbd6c844c1af82cab56883niq <function>lwres_lwpacket_parseheader()</function> return
cf82d17373559b6163dbd6c844c1af82cab56883niq <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
cf82d17373559b6163dbd6c844c1af82cab56883niq space to copy data between the buffer <parameter>*b</parameter> and
cf82d17373559b6163dbd6c844c1af82cab56883niq lightweight resolver packet <parameter>*pkt</parameter> both
c4e6f5320f87eff25838c21c107a24b688d539d0niq </refsection>
c4e6f5320f87eff25838c21c107a24b688d539d0niq</refentry>