Debian Codegraph @

deps/libneon/src/ne_socket.h

raw
1 /*
2 socket handling interface
3 Copyright (C) 1999-2010, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_SOCKET_H
23 #define NE_SOCKET_H
24
25 #include <sys/types.h>
26
27 #ifdef WIN32
28 #include <stdlib.h> /* for size_t */
29 #endif
30
31 #include "ne_defs.h"
32 #include "ne_ssl.h" /* for ne_ssl_context */
33
34 NE_BEGIN_DECLS
35
36 #define NE_SOCK_ERROR (-1)
37 /* Read/Write timed out */
38 #define NE_SOCK_TIMEOUT (-2)
39 /* Socket was closed */
40 #define NE_SOCK_CLOSED (-3)
41 /* Connection was reset (e.g. server crashed) */
42 #define NE_SOCK_RESET (-4)
43 /* Secure connection was closed without proper SSL shutdown. */
44 #define NE_SOCK_TRUNC (-5)
45
46 /* ne_socket represents a TCP socket. */
47 typedef struct ne_socket_s ne_socket;
48
49 /* ne_sock_addr represents an address object. */
50 typedef struct ne_sock_addr_s ne_sock_addr;
51
52 #ifndef NE_INET_ADDR_DEFINED
53 typedef struct ne_inet_addr_s ne_inet_addr;
54 #endif
55
56 /* Perform process-global initialization of any libraries in use.
57 * Returns non-zero on error. */
58 int ne_sock_init(void);
59
60 /* Perform process-global shutdown of any libraries in use. This
61 * function only has effect when it has been called an equal number of
62 * times to ne_sock_init() for the process. */
63 void ne_sock_exit(void);
64
65 /* Resolve the given hostname. 'flags' must be zero. Hex
66 * string IPv6 addresses (e.g. `::1') may be enclosed in brackets
67 * (e.g. `[::1]'). */
68 ne_sock_addr *ne_addr_resolve(const char *hostname, int flags);
69
70 /* Returns zero if name resolution was successful, non-zero on
71 * error. */
72 int ne_addr_result(const ne_sock_addr *addr);
73
74 /* Returns the first network address associated with the 'addr'
75 * object. Undefined behaviour if ne_addr_result returns non-zero for
76 * 'addr'; otherwise, never returns NULL. */
77 const ne_inet_addr *ne_addr_first(ne_sock_addr *addr);
78
79 /* Returns the next network address associated with the 'addr' object,
80 * or NULL if there are no more. */
81 const ne_inet_addr *ne_addr_next(ne_sock_addr *addr);
82
83 /* NB: the pointers returned by ne_addr_first and ne_addr_next are
84 * valid until ne_addr_destroy is called for the corresponding
85 * ne_sock_addr object. They must not be passed to ne_iaddr_free. */
86
87 /* If name resolution fails, copies the error string into 'buffer',
88 * which is of size 'bufsiz'. 'buffer' is returned. */
89 char *ne_addr_error(const ne_sock_addr *addr, char *buffer, size_t bufsiz);
90
91 /* Destroys an address object created by ne_addr_resolve. */
92 void ne_addr_destroy(ne_sock_addr *addr);
93
94 /* Network address type; IPv4 or IPv6 */
95 typedef enum {
96 ne_iaddr_ipv4 = 0,
97 ne_iaddr_ipv6
98 } ne_iaddr_type;
99
100 /* Create a network address object from raw byte representation (in
101 * network byte order) of given type. 'raw' must be four bytes for an
102 * IPv4 address, 16 bytes for an IPv6 address. May return NULL if
103 * address type is not supported. */
104 ne_inet_addr *ne_iaddr_make(ne_iaddr_type type, const unsigned char *raw);
105
106 /* Compare two network address objects i1 and i2; returns zero if they
107 * are equivalent or non-zero otherwise. */
108 int ne_iaddr_cmp(const ne_inet_addr *i1, const ne_inet_addr *i2);
109
110 /* Return the type of the given network address object. */
111 ne_iaddr_type ne_iaddr_typeof(const ne_inet_addr *ia);
112
113 /* Print the string representation of network address 'ia' into the
114 * buffer 'buffer', which is of length 'bufsiz'. Returns 'buffer'. */
115 char *ne_iaddr_print(const ne_inet_addr *ia, char *buffer, size_t bufsiz);
116
117 /* Dump the raw byte representation (in network byte order) of address
118 * 'ia' into the buffer 'buffer', which must be of a suitable length
119 * (4 bytes for an IPv4 address, 16 bytes for an IPv6 address).
120 * Returns 'buffer'. */
121 unsigned char *ne_iaddr_raw(const ne_inet_addr *ia, unsigned char *buffer);
122
123 /* Perform the reverse name lookup on network address 'ia', placing
124 * the returned name in the 'buf' buffer (of length 'bufsiz') if
125 * successful. Returns zero on success, or non-zero on error. */
126 int ne_iaddr_reverse(const ne_inet_addr *ia, char *buf, size_t bufsiz);
127
128 /* Convert network address string 'addr' (for example, "127.0.0.1")
129 * into a network address object. Returns NULL on parse error. If
130 * non-NULL, return value must be freed using ne_iaddr_free. */
131 ne_inet_addr *ne_iaddr_parse(const char *addr, ne_iaddr_type type);
132
133 /* Destroy a network address object created using ne_iaddr_make or
134 * ne_iaddr_parse. */
135 void ne_iaddr_free(ne_inet_addr *addr);
136
137 /* Create a socket object; returns NULL on error. */
138 ne_socket *ne_sock_create(void);
139
140 /* Specify an address to which the local end of the socket will be
141 * bound during a subsequent ne_sock_connect() call. If the address
142 * passed to ne_sock_connect() is of a different type (family) to
143 * 'addr', 'addr' is ignored. Either 'addr' may be NULL, to use the
144 * given port with unspecified address, or 'port' may be 0, to use the
145 * given address with an unspecified port.
146 *
147 * (Note: This function is not equivalent to a BSD socket bind(), it
148 * only takes effect during the _connect() call). */
149 void ne_sock_prebind(ne_socket *sock, const ne_inet_addr *addr,
150 unsigned int port);
151
152 /* Connect the socket to server at address 'addr' on port 'port'.
153 * Returns zero on success, NE_SOCK_TIMEOUT if a timeout occurs when a
154 * non-zero connect timeout is configured (and is supported), or
155 * NE_SOCK_ERROR on failure. */
156 int ne_sock_connect(ne_socket *sock, const ne_inet_addr *addr,
157 unsigned int port);
158
159 /* Read up to 'count' bytes from socket into 'buffer'. Returns:
160 * NE_SOCK_* on error,
161 * >0 length of data read into buffer (may be less than 'count')
162 */
163 ssize_t ne_sock_read(ne_socket *sock, char *buffer, size_t count);
164
165 /* Read up to 'count' bytes into 'buffer', leaving the data available
166 * in the socket buffer to be returned by a subsequent call to
167 * ne_sock_read or ne_sock_peek. Returns:
168 * NE_SOCK_* on error,
169 * >0 length of data read into buffer.
170 */
171 ssize_t ne_sock_peek(ne_socket *sock, char *buffer, size_t count);
172
173 /* Block for up to 'n' seconds until data becomes available for reading
174 * from the socket. Returns:
175 * NE_SOCK_* on error,
176 * NE_SOCK_TIMEOUT if no data arrives in 'n' seconds,
177 * 0 if data arrived on the socket.
178 */
179 int ne_sock_block(ne_socket *sock, int n);
180
181 /* Write 'count' bytes of 'data' to the socket. Guarantees to either
182 * write all the bytes or to fail. Returns 0 on success, or NE_SOCK_*
183 * on error. */
184 int ne_sock_fullwrite(ne_socket *sock, const char *data, size_t count);
185
186 /* I/O vector. */
187 struct ne_iovec {
188 void *base;
189 size_t len;
190 };
191
192 /* Writes 'count' blocks described by 'vector' to the socket.
193 * Guarantees to either write all the bytes or to fail. Count must be
194 * greater than zero and smaller than the system-defined maximum
195 * vector limit. Returns 0 on success, or NE_SOCK_* on error. */
196 int ne_sock_fullwritev(ne_socket *sock, const struct ne_iovec *vector,
197 int count);
198
199 /* Read an LF-terminated line into 'buffer', and NUL-terminate it.
200 * At most 'len' bytes are read (including the NUL terminator).
201 * Returns:
202 * NE_SOCK_* on error,
203 * >0 number of bytes read (including NUL terminator)
204 */
205 ssize_t ne_sock_readline(ne_socket *sock, char *buffer, size_t len);
206
207 /* Read exactly 'len' bytes into buffer, or fail; returns 0 on
208 * success, NE_SOCK_* on error. */
209 ssize_t ne_sock_fullread(ne_socket *sock, char *buffer, size_t len);
210
211 /* Accepts a connection from listening socket 'fd' and places the
212 * socket in 'sock'. Returns zero on success or -1 on failure. */
213 int ne_sock_accept(ne_socket *sock, int fd);
214
215 /* Returns the file descriptor used for socket 'sock'. */
216 int ne_sock_fd(const ne_socket *sock);
217
218 /* Return address of peer, or NULL on error. The returned address
219 * must be destroyed by caller using ne_iaddr_free. */
220 ne_inet_addr *ne_sock_peer(ne_socket *sock, unsigned int *port);
221
222 /* Close the socket and destroy the socket object. If SSL is in use
223 * for the socket, a closure alert is sent to initiate a clean
224 * shutdown, but this function does not wait for the peer's response.
225 * Returns zero on success, or non-zero on failure. */
226 int ne_sock_close(ne_socket *sock);
227
228 /* Return current error string for socket. */
229 const char *ne_sock_error(const ne_socket *sock);
230
231 /* Set the error string for the socket; takes printf-like format
232 * string. */
233 void ne_sock_set_error(ne_socket *sock, const char *format, ...)
234 ne_attribute((format (printf, 2, 3)));
235
236 /* Set read timeout for socket, in seconds; must be a non-zero
237 * positive integer. */
238 void ne_sock_read_timeout(ne_socket *sock, int timeout);
239
240 /* Set connect timeout for socket, in seconds; must be a positive
241 * integer. If a timeout of 'zero' is used then then no explicit
242 * timeout handling will be used for ne_sock_connect(), and the
243 * connect call will only timeout as dictated by the TCP stack. */
244 void ne_sock_connect_timeout(ne_socket *sock, int timeout);
245
246 /* Negotiate an SSL connection on socket as an SSL server, using given
247 * SSL context. */
248 int ne_sock_accept_ssl(ne_socket *sock, ne_ssl_context *ctx);
249
250 /* Negotiate an SSL connection on socket as an SSL client, using given
251 * SSL context. The 'userdata' parameter is associated with the
252 * underlying SSL library's socket structure for use in callbacks.
253 * Returns zero on success, or non-zero on error. */
254 int ne_sock_connect_ssl(ne_socket *sock, ne_ssl_context *ctx,
255 void *userdata);
256
257 /* Retrieve the session ID of the current SSL session. If 'buf' is
258 * non-NULL, on success, copies at most *buflen bytes to 'buf' and
259 * sets *buflen to the exact number of bytes copied. If 'buf' is
260 * NULL, on success, sets *buflen to the length of the session ID.
261 * Returns zero on success, non-zero on error. */
262 int ne_sock_sessid(ne_socket *sock, unsigned char *buf, size_t *buflen);
263
264 /* Return human-readable name of SSL/TLS cipher used for connection,
265 * or NULL if none. The format of this string is not intended to be
266 * fixed or parseable, but is informational only. Return value is
267 * NUL-terminated malloc-allocated string if not NULL, which must be
268 * freed by the caller. */
269 char *ne_sock_cipher(ne_socket *sock);
270
271 /* SOCKS proxy protocol version: */
272 enum ne_sock_sversion {
273 NE_SOCK_SOCKSV4 = 0,
274 NE_SOCK_SOCKSV4A,
275 NE_SOCK_SOCKSV5
276 };
277
278 /* Given a socket 'sock' which is connected to a SOCKS proxy, initiate
279 * a connection to a destination server using that proxy, specified
280 * either by network address or hostname, at given port 'port'.
281 *
282 * If 'vers' is NE_SOCKS_V4, addr must be an IPv4 address; hostname
283 * and password are ignored; username must be non-NULL.
284 *
285 * If 'vers' is NE_SOCKS_V4A, hostname must be non-NULL; addr is
286 * ignored; password is ignored; username must be non-NULL.
287 *
288 * If 'vers' is NE_SOCKS_V5, addr may be NULL, in which case hostname
289 * must be non-NULL. addr if non-NULL may be an IPv4 or IPv6 address;
290 * username may be NULL, in which case password is ignored. If
291 * username is non-NULL password must also be non-NULL.
292 *
293 * Returns 0 on success, or NE_SOCK_* on failure - in which case, the
294 * socket error string is set. On failure, the socket must be closed
295 * by the caller.
296 */
297 int ne_sock_proxy(ne_socket *sock, enum ne_sock_sversion vers,
298 const ne_inet_addr *addr, const char *hostname,
299 unsigned int port,
300 const char *username, const char *password);
301
302 NE_END_DECLS
303
304 #endif /* NE_SOCKET_H */