summaryrefslogtreecommitdiffstats
path: root/lib/lwres/man/lwres_packet.docbook
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 18:37:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 18:37:14 +0000
commitea648e70a989cca190cd7403fe892fd2dcc290b4 (patch)
treee2b6b1c647da68b0d4d66082835e256eb30970e8 /lib/lwres/man/lwres_packet.docbook
parentInitial commit. (diff)
downloadbind9-ea648e70a989cca190cd7403fe892fd2dcc290b4.tar.xz
bind9-ea648e70a989cca190cd7403fe892fd2dcc290b4.zip
Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'lib/lwres/man/lwres_packet.docbook')
-rw-r--r--lib/lwres/man/lwres_packet.docbook283
1 files changed, 283 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_packet.docbook b/lib/lwres/man/lwres_packet.docbook
new file mode 100644
index 0000000..8b43750
--- /dev/null
+++ b/lib/lwres/man/lwres_packet.docbook
@@ -0,0 +1,283 @@
+<!--
+ - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
+ <info>
+ <date>2007-06-18</date>
+ </info>
+ <refentryinfo>
+ <corpname>ISC</corpname>
+ <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>lwres_packet</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo>BIND9</refmiscinfo>
+ </refmeta>
+
+ <docinfo>
+ <copyright>
+ <year>2000</year>
+ <year>2001</year>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2007</year>
+ <year>2014</year>
+ <year>2015</year>
+ <year>2016</year>
+ <year>2018</year>
+ <year>2019</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+ </copyright>
+ </docinfo>
+
+ <refnamediv>
+ <refname>lwres_lwpacket_renderheader</refname>
+ <refname>lwres_lwpacket_parseheader</refname>
+ <refpurpose>lightweight resolver packet handling functions</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/lwpacket.h&gt;</funcsynopsisinfo>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_lwpacket_renderheader</function></funcdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_lwpacket_parseheader</function></funcdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+ </refsynopsisdiv>
+ <refsection><info><title>DESCRIPTION</title></info>
+
+ <para>
+ These functions rely on a
+ <type>struct lwres_lwpacket</type>
+ which is defined in
+ <filename>lwres/lwpacket.h</filename>.
+ </para>
+
+ <para><programlisting>
+typedef struct lwres_lwpacket lwres_lwpacket_t;
+ </programlisting>
+ </para>
+ <para><programlisting>
+struct lwres_lwpacket {
+ uint32_t length;
+ uint16_t version;
+ uint16_t pktflags;
+ uint32_t serial;
+ uint32_t opcode;
+ uint32_t result;
+ uint32_t recvlength;
+ uint16_t authtype;
+ uint16_t authlength;
+};
+</programlisting>
+ </para>
+
+ <para>
+ The elements of this structure are:
+ <variablelist>
+ <varlistentry>
+ <term><constant>length</constant></term>
+ <listitem>
+ <para>
+ the overall packet length, including the entire packet header.
+ This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+ calls.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>version</constant></term>
+ <listitem>
+ <para>
+ the header format. There is currently only one format,
+ <type>LWRES_LWPACKETVERSION_0</type>.
+
+ This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+ calls.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>pktflags</constant></term>
+ <listitem>
+ <para>
+ library-defined flags for this packet: for instance whether the
+ packet
+ is a request or a reply. Flag values can be set, but not defined
+ by
+ the caller.
+ This field is filled in by the application wit the exception of
+ the
+ LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
+ the
+ lwres_gabn_*() and lwres_gnba_*() calls.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>serial</constant></term>
+ <listitem>
+ <para>
+ is set by the requestor and is returned in all replies. If two
+ or more
+ packets from the same source have the same serial number and are
+ from
+ the same source, they are assumed to be duplicates and the
+ latter ones
+ may be dropped.
+ This field must be set by the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>opcode</constant></term>
+ <listitem>
+ <para>
+ indicates the operation.
+ Opcodes between 0x00000000 and 0x03ffffff are
+ reserved for use by the lightweight resolver library. Opcodes
+ between
+ 0x04000000 and 0xffffffff are application defined.
+ This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+ calls.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>result</constant></term>
+ <listitem>
+ <para>
+ is only valid for replies.
+ Results between 0x04000000 and 0xffffffff are application
+ defined.
+ Results between 0x00000000 and 0x03ffffff are reserved for
+ library use.
+ This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+ calls.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>recvlength</constant></term>
+ <listitem>
+ <para>
+ is the maximum buffer size that the receiver can handle on
+ requests
+ and the size of the buffer needed to satisfy a request when the
+ buffer
+ is too large for replies.
+ This field is supplied by the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>authtype</constant></term>
+ <listitem>
+ <para>
+ defines the packet level authentication that is used.
+ Authorisation types between 0x1000 and 0xffff are application
+ defined
+ and types between 0x0000 and 0x0fff are reserved for library
+ use.
+ Currently these are not used and must be zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>authlen</constant></term>
+ <listitem>
+ <para>
+ gives the length of the authentication data.
+ Since packet authentication is currently not used, this must be
+ zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ The following opcodes are currently defined:
+ <variablelist>
+ <varlistentry>
+ <term><constant>NOOP</constant></term>
+ <listitem>
+ <para>
+ Success is always returned and the packet contents are echoed.
+ The lwres_noop_*() functions should be used for this type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GETADDRSBYNAME</constant></term>
+ <listitem>
+ <para>
+ returns all known addresses for a given name.
+ The lwres_gabn_*() functions should be used for this type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GETNAMEBYADDR</constant></term>
+ <listitem>
+ <para>
+ return the hostname for the given address.
+ The lwres_gnba_*() functions should be used for this type.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para><function>lwres_lwpacket_renderheader()</function>
+ transfers the contents of lightweight resolver packet structure
+ <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
+ network byte order to the lightweight resolver buffer,
+ <parameter>*b</parameter>.
+ </para>
+
+ <para><function>lwres_lwpacket_parseheader()</function>
+ performs the converse operation. It transfers data in network
+ byte order from buffer <parameter>*b</parameter> to resolver
+ packet <parameter>*pkt</parameter>. The contents of the buffer
+ <parameter>b</parameter> should correspond to a
+ <type>lwres_lwpacket_t</type>.
+ </para>
+
+ </refsection>
+
+ <refsection><info><title>RETURN VALUES</title></info>
+
+ <para>
+ Successful calls to
+ <function>lwres_lwpacket_renderheader()</function> and
+ <function>lwres_lwpacket_parseheader()</function> return
+ <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
+ space to copy data between the buffer <parameter>*b</parameter> and
+ lightweight resolver packet <parameter>*pkt</parameter> both
+ functions
+ return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
+ </para>
+
+ </refsection>
+</refentry>