Back to index

avfs  1.0.1
nsocket.h
Go to the documentation of this file.
00001 /* 
00002    socket handling interface
00003    Copyright (C) 1999-2001, Joe Orton <joe@light.plus.com>
00004 
00005    This library is free software; you can redistribute it and/or
00006    modify it under the terms of the GNU Library General Public
00007    License as published by the Free Software Foundation; either
00008    version 2 of the License, or (at your option) any later version.
00009    
00010    This library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Library General Public License for more details.
00014 
00015    You should have received a copy of the GNU Library General Public
00016    License along with this library; if not, write to the Free
00017    Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
00018    MA 02111-1307, USA
00019 
00020 */
00021 
00022 #ifndef NSOCKET_H
00023 #define NSOCKET_H
00024 
00025 #ifdef WIN32
00026 #include <WinSock2.h>
00027 #include <stddef.h>
00028 #else
00029 #include <sys/types.h>
00030 #include <sys/socket.h>
00031 #include <netinet/in.h>
00032 #endif
00033 
00034 #include "neon_defs.h"
00035 
00036 BEGIN_NEON_DECLS
00037 
00038 #define SOCK_ERROR -1
00039 /* Read/Write timed out */
00040 #define SOCK_TIMEOUT -2
00041 /* Passed buffer was full */
00042 #define SOCK_FULL -3
00043 /* Socket was closed */
00044 #define SOCK_CLOSED -4
00045 
00046 /* Socket read timeout */
00047 #define SOCKET_READ_TIMEOUT 120
00048 
00049 typedef enum {
00050     sock_namelookup, /* Looking up hostname given by info */
00051     sock_connecting, /* Connecting to server */
00052     sock_connected, /* Connection established */
00053     sock_secure_details /* Secure connection details */
00054 } sock_status;
00055 
00056 struct nsocket_s;
00057 typedef struct nsocket_s nsocket;
00058 
00059 typedef void (*sock_block_reader) (
00060     void *userdata, const char *buf, size_t len);
00061 
00062 typedef void (*sock_progress)(void *userdata, off_t progress, off_t total);
00063 typedef void (*sock_notify)(void *userdata, 
00064                          sock_status status, const char *info);
00065 
00066 void sock_register_progress(sock_progress cb, void *userdata);
00067 void sock_register_notify(sock_notify cb, void *userdata);
00068 
00069 void sock_call_progress(off_t progress, off_t total);
00070 
00071 /* Initialize the socket library. If you don't do this, SSL WILL NOT WORK.
00072  * Returns 0 on success, or non-zero on screwed up SSL library. */
00073 int sock_init(void);
00074 
00075 /* Shutdown the socket library. */
00076 void sock_exit(void);
00077 
00078 /* sock_read is read() with a timeout of SOCKET_TIMEOUT.
00079  * Returns:
00080  *   SOCK_* on error,
00081  *    0 on no data to read (due to EOF),
00082  *   >0 length of data read into buffer.
00083  */
00084 int sock_read(nsocket *sock, char *buffer, size_t count);
00085 
00086 /* sock_peek is recv() with a timeout of SOCKET_TIMEOUT.
00087  * Returns:
00088  *   SOCK_* on error,
00089  *    0 on no data to read (due to EOF),
00090  *   >0 length of data read into buffer.
00091  */
00092 int sock_peek(nsocket *sock, char *buffer, size_t count);
00093 
00094 /* Blocks waiting for data on the given socket for the given time.
00095  * Returns:
00096  *  SOCK_* on error,
00097  *  SOCK_TIMEOUT on no data within timeout,
00098  *  0 if data arrived on the socket.
00099  */
00100 int sock_block(nsocket *sock, int timeout);
00101 
00102 /* Reads readlen bytes from fd and writes to socket.
00103  * (Not all in one go, obviously).
00104  * If readlen == -1, then it reads from srcfd until EOF.
00105  * Returns number of bytes written to destfd, or SOCK_* on error.
00106  */
00107 int sock_transfer(int fd, nsocket *sock, off_t readlen);
00108 
00109 /* Sends the given line to given socket, CRLF appended */
00110 int sock_sendline(nsocket *sock, const char *line); 
00111 /* Sends the given block of data down the nsocket */
00112 int sock_fullwrite(nsocket *sock, const char *data, size_t length); 
00113 /* Sends the null-terminated string down the given nsocket */
00114 int sock_send_string(nsocket *sock, const char *string); 
00115 
00116 /* Reads a line from given nsocket */
00117 int sock_readline(nsocket *sock, char *line, int len); 
00118 /* Reads a chunk of data. */
00119 int sock_fullread(nsocket *sock, char *buffer, int buflen);
00120 
00121 /* Creates and connects a nsocket */
00122 nsocket *sock_connect(const struct in_addr host, 
00123                     unsigned short int portnum);
00124 
00125 /* Weirdo version of the above, which should go away */
00126 nsocket *sock_connect_u(const struct in_addr addr, 
00127                      unsigned short int portnum, 
00128                      int call_fe);
00129 
00130 /* Not as good as accept(2), missing parms 2+3.
00131  * Addings parms 2+3 would probably mean passing socklen_t as an
00132  * int then casting internally, since we don't really want to
00133  * autogenerate the header file to be correct for the build platform.
00134  */
00135 nsocket *sock_accept(int listener);
00136 
00137 /* Returns the file descriptor used for the socket */
00138 int sock_get_fd(nsocket *sock);
00139 
00140 /* Closes the socket and frees the nsocket object. */
00141 int sock_close(nsocket *sock);
00142 
00143 const char *sock_get_error(nsocket *sock);
00144 
00145 /* Do a name lookup on given hostname, writes the address into
00146  * given address buffer. Return -1 on failure. */
00147 int sock_name_lookup(const char *hostname, struct in_addr *addr);
00148 
00149 /* Returns the standard TCP port for the given service */
00150 int sock_service_lookup(const char *name);
00151 
00152 /* Read from socket, passing each block read to reader callback.
00153  * Pass userdata as first argument to reader callback.
00154  *
00155  * If length is -1, keep going till EOF is returned. SOCK_CLOSED
00156  * is never returned in this case.
00157  *
00158  * Otherwise, read exactly 'length' bytes. If EOF is encountered
00159  * before length bytes have been read, and SOCK_CLOSED will be
00160  * returned.
00161  *
00162  * Returns:
00163  *   0 on success,
00164  *   SOCK_* on error (SOCK_CLOSED is a special case, as above)
00165  */
00166 int sock_readfile_blocked(nsocket *sock, off_t length,
00167                        sock_block_reader reader, void *userdata);
00168 
00169 /* Auxiliary for use with SSL. */
00170 struct nssl_context_s;
00171 typedef struct nssl_context_s nssl_context;
00172 
00173 /* Netscape's prompts on getting a certificate which it doesn't
00174  * recognize the CA for:
00175  *   1. Hey, I don't recognize the CA for this cert.
00176  *   2. Here is the certificate: for foo signed by BLAH,
00177  *      using encryption level BLEE
00178  *   3. Allow: accept for this session only, 
00179  *             don't accept
00180  *             accept forever
00181  */
00182 nssl_context *sock_create_ssl_context(void);
00183 
00184 void sock_destroy_ssl_context(nssl_context *ctx);
00185 
00186 /* Callback to decide whether the user will accept the
00187  * given certificate or not */
00188 typedef struct {
00189     char *owner; /* Multi-line string describing owner of
00190                 * certificate */
00191     char *issuer; /* As above for issuer of certificate */
00192     /* Strings the certificate is valid between */
00193     char *valid_from, *valid_till;
00194     /* Certificate fingerprint */
00195     char *fingerprint;
00196 } nssl_certificate;
00197 
00198 /* Returns:
00199  *   0 -> User accepts the certificate
00200  *   non-zero -> user does NOT accept the certificate.
00201  */
00202 typedef int (*nssl_accept)(void *userdata, const nssl_certificate *info);
00203 
00204 void sock_set_cert_accept(nssl_context *c, 
00205                        nssl_accept accepter, void *userdata);
00206 
00207 /* Callback for retrieving the private key password.
00208  * Filename will be the filename of the private key file.
00209  * Must return:
00210  *    0 on success.  buf must be filled in with the password.
00211  *  non-zero if the user cancelled the prompt.
00212  *
00213  * FIXME: this is inconsistent with the HTTP authentication callbacks.  */
00214 typedef int (*nssl_key_prompt)(void *userdata, const char *filename,
00215                             char *buf, int buflen);
00216 
00217 void sock_set_key_prompt(nssl_context *c, 
00218                       nssl_key_prompt prompt, void *userdata);
00219 
00220 /* For PEM-encoded client certificates: use the given client
00221  * certificate and private key file. 
00222  * Returns: 0 if certificate is read okay,
00223  * non-zero otherwise.
00224 
00225  * For decoding the private key file, the callback above will be used
00226  * to prompt for the password.  If no callback has been set, then the
00227  * OpenSSL default will be used: the prompt appears on the terminal.
00228  * */
00229 int sock_set_client_cert(nssl_context *ctx, const char *certfile,
00230                       const char *keyfile);
00231 
00232 void sock_disable_tlsv1(nssl_context *c);
00233 void sock_disable_sslv2(nssl_context *c);
00234 void sock_disable_sslv3(nssl_context *c);
00235 
00236 /* Ctx is OPTIONAL. If it is NULL, defaults are used. */
00237 int sock_make_secure(nsocket *sock, nssl_context *ctx);
00238 
00239 END_NEON_DECLS
00240 
00241 #endif /* NSOCKET_H */