utils: Handle NULL consistently if memwipe() is implemented via explicit_bzero()
[strongswan.git] / src / libstrongswan / networking / host.h
1 /*
2 * Copyright (C) 2006-2014 Tobias Brunner
3 * Copyright (C) 2006 Daniel Roethlisberger
4 * Copyright (C) 2005-2008 Martin Willi
5 * Copyright (C) 2005 Jan Hutter
6 * HSR Hochschule fuer Technik Rapperswil
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU General Public License as published by the
10 * Free Software Foundation; either version 2 of the License, or (at your
11 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12 *
13 * This program is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 * for more details.
17 */
18
19 /**
20 * @defgroup host host
21 * @{ @ingroup networking
22 */
23
24 #ifndef HOST_H_
25 #define HOST_H_
26
27 #include <utils/utils.h>
28 #include <utils/chunk.h>
29
30 typedef enum host_diff_t host_diff_t;
31 typedef struct host_t host_t;
32
33 #include <stdlib.h>
34 #include <stdio.h>
35 #include <sys/types.h>
36
37 /**
38 * Representates a Host
39 *
40 * Host object, identifies a address:port pair and defines some
41 * useful functions on it.
42 */
43 struct host_t {
44
45 /**
46 * Build a clone of this host object.
47 *
48 * @return cloned host
49 */
50 host_t *(*clone) (host_t *this);
51
52 /**
53 * Get a pointer to the internal sockaddr struct.
54 *
55 * This is used for sending and receiving via sockets.
56 *
57 * @return pointer to the internal sockaddr structure
58 */
59 sockaddr_t *(*get_sockaddr) (host_t *this);
60
61 /**
62 * Get the length of the sockaddr struct.
63 *
64 * Depending on the family, the length of the sockaddr struct
65 * is different. Use this function to get the length of the sockaddr
66 * struct returned by get_sock_addr.
67 *
68 * This is used for sending and receiving via sockets.
69 *
70 * @return length of the sockaddr struct
71 */
72 socklen_t *(*get_sockaddr_len) (host_t *this);
73
74 /**
75 * Gets the family of the address
76 *
77 * @return family
78 */
79 int (*get_family) (host_t *this);
80
81 /**
82 * Checks if the ip address of host is set to default route.
83 *
84 * @return TRUE if host is 0.0.0.0 or 0::0, FALSE otherwise
85 */
86 bool (*is_anyaddr) (host_t *this);
87
88 /**
89 * Get the address of this host as chunk_t
90 *
91 * Returned chunk points to internal data.
92 *
93 * @return address blob
94 */
95 chunk_t (*get_address) (host_t *this);
96
97 /**
98 * Get the port of this host
99 *
100 * @return port number
101 */
102 uint16_t (*get_port) (host_t *this);
103
104 /**
105 * Set the port of this host
106 *
107 * @param port port number
108 */
109 void (*set_port) (host_t *this, uint16_t port);
110
111 /**
112 * Compare the ips of two hosts hosts.
113 *
114 * @param other the other to compare
115 * @return TRUE if addresses are equal.
116 */
117 bool (*ip_equals) (host_t *this, host_t *other);
118
119 /**
120 * Compare two hosts, with port.
121 *
122 * @param other the other to compare
123 * @return TRUE if addresses and ports are equal.
124 */
125 bool (*equals) (host_t *this, host_t *other);
126
127 /**
128 * Destroy this host object.
129 */
130 void (*destroy) (host_t *this);
131 };
132
133 /**
134 * Constructor to create a host_t object from an address string.
135 *
136 * @param string string of an address, such as "152.96.193.130"
137 * @param port port number
138 * @return host_t, NULL if string not an address.
139 */
140 host_t *host_create_from_string(char *string, uint16_t port);
141
142 /**
143 * Same as host_create_from_string(), but with the option to enforce a family.
144 *
145 * @param string string of an address
146 * @param family address family, or AF_UNSPEC
147 * @param port port number
148 * @return host_t, NULL if string not an address.
149 */
150 host_t *host_create_from_string_and_family(char *string, int family,
151 uint16_t port);
152
153 /**
154 * Constructor to create a host_t from a DNS name.
155 *
156 * @param string hostname to resolve
157 * @param family family to prefer, 0 for first match
158 * @param port port number
159 * @return host_t, NULL lookup failed
160 */
161 host_t *host_create_from_dns(char *string, int family, uint16_t port);
162
163 /**
164 * Constructor to create a host_t object from an address chunk.
165 *
166 * If family is AF_UNSPEC, it is guessed using address.len.
167 *
168 * @param family Address family, such as AF_INET or AF_INET6
169 * @param address address as chunk_t in network order
170 * @param port port number
171 * @return host_t, NULL if family not supported/chunk invalid
172 */
173 host_t *host_create_from_chunk(int family, chunk_t address, uint16_t port);
174
175 /**
176 * Constructor to create a host_t object from a sockaddr struct
177 *
178 * @param sockaddr sockaddr struct which contains family, address and port
179 * @return host_t, NULL if family not supported
180 */
181 host_t *host_create_from_sockaddr(sockaddr_t *sockaddr);
182
183 /**
184 * Parse a range definition (1.2.3.0-1.2.3.5), return the two hosts.
185 *
186 * The two hosts are not ordered, from is simply the first, to is the second,
187 * from is not necessarily smaller.
188 *
189 * @param string string to parse
190 * @param from returns the first address (out)
191 * @param to returns the second address (out)
192 * @return TRUE if parsed successfully, FALSE otherwise
193 */
194 bool host_create_from_range(char *string, host_t **from, host_t **to);
195
196 /**
197 * Create a host from a CIDR subnet definition (1.2.3.0/24), return bits.
198 *
199 * @param string string to parse
200 * @param bits gets the number of network bits in CIDR notation
201 * @return network start address, NULL on error
202 */
203 host_t *host_create_from_subnet(char *string, int *bits);
204
205 /**
206 * Create a netmask host having the first netbits bits set.
207 *
208 * @param family family of the netmask host
209 * @param netbits number of leading bits set in the host
210 * @return netmask host
211 */
212 host_t *host_create_netmask(int family, int netbits);
213
214 /**
215 * Create a host without an address, a "any" host.
216 *
217 * @param family family of the any host
218 * @return host_t, NULL if family not supported
219 */
220 host_t *host_create_any(int family);
221
222 /**
223 * printf hook function for host_t.
224 *
225 * Arguments are:
226 * host_t *host
227 * Use #-modifier to include port number
228 * Use +-modifier to force numeric representation (instead of e.g. %any)
229 */
230 int host_printf_hook(printf_hook_data_t *data, printf_hook_spec_t *spec,
231 const void *const *args);
232
233 #endif /** HOST_H_ @}*/