1 /* 2 socket handling interface 3 Copyright (C) 1999-2003, Joe Orton <joe@manyfish.co.uk> 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 #include "ne_defs.h" 28 #include "ne_ssl.h" /* for ne_ssl_context */ 29 30 BEGIN_NEON_DECLS 31 32 #define NE_SOCK_ERROR (-1) 33 /* Read/Write timed out */ 34 #define NE_SOCK_TIMEOUT (-2) 35 /* Socket was closed */ 36 #define NE_SOCK_CLOSED (-3) 37 /* Connection was reset (e.g. server crashed) */ 38 #define NE_SOCK_RESET (-4) 39 /* Secure connection was subject to possible truncation attack. */ 40 #define NE_SOCK_TRUNC (-5) 41 42 /* ne_socket represents a TCP socket. */ 43 typedef struct ne_socket_s ne_socket; 44 45 /* ne_sock_addr represents an address object. */ 46 typedef struct ne_sock_addr_s ne_sock_addr; 47 48 #ifndef NE_INET_ADDR_DEFINED 49 typedef struct ne_inet_addr_s ne_inet_addr; 50 #endif 51 52 /* While neon itself doesn't require per-process global 53 * initialization, some platforms do, and so does the OpenSSL 54 * library. */ 55 int ne_sock_init(void); 56 57 /* Shutdown any underlying libraries. */ 58 void ne_sock_exit(void); 59 60 /* Resolve the given hostname. 'flags' are currently ignored. Hex 61 * string IPv6 addresses (e.g. `::1') may be enclosed in brackets 62 * (e.g. `[::1]'). */ 63 ne_sock_addr *ne_addr_resolve(const char *hostname, int flags); 64 65 /* Returns zero if name resolution was successful, non-zero on 66 * error. */ 67 int ne_addr_result(const ne_sock_addr *addr); 68 69 /* Returns the first network address associated with the 'addr' 70 * object. Undefined behaviour if ne_addr_result returns non-zero for 71 * 'addr'; otherwise, never returns NULL. */ 72 const ne_inet_addr *ne_addr_first(ne_sock_addr *addr); 73 74 /* Returns the next network address associated with the 'addr' object, 75 * or NULL if there are no more. */ 76 const ne_inet_addr *ne_addr_next(ne_sock_addr *addr); 77 78 /* NB: the pointers returned by ne_addr_first and ne_addr_next are 79 * valid until ne_addr_destroy is called for the corresponding 80 * ne_sock_addr object. They must not be passed to ne_iaddr_free. */ 81 82 /* If name resolution fails, copies the error string into 'buffer', 83 * which is of size 'bufsiz'. 'buffer' is returned. */ 84 char *ne_addr_error(const ne_sock_addr *addr, char *buffer, size_t bufsiz); 85 86 /* Destroys an address object created by ne_addr_resolve. */ 87 void ne_addr_destroy(ne_sock_addr *addr); 88 89 /* Network address type; IPv4 or IPv6 */ 90 typedef enum { 91 ne_iaddr_ipv4 = 0, 92 ne_iaddr_ipv6 93 } ne_iaddr_type; 94 95 /* Create a network address from raw byte representation (in network 96 * byte order) of given type. 'raw' must be four bytes for an IPv4 97 * address, 16 bytes for an IPv6 address. May return NULL if address 98 * type is not supported. */ 99 ne_inet_addr *ne_iaddr_make(ne_iaddr_type type, const unsigned char *raw); 100 101 /* Compare two network addresses i1 and i2; return non-zero if they 102 * are not equal. */ 103 int ne_iaddr_cmp(const ne_inet_addr *i1, const ne_inet_addr *i2); 104 105 /* Prints the string representation of network address 'ia' into the 106 * 'buffer', which is of size 'bufsiz'. Returns 'buffer'. */ 107 char *ne_iaddr_print(const ne_inet_addr *ia, char *buffer, size_t bufsiz); 108 109 /* Free a network address created using ne_iaddr_make. */ 110 void ne_iaddr_free(ne_inet_addr *addr); 111 112 /* Create a TCP socket; returns NULL on error. */ 113 ne_socket *ne_sock_create(void); 114 115 /* Connect the socket to server at address 'addr' on port 'port'. 116 * Returns non-zero if a connection could not be established. */ 117 int ne_sock_connect(ne_socket *sock, const ne_inet_addr *addr, 118 unsigned int port); 119 120 /* ne_sock_read reads up to 'count' bytes into 'buffer'. 121 * Returns: 122 * NE_SOCK_* on error, 123 * >0 length of data read into buffer. 124 */ 125 ssize_t ne_sock_read(ne_socket *sock, char *buffer, size_t count); 126 127 /* ne_sock_peek reads up to 'count' bytes into 'buffer', but the data 128 * will still be returned on a subsequent call to ne_sock_read or 129 * ne_sock_peek. 130 * Returns: 131 * NE_SOCK_* on error, 132 * >0 length of data read into buffer. 133 */ 134 ssize_t ne_sock_peek(ne_socket *sock, char *buffer, size_t count); 135 136 /* Block for up to 'n' seconds until data becomes available for reading 137 * on the socket. Returns: 138 * NE_SOCK_* on error, 139 * NE_SOCK_TIMEOUT if no data arrives in 'n' seconds. 140 * 0 if data arrived on the socket. 141 */ 142 int ne_sock_block(ne_socket *sock, int n); 143 144 /* Writes 'count' bytes of 'data' to the socket. 145 * Returns 0 on success, NE_SOCK_* on error. */ 146 int ne_sock_fullwrite(ne_socket *sock, const char *data, size_t count); 147 148 /* Reads an LF-terminated line into 'buffer', and NUL-terminate it. 149 * At most 'len' bytes are read (including the NUL terminator). 150 * Returns: 151 * NE_SOCK_* on error, 152 * >0 number of bytes read (including NUL terminator) 153 */ 154 ssize_t ne_sock_readline(ne_socket *sock, char *buffer, size_t len); 155 156 /* Read exactly 'len' bytes into buffer; returns 0 on success, SOCK_* 157 * on error. */ 158 ssize_t ne_sock_fullread(ne_socket *sock, char *buffer, size_t len); 159 160 /* Accept a connection on listening socket 'fd'. */ 161 int ne_sock_accept(ne_socket *sock, int fd); 162 163 /* Returns the file descriptor used for socket 'sock'. */ 164 int ne_sock_fd(const ne_socket *sock); 165 166 /* Close the socket, and destroy the socket object. Returns non-zero 167 * on error. */ 168 int ne_sock_close(ne_socket *sock); 169 170 /* Return current error string for socket. */ 171 const char *ne_sock_error(const ne_socket *sock); 172 173 /* Set read timeout for socket. */ 174 void ne_sock_read_timeout(ne_socket *sock, int timeout); 175 176 /* Returns the standard TCP port for the given service, or zero if 177 * none is known. */ 178 int ne_service_lookup(const char *name); 179 180 /* Enable SSL with an already-negotiated SSL socket. */ 181 void ne_sock_switch_ssl(ne_socket *sock, void *ssl); 182 183 /* Perform an SSL negotiation on 'sock', using given context. */ 184 int ne_sock_connect_ssl(ne_socket *sock, ne_ssl_context *ctx); 185 186 /* Return SSL socket object in use for 'sock'. */ 187 typedef struct ne_ssl_socket_s ne_ssl_socket; 188 ne_ssl_socket *ne_sock_sslsock(ne_socket *sock); 189 190 END_NEON_DECLS 191 192 #endif /* NE_SOCKET_H */ 193