1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<refentry> 22 23 <refentryinfo> 24 <date>June 18, 2007</date> 25 </refentryinfo> 26 27 <refmeta> 28 <refentrytitle>lwres_gabn</refentrytitle> 29 <manvolnum>3</manvolnum> 30 <refmiscinfo>BIND9</refmiscinfo> 31 </refmeta> 32 33 <docinfo> 34 <copyright> 35 <year>2004</year> 36 <year>2005</year> 37 <year>2007</year> 38 <year>2014</year> 39 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 40 </copyright> 41 <copyright> 42 <year>2000</year> 43 <year>2001</year> 44 <holder>Internet Software Consortium.</holder> 45 </copyright> 46 </docinfo> 47 48 <refnamediv> 49 <refname>lwres_gabnrequest_render</refname> 50 <refname>lwres_gabnresponse_render</refname> 51 <refname>lwres_gabnrequest_parse</refname> 52 <refname>lwres_gabnresponse_parse</refname> 53 <refname>lwres_gabnresponse_free</refname> 54 <refname>lwres_gabnrequest_free</refname> 55 <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose> 56 </refnamediv> 57 <refsynopsisdiv> 58 <funcsynopsis> 59<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> 60<funcprototype> 61 <funcdef> 62lwres_result_t 63<function>lwres_gabnrequest_render</function></funcdef> 64 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 65 <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef> 66 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 67 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 68 </funcprototype> 69<funcprototype> 70 <funcdef> 71lwres_result_t 72<function>lwres_gabnresponse_render</function></funcdef> 73 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 74 <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef> 75 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 76 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 77 </funcprototype> 78<funcprototype> 79 <funcdef> 80lwres_result_t 81<function>lwres_gabnrequest_parse</function></funcdef> 82 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 83 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 84 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 85 <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> 86 </funcprototype> 87<funcprototype> 88 <funcdef> 89lwres_result_t 90<function>lwres_gabnresponse_parse</function></funcdef> 91 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 92 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 93 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 94 <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> 95 </funcprototype> 96<funcprototype> 97 <funcdef> 98void 99<function>lwres_gabnresponse_free</function></funcdef> 100 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 101 <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> 102 </funcprototype> 103<funcprototype> 104 <funcdef> 105void 106<function>lwres_gabnrequest_free</function></funcdef> 107 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 108 <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> 109 </funcprototype> 110</funcsynopsis> 111 </refsynopsisdiv> 112 <refsect1> 113 <title>DESCRIPTION</title> 114 <para> 115 These are low-level routines for creating and parsing 116 lightweight resolver name-to-address lookup request and 117 response messages. 118 </para> 119 <para> 120 There are four main functions for the getaddrbyname opcode. 121 One render function converts a getaddrbyname request structure — 122 <type>lwres_gabnrequest_t</type> — 123 to the lightweight resolver's canonical format. 124 It is complemented by a parse function that converts a packet in this 125 canonical format to a getaddrbyname request structure. 126 Another render function converts the getaddrbyname response structure 127 — <type>lwres_gabnresponse_t</type> — 128 to the canonical format. 129 This is complemented by a parse function which converts a packet in 130 canonical format to a getaddrbyname response structure. 131 </para> 132 <para> 133 These structures are defined in 134 <filename><lwres/lwres.h></filename>. 135 They are shown below. 136 </para> 137 <para><programlisting> 138#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U 139</programlisting> 140 </para> 141 <para><programlisting> 142typedef struct lwres_addr lwres_addr_t; 143typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; 144</programlisting> 145 </para> 146 <para><programlisting> 147typedef struct { 148 lwres_uint32_t flags; 149 lwres_uint32_t addrtypes; 150 lwres_uint16_t namelen; 151 char *name; 152} lwres_gabnrequest_t; 153</programlisting> 154 </para> 155 <para><programlisting> 156typedef struct { 157 lwres_uint32_t flags; 158 lwres_uint16_t naliases; 159 lwres_uint16_t naddrs; 160 char *realname; 161 char **aliases; 162 lwres_uint16_t realnamelen; 163 lwres_uint16_t *aliaslen; 164 lwres_addrlist_t addrs; 165 void *base; 166 size_t baselen; 167} lwres_gabnresponse_t; 168</programlisting> 169 </para> 170 171 <para><function>lwres_gabnrequest_render()</function> 172 uses resolver context <parameter>ctx</parameter> to convert 173 getaddrbyname request structure <parameter>req</parameter> to 174 canonical format. The packet header structure 175 <parameter>pkt</parameter> is initialised and transferred to 176 buffer <parameter>b</parameter>. 177 178 The contents of <parameter>*req</parameter> are then appended to 179 the buffer in canonical format. 180 <function>lwres_gabnresponse_render()</function> performs the 181 same task, except it converts a getaddrbyname response structure 182 <type>lwres_gabnresponse_t</type> to the lightweight resolver's 183 canonical format. 184 </para> 185 186 <para><function>lwres_gabnrequest_parse()</function> 187 uses context <parameter>ctx</parameter> to convert the contents 188 of packet <parameter>pkt</parameter> to a 189 <type>lwres_gabnrequest_t</type> structure. Buffer 190 <parameter>b</parameter> provides space to be used for storing 191 this structure. When the function succeeds, the resulting 192 <type>lwres_gabnrequest_t</type> is made available through 193 <parameter>*structp</parameter>. 194 195 <function>lwres_gabnresponse_parse()</function> offers the same 196 semantics as <function>lwres_gabnrequest_parse()</function> 197 except it yields a <type>lwres_gabnresponse_t</type> structure. 198 </para> 199 200 <para><function>lwres_gabnresponse_free()</function> 201 and <function>lwres_gabnrequest_free()</function> release the 202 memory in resolver context <parameter>ctx</parameter> that was 203 allocated to the <type>lwres_gabnresponse_t</type> or 204 <type>lwres_gabnrequest_t</type> structures referenced via 205 <parameter>structp</parameter>. 206 207 Any memory associated with ancillary buffers and strings for 208 those structures is also discarded. 209 </para> 210 </refsect1> 211 <refsect1> 212 <title>RETURN VALUES</title> 213 <para> 214 The getaddrbyname opcode functions 215 <function>lwres_gabnrequest_render()</function>, 216 <function>lwres_gabnresponse_render()</function> 217 <function>lwres_gabnrequest_parse()</function> 218 and 219 <function>lwres_gabnresponse_parse()</function> 220 all return 221 <errorcode>LWRES_R_SUCCESS</errorcode> 222 on success. 223 They return 224 <errorcode>LWRES_R_NOMEMORY</errorcode> 225 if memory allocation fails. 226 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 227 is returned if the available space in the buffer 228 <parameter>b</parameter> 229 is too small to accommodate the packet header or the 230 <type>lwres_gabnrequest_t</type> 231 and 232 <type>lwres_gabnresponse_t</type> 233 structures. 234 <function>lwres_gabnrequest_parse()</function> 235 and 236 <function>lwres_gabnresponse_parse()</function> 237 will return 238 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 239 if the buffer is not empty after decoding the received packet. 240 These functions will return 241 <errorcode>LWRES_R_FAILURE</errorcode> 242 if 243 <structfield>pktflags</structfield> 244 in the packet header structure 245 <type>lwres_lwpacket_t</type> 246 indicate that the packet is not a response to an earlier query. 247 </para> 248 </refsect1> 249 <refsect1> 250 <title>SEE ALSO</title> 251 <para><citerefentry> 252 <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> 253 </citerefentry> 254 </para> 255 </refsect1> 256</refentry><!-- 257 - Local variables: 258 - mode: sgml 259 - End: 260--> 261