1<refentry id="refiaddr">
2
3  <refmeta>
4    <refentrytitle>ne_iaddr_make</refentrytitle>
5    <manvolnum>3</manvolnum>
6  </refmeta>
7
8  <refnamediv>
9    <refname id="ne_iaddr_make">ne_iaddr_make</refname>
10    <refname id="ne_iaddr_cmp">ne_iaddr_cmp</refname>
11    <refname id="ne_iaddr_print">ne_iaddr_print</refname>
12    <refname id="ne_iaddr_typeof">ne_iaddr_typeof</refname>
13    <refname id="ne_iaddr_parse">ne_iaddr_parse</refname>
14    <refname id="ne_iaddr_raw">ne_iaddr_raw</refname>
15    <refname id="ne_iaddr_reverse">ne_iaddr_reverse</refname>
16    <refname id="ne_iaddr_free">ne_iaddr_free</refname>
17    <refpurpose>functions to manipulate network addresses</refpurpose>
18  </refnamediv>
19  
20  <refsynopsisdiv>
21
22    <funcsynopsis>
23
24      <funcsynopsisinfo>#include &lt;ne_socket.h&gt;
25
26typedef enum {
27    ne_iaddr_ipv4 = 0,
28    ne_iaddr_ipv6
29} <type>ne_iaddr_type</type>;</funcsynopsisinfo>
30
31      <funcprototype>
32        <funcdef>ne_inet_addr *<function>ne_iaddr_make</function></funcdef>
33        <paramdef>ne_iaddr_type <parameter>type</parameter></paramdef>
34        <paramdef>const unsigned char *<parameter>raw</parameter></paramdef>
35      </funcprototype>
36
37      <funcprototype>
38        <funcdef>int <function>ne_iaddr_cmp</function></funcdef>
39        <paramdef>const ne_inet_addr *<parameter>ia1</parameter></paramdef>
40        <paramdef>const ne_inet_addr *<parameter>ia2</parameter></paramdef>
41      </funcprototype>
42
43      <funcprototype>
44        <funcdef>char *<function>ne_iaddr_print</function></funcdef>
45        <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
46        <paramdef>char *<parameter>buffer</parameter></paramdef>
47        <paramdef>size_t <parameter>bufsiz</parameter></paramdef>
48      </funcprototype>
49
50      <funcprototype>
51        <funcdef>ne_iaddr_type <function>ne_iaddr_typeof</function></funcdef>
52        <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
53      </funcprototype>
54
55      <funcprototype>
56        <funcdef>ne_inet_addr *<function>ne_iaddr_parse</function></funcdef>
57        <paramdef>const char *<parameter>address</parameter></paramdef>
58        <paramdef>ne_iaddr_type <parameter>type</parameter></paramdef>
59      </funcprototype>
60
61      <funcprototype>
62        <funcdef>unsigned char *<function>ne_iaddr_raw</function></funcdef>
63        <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
64        <paramdef>unsigned char *<parameter>buffer</parameter></paramdef>
65      </funcprototype>
66
67      <funcprototype>
68        <funcdef>int <function>ne_iaddr_reverse</function></funcdef>
69        <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
70        <paramdef>char *<parameter>buffer</parameter></paramdef>
71        <paramdef>size_t <parameter>buflen</parameter></paramdef>
72      </funcprototype>
73
74      <funcprototype>
75        <funcdef>void <function>ne_iaddr_free</function></funcdef>
76        <paramdef>const ne_inet_addr *<parameter>ia</parameter></paramdef>
77      </funcprototype>
78
79    </funcsynopsis>
80
81  </refsynopsisdiv>
82
83  <refsect1>
84    <title>Description</title>
85
86    <para><function>ne_iaddr_make</function> creates an
87    <type>ne_inet_addr</type> object from a raw binary network
88    address; for instance the four bytes <literal>0x7f 0x00 0x00
89    0x01</literal> represent the IPv4 address
90    <literal>127.0.0.1</literal>.  The object returned is suitable for
91    passing to <function>ne_sock_connect</function>.  A binary IPv4
92    address contains four bytes; a binary IPv6 address contains
93    sixteen bytes; addresses passed must be in network byte
94    order.</para>
95
96    <para><function>ne_iaddr_cmp</function> compares two network
97    address objects; returning zero only if they are identical.  The
98    objects need not have the same address type; if the addresses are
99    not of the same type, the return value is guaranteed to be
100    non-zero.</para>
101
102    <para><function>ne_iaddr_print</function> prints a human-readable
103    string representation of a network address into a buffer, for
104    instance the string <literal>"127.0.0.1"</literal>.</para>
105
106    <para><function>ne_iaddr_typeof</function> returns the type of the
107    given network address object.</para>
108
109    <para><function>ne_iaddr_parse</function> parses a string
110    representation of a network address (such as
111    <literal>"127.0.0.1"</literal> and creates a network address
112    object to represent the parsed address.</para>
113
114    <para><function>ne_iaddr_raw</function> writes the raw byte
115    representation of a network address to the provided buffer.  The
116    bytes are written in network byte order; the buffer must be of
117    suitable length for the type of address (4 bytes for an IPv4
118    address, 16 bytes for an IPv6 address).</para>
119
120    <para><function>ne_iaddr_reverse</function> performs a reverse
121    name lookup on the address object, writing the (first) hostname
122    associated with the IP address to the provided buffer.  If the
123    hostname is longer than the buffer it will be silently truncated;
124    on success the string written to the buffer is always
125    &nul;-terminated.</para>
126
127    <para><function>ne_iaddr_free</function> releases the memory
128    associated with a network address object.</para>
129
130  </refsect1>
131
132  <refsect1>
133    <title>Return value</title>
134
135    <para><function>ne_iaddr_make</function> returns &null; if the
136    address type passed is not supported (for instance on a platform
137    which does not support IPv6).</para>
138
139    <para><function>ne_iaddr_print</function> returns the
140    <parameter>buffer</parameter> pointer, and never &null;.</para>
141
142    <para><function>ne_iaddr_parse</function> returns a network
143    address object on success, or &null; on failure to parse the
144    <parameter>address</parameter> parameter.</para>
145
146    <para><function>ne_iaddr_reverse</function> returns zero on
147    success or non-zero if no hostname is associated with the
148    address.</para>
149
150    <para><function>ne_iaddr_raw</function> returns the
151    <parameter>buffer</parameter> parameter, and never &null;.</para>
152
153  </refsect1>
154
155  <refsect1>
156    <title>Examples</title>
157
158    <para>The following example connects a socket to port 80 at the
159    address <literal>127.0.0.1</literal>.</para>
160 
161    <programlisting>unsigned char addr[] = "\0x7f\0x00\0x00\0x01";
162ne_inet_addr *ia;
163
164ia = ne_iaddr_make(ne_iaddr_ipv4, addr);
165if (ia != NULL) {
166    ne_socket *sock = ne_sock_connect(ia, 80);
167    ne_iaddr_free(ia);
168    /* ... */
169} else {
170    /* ... */
171}</programlisting>
172
173  </refsect1>
174
175  <refsect1>
176    <title>See also</title>
177
178    <para><xref linkend="ne_addr_resolve"/></para>
179  </refsect1>
180
181</refentry>
182
183