lwres_gabn.html revision 7911e6f9de303bca5a3d8b34f4330c8f7cecffae
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
c40265eba0c99708887d68e67901924065ba2514Brian Wellington - This Source Code Form is subject to the terms of the Mozilla Public
c40265eba0c99708887d68e67901924065ba2514Brian Wellington - License, v. 2.0. If a copy of the MPL was not distributed with this
c40265eba0c99708887d68e67901924065ba2514Brian Wellington - file, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
af5073d03288a53b646ec3b807ac25ced64d7879Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
af5073d03288a53b646ec3b807ac25ced64d7879Mark Andrews<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<a name="id-1"></a><div class="titlepage"></div>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_gabnrequest_render,
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews lwres_gabnresponse_render,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_gabnrequest_parse,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_gabnresponse_parse,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_gabnresponse_free,
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews lwres_gabnrequest_free
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews — lightweight resolver getaddrbyname message handling
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrewslwres_result_t
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_gabnrequest_t *<var class="pdparam">req</var>, </td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<td>lwres_gabnresponse_t *<var class="pdparam">req</var>, </td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrewslwres_result_t
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrews<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrewslwres_result_t
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
a057e8e33baa5fa369be28a9680585200ce3ff73Mark Andrews<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
3a3705ef7747327df182bf8d009333d2472253d5Mark Andrews<td>lwres_gabnrequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews These are low-level routines for creating and parsing
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews lightweight resolver name-to-address lookup request and
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews response messages.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein There are four main functions for the getaddrbyname opcode.
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews One render function converts a getaddrbyname request structure —
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews <span class="type">lwres_gabnrequest_t</span> —
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews to the lightweight resolver's canonical format.
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews It is complemented by a parse function that converts a packet in this
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews canonical format to a getaddrbyname request structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Another render function converts the getaddrbyname response structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein — <span class="type">lwres_gabnresponse_t</span> —
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to the canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This is complemented by a parse function which converts a packet in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format to a getaddrbyname response structure.
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews These structures are defined in
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews <code class="filename"><lwres/lwres.h></code>.
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews They are shown below.
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrews#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrewstypedef struct lwres_addr lwres_addr_t;
7208386cd37a2092c70eddf80cf29519b16c4c80Mark Andrewstypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrewstypedef struct {
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews lwres_uint32_t flags;
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews lwres_uint32_t addrtypes;
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews lwres_uint16_t namelen;
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews} lwres_gabnrequest_t;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintypedef struct {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint32_t flags;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t naliases;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t naddrs;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein char *realname;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein char **aliases;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t realnamelen;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_uint16_t *aliaslen;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_addrlist_t addrs;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein size_t baselen;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein} lwres_gabnresponse_t;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <p><code class="function">lwres_gabnrequest_render()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uses resolver context <em class="parameter"><code>ctx</code></em> to convert
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein getaddrbyname request structure <em class="parameter"><code>req</code></em> to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format. The packet header structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>pkt</code></em> is initialised and transferred to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein buffer <em class="parameter"><code>b</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The contents of <em class="parameter"><code>*req</code></em> are then appended to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the buffer in canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_render()</code> performs the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein same task, except it converts a getaddrbyname response structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <p><code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uses context <em class="parameter"><code>ctx</code></em> to convert the contents
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein of packet <em class="parameter"><code>pkt</code></em> to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> structure. Buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>b</code></em> provides space to be used for storing
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews this structure. When the function succeeds, the resulting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> is made available through
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>*structp</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_gabnresponse_parse()</code> offers the same
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein semantics as <code class="function">lwres_gabnrequest_parse()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <p><code class="function">lwres_gabnresponse_free()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and <code class="function">lwres_gabnrequest_free()</code> release the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein memory in resolver context <em class="parameter"><code>ctx</code></em> that was
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein allocated to the <span class="type">lwres_gabnresponse_t</span> or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_gabnrequest_t</span> structures referenced via
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews <em class="parameter"><code>structp</code></em>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Any memory associated with ancillary buffers and strings for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein those structures is also discarded.