| 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 */ |