/contrib/bind9/lib/lwres/man/lwres_gabn.docbook
Unknown | 261 lines | 250 code | 11 blank | 0 comment | 0 complexity | 1623587ae5b9113834247e1b40b41ef4 MD5 | raw file
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, 2012 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<!-- $Id$ --> 22<refentry> 23 24 <refentryinfo> 25 <date>Jun 30, 2000</date> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle>lwres_gabn</refentrytitle> 30 <manvolnum>3</manvolnum> 31 <refmiscinfo>BIND9</refmiscinfo> 32 </refmeta> 33 34 <docinfo> 35 <copyright> 36 <year>2004</year> 37 <year>2005</year> 38 <year>2007</year> 39 <year>2012</year> 40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 41 </copyright> 42 <copyright> 43 <year>2000</year> 44 <year>2001</year> 45 <holder>Internet Software Consortium.</holder> 46 </copyright> 47 </docinfo> 48 49 <refnamediv> 50 <refname>lwres_gabnrequest_render</refname> 51 <refname>lwres_gabnresponse_render</refname> 52 <refname>lwres_gabnrequest_parse</refname> 53 <refname>lwres_gabnresponse_parse</refname> 54 <refname>lwres_gabnresponse_free</refname> 55 <refname>lwres_gabnrequest_free</refname> 56 <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose> 57 </refnamediv> 58 <refsynopsisdiv> 59 <funcsynopsis> 60<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> 61<funcprototype> 62 <funcdef> 63lwres_result_t 64<function>lwres_gabnrequest_render</function></funcdef> 65 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 66 <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef> 67 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 68 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 69 </funcprototype> 70<funcprototype> 71 <funcdef> 72lwres_result_t 73<function>lwres_gabnresponse_render</function></funcdef> 74 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 75 <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef> 76 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 77 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 78 </funcprototype> 79<funcprototype> 80 <funcdef> 81lwres_result_t 82<function>lwres_gabnrequest_parse</function></funcdef> 83 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 84 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 85 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 86 <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> 87 </funcprototype> 88<funcprototype> 89 <funcdef> 90lwres_result_t 91<function>lwres_gabnresponse_parse</function></funcdef> 92 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 93 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 94 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 95 <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> 96 </funcprototype> 97<funcprototype> 98 <funcdef> 99void 100<function>lwres_gabnresponse_free</function></funcdef> 101 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 102 <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> 103 </funcprototype> 104<funcprototype> 105 <funcdef> 106void 107<function>lwres_gabnrequest_free</function></funcdef> 108 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 109 <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> 110 </funcprototype> 111</funcsynopsis> 112 </refsynopsisdiv> 113 <refsect1> 114 <title>DESCRIPTION</title> 115 <para> 116 These are low-level routines for creating and parsing 117 lightweight resolver name-to-address lookup request and 118 response messages. 119 </para> 120 <para> 121 There are four main functions for the getaddrbyname opcode. 122 One render function converts a getaddrbyname request structure — 123 <type>lwres_gabnrequest_t</type> — 124 to the lighweight resolver's canonical format. 125 It is complemented by a parse function that converts a packet in this 126 canonical format to a getaddrbyname request structure. 127 Another render function converts the getaddrbyname response structure 128 — <type>lwres_gabnresponse_t</type> — 129 to the canonical format. 130 This is complemented by a parse function which converts a packet in 131 canonical format to a getaddrbyname response structure. 132 </para> 133 <para> 134 These structures are defined in 135 <filename><lwres/lwres.h></filename>. 136 They are shown below. 137 </para> 138 <para><programlisting> 139#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U 140</programlisting> 141 </para> 142 <para><programlisting> 143typedef struct lwres_addr lwres_addr_t; 144typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; 145</programlisting> 146 </para> 147 <para><programlisting> 148typedef struct { 149 lwres_uint32_t flags; 150 lwres_uint32_t addrtypes; 151 lwres_uint16_t namelen; 152 char *name; 153} lwres_gabnrequest_t; 154</programlisting> 155 </para> 156 <para><programlisting> 157typedef struct { 158 lwres_uint32_t flags; 159 lwres_uint16_t naliases; 160 lwres_uint16_t naddrs; 161 char *realname; 162 char **aliases; 163 lwres_uint16_t realnamelen; 164 lwres_uint16_t *aliaslen; 165 lwres_addrlist_t addrs; 166 void *base; 167 size_t baselen; 168} lwres_gabnresponse_t; 169</programlisting> 170 </para> 171 172 <para><function>lwres_gabnrequest_render()</function> 173 uses resolver context <parameter>ctx</parameter> to convert 174 getaddrbyname request structure <parameter>req</parameter> to 175 canonical format. The packet header structure 176 <parameter>pkt</parameter> is initialised and transferred to 177 buffer <parameter>b</parameter>. 178 179 The contents of <parameter>*req</parameter> are then appended to 180 the buffer in canonical format. 181 <function>lwres_gabnresponse_render()</function> performs the 182 same task, except it converts a getaddrbyname response structure 183 <type>lwres_gabnresponse_t</type> to the lightweight resolver's 184 canonical format. 185 </para> 186 187 <para><function>lwres_gabnrequest_parse()</function> 188 uses context <parameter>ctx</parameter> to convert the contents 189 of packet <parameter>pkt</parameter> to a 190 <type>lwres_gabnrequest_t</type> structure. Buffer 191 <parameter>b</parameter> provides space to be used for storing 192 this structure. When the function succeeds, the resulting 193 <type>lwres_gabnrequest_t</type> is made available through 194 <parameter>*structp</parameter>. 195 196 <function>lwres_gabnresponse_parse()</function> offers the same 197 semantics as <function>lwres_gabnrequest_parse()</function> 198 except it yields a <type>lwres_gabnresponse_t</type> structure. 199 </para> 200 201 <para><function>lwres_gabnresponse_free()</function> 202 and <function>lwres_gabnrequest_free()</function> release the 203 memory in resolver context <parameter>ctx</parameter> that was 204 allocated to the <type>lwres_gabnresponse_t</type> or 205 <type>lwres_gabnrequest_t</type> structures referenced via 206 <parameter>structp</parameter>. 207 208 Any memory associated with ancillary buffers and strings for 209 those structures is also discarded. 210 </para> 211 </refsect1> 212 <refsect1> 213 <title>RETURN VALUES</title> 214 <para> 215 The getaddrbyname opcode functions 216 <function>lwres_gabnrequest_render()</function>, 217 <function>lwres_gabnresponse_render()</function> 218 <function>lwres_gabnrequest_parse()</function> 219 and 220 <function>lwres_gabnresponse_parse()</function> 221 all return 222 <errorcode>LWRES_R_SUCCESS</errorcode> 223 on success. 224 They return 225 <errorcode>LWRES_R_NOMEMORY</errorcode> 226 if memory allocation fails. 227 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 228 is returned if the available space in the buffer 229 <parameter>b</parameter> 230 is too small to accommodate the packet header or the 231 <type>lwres_gabnrequest_t</type> 232 and 233 <type>lwres_gabnresponse_t</type> 234 structures. 235 <function>lwres_gabnrequest_parse()</function> 236 and 237 <function>lwres_gabnresponse_parse()</function> 238 will return 239 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 240 if the buffer is not empty after decoding the received packet. 241 These functions will return 242 <errorcode>LWRES_R_FAILURE</errorcode> 243 if 244 <structfield>pktflags</structfield> 245 in the packet header structure 246 <type>lwres_lwpacket_t</type> 247 indicate that the packet is not a response to an earlier query. 248 </para> 249 </refsect1> 250 <refsect1> 251 <title>SEE ALSO</title> 252 <para><citerefentry> 253 <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> 254 </citerefentry> 255 </para> 256 </refsect1> 257</refentry><!-- 258 - Local variables: 259 - mode: sgml 260 - End: 261-->