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_gnba</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_gnbarequest_render</refname> 50 <refname>lwres_gnbaresponse_render</refname> 51 <refname>lwres_gnbarequest_parse</refname> 52 <refname>lwres_gnbaresponse_parse</refname> 53 <refname>lwres_gnbaresponse_free</refname> 54 <refname>lwres_gnbarequest_free</refname> 55 <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose> 56 </refnamediv> 57 58 <refsynopsisdiv> 59 60 <funcsynopsis> 61<funcsynopsisinfo> 62#include <lwres/lwres.h> 63</funcsynopsisinfo> 64 65<funcprototype> 66 <funcdef> 67lwres_result_t 68<function>lwres_gnbarequest_render</function> 69</funcdef> 70 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 71 <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef> 72 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 73 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 74 </funcprototype> 75 76<funcprototype> 77 <funcdef> 78lwres_result_t 79<function>lwres_gnbaresponse_render</function> 80</funcdef> 81 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 82 <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef> 83 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 84 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 85 </funcprototype> 86<funcprototype> 87 <funcdef> 88lwres_result_t 89<function>lwres_gnbarequest_parse</function></funcdef> 90 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 91 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 92 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 93 <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef> 94 </funcprototype> 95<funcprototype> 96 <funcdef> 97lwres_result_t 98<function>lwres_gnbaresponse_parse</function></funcdef> 99 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 100 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 101 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 102 <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef> 103 </funcprototype> 104 105<funcprototype> 106 <funcdef> 107void 108<function>lwres_gnbaresponse_free</function> 109</funcdef> 110 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 111 <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef> 112 </funcprototype> 113<funcprototype> 114 <funcdef> 115void 116<function>lwres_gnbarequest_free</function></funcdef> 117 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 118 <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef> 119 </funcprototype> 120</funcsynopsis> 121 122 </refsynopsisdiv> 123 124 <refsect1> 125 <title>DESCRIPTION</title> 126 <para> 127 These are low-level routines for creating and parsing 128 lightweight resolver address-to-name lookup request and 129 response messages. 130 </para> 131 <para> 132 There are four main functions for the getnamebyaddr opcode. 133 One render function converts a getnamebyaddr request structure — 134 <type>lwres_gnbarequest_t</type> — 135 to the lightweight resolver's canonical format. 136 It is complemented by a parse function that converts a packet in this 137 canonical format to a getnamebyaddr request structure. 138 Another render function converts the getnamebyaddr response structure 139 — 140 <type>lwres_gnbaresponse_t</type> 141 to the canonical format. 142 This is complemented by a parse function which converts a packet in 143 canonical format to a getnamebyaddr response structure. 144 </para> 145 <para> 146 These structures are defined in 147 <filename>lwres/lwres.h</filename>. 148 They are shown below. 149 </para> 150 <para><programlisting> 151#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U 152</programlisting> 153 </para> 154 <para><programlisting> 155typedef struct { 156 lwres_uint32_t flags; 157 lwres_addr_t addr; 158} lwres_gnbarequest_t; 159</programlisting> 160 </para> 161 <para><programlisting> 162typedef struct { 163 lwres_uint32_t flags; 164 lwres_uint16_t naliases; 165 char *realname; 166 char **aliases; 167 lwres_uint16_t realnamelen; 168 lwres_uint16_t *aliaslen; 169 void *base; 170 size_t baselen; 171} lwres_gnbaresponse_t; 172</programlisting> 173 </para> 174 175 <para><function>lwres_gnbarequest_render()</function> 176 uses resolver context <varname>ctx</varname> to convert 177 getnamebyaddr request structure <varname>req</varname> to 178 canonical format. The packet header structure 179 <varname>pkt</varname> is initialised and transferred to buffer 180 <varname>b</varname>. The contents of <varname>*req</varname> 181 are then appended to the buffer in canonical format. 182 <function>lwres_gnbaresponse_render()</function> performs the 183 same task, except it converts a getnamebyaddr response structure 184 <type>lwres_gnbaresponse_t</type> to the lightweight resolver's 185 canonical format. 186 </para> 187 188 <para><function>lwres_gnbarequest_parse()</function> 189 uses context <varname>ctx</varname> to convert the contents of 190 packet <varname>pkt</varname> to a 191 <type>lwres_gnbarequest_t</type> structure. Buffer 192 <varname>b</varname> provides space to be used for storing this 193 structure. When the function succeeds, the resulting 194 <type>lwres_gnbarequest_t</type> is made available through 195 <varname>*structp</varname>. 196 <function>lwres_gnbaresponse_parse()</function> offers the same 197 semantics as <function>lwres_gnbarequest_parse()</function> 198 except it yields a <type>lwres_gnbaresponse_t</type> structure. 199 </para> 200 201 <para><function>lwres_gnbaresponse_free()</function> 202 and <function>lwres_gnbarequest_free()</function> release the 203 memory in resolver context <varname>ctx</varname> that was 204 allocated to the <type>lwres_gnbaresponse_t</type> or 205 <type>lwres_gnbarequest_t</type> structures referenced via 206 <varname>structp</varname>. Any memory associated with 207 ancillary buffers and strings for those structures is also 208 discarded. 209 </para> 210 </refsect1> 211 212 <refsect1> 213 <title>RETURN VALUES</title> 214 <para> 215 The getnamebyaddr opcode functions 216 <function>lwres_gnbarequest_render()</function>, 217 <function>lwres_gnbaresponse_render()</function> 218 <function>lwres_gnbarequest_parse()</function> 219 and 220 <function>lwres_gnbaresponse_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 <varname>b</varname> 230 is too small to accommodate the packet header or the 231 <type>lwres_gnbarequest_t</type> 232 and 233 <type>lwres_gnbaresponse_t</type> 234 structures. 235 <function>lwres_gnbarequest_parse()</function> 236 and 237 <function>lwres_gnbaresponse_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--> 262