/* socket handling interface Copyright (C) 1999-2010, Joe Orton This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA */ #ifndef NE_SOCKET_H #define NE_SOCKET_H #include #ifdef WIN32 #include /* for size_t */ #endif #include "ne_defs.h" #include "ne_ssl.h" /* for ne_ssl_context */ NE_BEGIN_DECLS #define NE_SOCK_ERROR (-1) /* Read/Write timed out */ #define NE_SOCK_TIMEOUT (-2) /* Socket was closed */ #define NE_SOCK_CLOSED (-3) /* Connection was reset (e.g. server crashed) */ #define NE_SOCK_RESET (-4) /* Secure connection was closed without proper SSL shutdown. */ #define NE_SOCK_TRUNC (-5) /* Reserved value - (-6) */ /* ne_socket represents a TCP socket. */ typedef struct ne_socket_s ne_socket; /* ne_sock_addr represents an address object. */ typedef struct ne_sock_addr_s ne_sock_addr; #ifndef NE_INET_ADDR_DEFINED typedef struct ne_inet_addr_s ne_inet_addr; #endif /* Perform process-global initialization of any libraries in use. * Returns non-zero on error. */ int ne_sock_init(void); /* Perform process-global shutdown of any libraries in use. This * function only has effect when it has been called an equal number of * times to ne_sock_init() for the process. */ void ne_sock_exit(void); #define NE_ADDR_CANON (0x01) /* Resolve the given hostname. Hex string IPv6 addresses (e.g. `::1') * may be enclosed in brackets (e.g. `[::1]'). 'flags' should be * zero, or if NE_ADDR_CANON is passed, the canonical name for the * hostname will be determined. */ ne_sock_addr *ne_addr_resolve(const char *hostname, int flags); /* Returns zero if name resolution was successful, non-zero on * error. */ int ne_addr_result(const ne_sock_addr *addr); /* Returns the first network address associated with the 'addr' * object. Undefined behaviour if ne_addr_result returns non-zero for * 'addr'; otherwise, never returns NULL. */ const ne_inet_addr *ne_addr_first(ne_sock_addr *addr); /* Returns the next network address associated with the 'addr' object, * or NULL if there are no more. */ const ne_inet_addr *ne_addr_next(ne_sock_addr *addr); /* NB: the pointers returned by ne_addr_first and ne_addr_next are * valid until ne_addr_destroy is called for the corresponding * ne_sock_addr object. They must not be passed to ne_iaddr_free. */ /* If name resolution fails, copies the error string into 'buffer', * which is of size 'bufsiz'. 'buffer' is returned. */ char *ne_addr_error(const ne_sock_addr *addr, char *buffer, size_t bufsiz); /* Returns the canonical name of the host as a NUL-terminated string, * if NE_ADDR_CANON was used, and name resolution was successful. * Otherwise, returns NULL. */ const char *ne_addr_canonical(const ne_sock_addr *addr); /* Destroys an address object created by ne_addr_resolve. */ void ne_addr_destroy(ne_sock_addr *addr); /* Network address type; IPv4 or IPv6 */ typedef enum { ne_iaddr_ipv4 = 0, ne_iaddr_ipv6 } ne_iaddr_type; /* Create a network address object from raw byte representation (in * network byte order) of given type. 'raw' must be four bytes for an * IPv4 address, 16 bytes for an IPv6 address. May return NULL if * address type is not supported. */ ne_inet_addr *ne_iaddr_make(ne_iaddr_type type, const unsigned char *raw); /* Compare two network address objects i1 and i2; returns zero if they * are equivalent or non-zero otherwise. */ int ne_iaddr_cmp(const ne_inet_addr *i1, const ne_inet_addr *i2); /* Return the type of the given network address object. */ ne_iaddr_type ne_iaddr_typeof(const ne_inet_addr *ia); /* Print the string representation of network address 'ia' into the * buffer 'buffer', which is of length 'bufsiz'. Returns 'buffer'. */ char *ne_iaddr_print(const ne_inet_addr *ia, char *buffer, size_t bufsiz); /* Dump the raw byte representation (in network byte order) of address * 'ia' into the buffer 'buffer', which must be of a suitable length * (4 bytes for an IPv4 address, 16 bytes for an IPv6 address). * Returns 'buffer'. */ unsigned char *ne_iaddr_raw(const ne_inet_addr *ia, unsigned char *buffer); /* Perform the reverse name lookup on network address 'ia', placing * the returned name in the 'buf' buffer (of length 'bufsiz') if * successful. Returns zero on success, or non-zero on error. */ int ne_iaddr_reverse(const ne_inet_addr *ia, char *buf, size_t bufsiz); /* Convert network address string 'addr' (for example, "127.0.0.1") * into a network address object. Returns NULL on parse error. If * non-NULL, return value must be freed using ne_iaddr_free. */ ne_inet_addr *ne_iaddr_parse(const char *addr, ne_iaddr_type type); /* Destroy a network address object created using ne_iaddr_make or * ne_iaddr_parse. */ void ne_iaddr_free(ne_inet_addr *addr); /* Create a socket object; returns NULL on error. */ ne_socket *ne_sock_create(void); /* Specify an address to which the local end of the socket will be * bound during a subsequent ne_sock_connect() call. If the address * passed to ne_sock_connect() is of a different type (family) to * 'addr', 'addr' is ignored. Either 'addr' may be NULL, to use the * given port with unspecified address, or 'port' may be 0, to use the * given address with an unspecified port. * * (Note: This function is not equivalent to a BSD socket bind(), it * only takes effect during the _connect() call). */ void ne_sock_prebind(ne_socket *sock, const ne_inet_addr *addr, unsigned int port); /* Connect the socket to server at address 'addr' on port 'port'. * Returns zero on success, NE_SOCK_TIMEOUT if a timeout occurs when a * non-zero connect timeout is configured (and is supported), or * NE_SOCK_ERROR on failure. */ int ne_sock_connect(ne_socket *sock, const ne_inet_addr *addr, unsigned int port); /* Read up to 'count' bytes from socket into 'buffer'. Returns: * NE_SOCK_* on error, * >0 length of data read into buffer (may be less than 'count') */ ssize_t ne_sock_read(ne_socket *sock, char *buffer, size_t count); /* Read up to 'count' bytes into 'buffer', leaving the data available * in the socket buffer to be returned by a subsequent call to * ne_sock_read or ne_sock_peek. Returns: * NE_SOCK_* on error, * >0 length of data read into buffer. */ ssize_t ne_sock_peek(ne_socket *sock, char *buffer, size_t count); /* Block for up to 'n' seconds until data becomes available for reading * from the socket. Returns: * NE_SOCK_* on error, * NE_SOCK_TIMEOUT if no data arrives in 'n' seconds, * 0 if data arrived on the socket. */ int ne_sock_block(ne_socket *sock, int n); /* Write 'count' bytes of 'data' to the socket. Guarantees to either * write all the bytes or to fail. Returns 0 on success, or NE_SOCK_* * on error. */ int ne_sock_fullwrite(ne_socket *sock, const char *data, size_t count); /* I/O vector. */ struct ne_iovec { void *base; size_t len; }; /* Writes 'count' blocks described by 'vector' to the socket. * Guarantees to either write all the bytes or to fail. Count must be * greater than zero and smaller than the system-defined maximum * vector limit. Returns 0 on success, or NE_SOCK_* on error. */ int ne_sock_fullwritev(ne_socket *sock, const struct ne_iovec *vector, int count); /* Read an LF-terminated line into 'buffer', and NUL-terminate it. * At most 'len' bytes are read (including the NUL terminator). * Returns: * NE_SOCK_* on error, * >0 number of bytes read (including NUL terminator) */ ssize_t ne_sock_readline(ne_socket *sock, char *buffer, size_t len); /* Read exactly 'len' bytes into buffer, or fail; returns 0 on * success, NE_SOCK_* on error. */ ssize_t ne_sock_fullread(ne_socket *sock, char *buffer, size_t len); /* Accepts a connection from listening socket 'fd' and places the * socket in 'sock'. Returns zero on success or -1 on failure. */ int ne_sock_accept(ne_socket *sock, int fd); /* Returns the file descriptor used for socket 'sock'. */ int ne_sock_fd(const ne_socket *sock); /* Return address of peer, or NULL on error. The returned address * must be destroyed by caller using ne_iaddr_free. */ ne_inet_addr *ne_sock_peer(ne_socket *sock, unsigned int *port); /* Close the socket and destroy the socket object. If SSL is in use * for the socket, a closure alert is sent to initiate a clean * shutdown, but this function does not wait for the peer's response. * Returns zero on success, or non-zero on failure. */ int ne_sock_close(ne_socket *sock); /* Return current error string for socket. */ const char *ne_sock_error(const ne_socket *sock); /* Set the error string for the socket; takes printf-like format * string. */ void ne_sock_set_error(ne_socket *sock, const char *format, ...) ne_attribute((format (printf, 2, 3))); /* Set read timeout for socket, in seconds; must be a non-zero * positive integer. */ void ne_sock_read_timeout(ne_socket *sock, int timeout); /* Set connect timeout for socket, in seconds; must be a positive * integer. If a timeout of 'zero' is used then then no explicit * timeout handling will be used for ne_sock_connect(), and the * connect call will only timeout as dictated by the TCP stack. */ void ne_sock_connect_timeout(ne_socket *sock, int timeout); /* Negotiate an SSL connection on socket as an SSL server, using given * SSL context. */ int ne_sock_accept_ssl(ne_socket *sock, ne_ssl_context *ctx); /* Negotiate an SSL connection on socket as an SSL client, using given * SSL context. The 'userdata' parameter is associated with the * underlying SSL library's socket structure for use in callbacks. * Returns zero on success, or non-zero on error. */ int ne_sock_connect_ssl(ne_socket *sock, ne_ssl_context *ctx, void *userdata); /* Retrieve the session ID of the current SSL session. If 'buf' is * non-NULL, on success, copies at most *buflen bytes to 'buf' and * sets *buflen to the exact number of bytes copied. If 'buf' is * NULL, on success, sets *buflen to the length of the session ID. * Returns zero on success, non-zero on error. */ int ne_sock_sessid(ne_socket *sock, unsigned char *buf, size_t *buflen); /* Return human-readable name of SSL/TLS cipher used for connection, * or NULL if none. The format of this string is not intended to be * fixed or parseable, but is informational only. Return value is * NUL-terminated malloc-allocated string if not NULL, which must be * freed by the caller. */ char *ne_sock_cipher(ne_socket *sock); /* SOCKS proxy protocol version: */ enum ne_sock_sversion { NE_SOCK_SOCKSV4 = 0, NE_SOCK_SOCKSV4A, NE_SOCK_SOCKSV5 }; /* Given a socket 'sock' which is connected to a SOCKS proxy, initiate * a connection to a destination server using that proxy, specified * either by network address or hostname, at given port 'port'. * * If 'vers' is NE_SOCKS_V4, addr must be an IPv4 address; hostname * and password are ignored; username must be non-NULL. * * If 'vers' is NE_SOCKS_V4A, hostname must be non-NULL; addr is * ignored; password is ignored; username must be non-NULL. * * If 'vers' is NE_SOCKS_V5, addr may be NULL, in which case hostname * must be non-NULL. addr if non-NULL may be an IPv4 or IPv6 address; * username may be NULL, in which case password is ignored. If * username is non-NULL password must also be non-NULL. * * Returns 0 on success, or NE_SOCK_* on failure - in which case, the * socket error string is set. On failure, the socket must be closed * by the caller. */ int ne_sock_proxy(ne_socket *sock, enum ne_sock_sversion vers, const ne_inet_addr *addr, const char *hostname, unsigned int port, const char *username, const char *password); NE_END_DECLS #endif /* NE_SOCKET_H */