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