151 lines
5.1 KiB
Groff
151 lines
5.1 KiB
Groff
.\"
|
|
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
|
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
|
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
|
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
|
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
|
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.TH "LWRES_PACKET" "3" "Jun 30, 2000" "BIND9" ""
|
|
.SH NAME
|
|
lwres_lwpacket_renderheader, lwres_lwpacket_parseheader \- lightweight resolver packet handling functions
|
|
.SH SYNOPSIS
|
|
\fB#include <lwres/lwpacket.h>
|
|
.sp
|
|
.na
|
|
lwres_result_t
|
|
lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
|
|
.ad
|
|
.sp
|
|
.na
|
|
lwres_result_t
|
|
lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
|
|
.ad
|
|
\fR
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
These functions rely on a
|
|
\fBstruct lwres_lwpacket\fR
|
|
which is defined in
|
|
\fIlwres/lwpacket.h\fR.
|
|
.sp
|
|
.nf
|
|
typedef struct lwres_lwpacket lwres_lwpacket_t;
|
|
|
|
struct lwres_lwpacket {
|
|
lwres_uint32_t length;
|
|
lwres_uint16_t version;
|
|
lwres_uint16_t pktflags;
|
|
lwres_uint32_t serial;
|
|
lwres_uint32_t opcode;
|
|
lwres_uint32_t result;
|
|
lwres_uint32_t recvlength;
|
|
lwres_uint16_t authtype;
|
|
lwres_uint16_t authlength;
|
|
};
|
|
.sp
|
|
.fi
|
|
.PP
|
|
The elements of this structure are:
|
|
.TP
|
|
\fBlength\fR
|
|
the overall packet length, including the entire packet header.
|
|
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
|
calls.
|
|
.TP
|
|
\fBversion\fR
|
|
the header format. There is currently only one format,
|
|
\fBLWRES_LWPACKETVERSION_0\fR.
|
|
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
|
calls.
|
|
.TP
|
|
\fBpktflags\fR
|
|
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.
|
|
.TP
|
|
\fBserial\fR
|
|
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.
|
|
.TP
|
|
\fBopcode\fR
|
|
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.
|
|
.TP
|
|
\fBresult\fR
|
|
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.
|
|
.TP
|
|
\fBrecvlength\fR
|
|
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.
|
|
.TP
|
|
\fBauthtype\fR
|
|
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.
|
|
.TP
|
|
\fBauthlen\fR
|
|
gives the length of the authentication data.
|
|
Since packet authentication is currently not used, this must be zero.
|
|
.PP
|
|
The following opcodes are currently defined:
|
|
.TP
|
|
\fBNOOP\fR
|
|
Success is always returned and the packet contents are echoed.
|
|
The lwres_noop_*() functions should be used for this type.
|
|
.TP
|
|
\fBGETADDRSBYNAME\fR
|
|
returns all known addresses for a given name.
|
|
The lwres_gabn_*() functions should be used for this type.
|
|
.TP
|
|
\fBGETNAMEBYADDR\fR
|
|
return the hostname for the given address.
|
|
The lwres_gnba_*() functions should be used for this type.
|
|
.PP
|
|
\fBlwres_lwpacket_renderheader()\fR transfers the
|
|
contents of lightweight resolver packet structure
|
|
\fBlwres_lwpacket_t\fR \fI*pkt\fR in network
|
|
byte order to the lightweight resolver buffer,
|
|
\fI*b\fR.
|
|
.PP
|
|
\fBlwres_lwpacket_parseheader()\fR performs the
|
|
converse operation. It transfers data in network byte order from
|
|
buffer \fI*b\fR to resolver packet
|
|
\fI*pkt\fR. The contents of the buffer
|
|
\fIb\fR should correspond to a
|
|
\fBlwres_lwpacket_t\fR.
|
|
.SH "RETURN VALUES"
|
|
.PP
|
|
Successful calls to
|
|
\fBlwres_lwpacket_renderheader()\fR and
|
|
\fBlwres_lwpacket_parseheader()\fR return
|
|
LWRES_R_SUCCESS. If there is insufficient
|
|
space to copy data between the buffer \fI*b\fR and
|
|
lightweight resolver packet \fI*pkt\fR both functions
|
|
return LWRES_R_UNEXPECTEDEND.
|