• Main Page
  • Related Pages
  • Modules
  • Data Structures
  • Files
  • File List
  • Globals

sst/elements/genericProc/programs/libcprops/client.h

Go to the documentation of this file.
00001 #ifndef _CP_TCP_CLIENT_H
00002 #define _CP_TCP_CLIENT_H
00003 
00004 /**
00005  * @addtogroup cp_socket
00006  */
00007 /** @{ */
00008 /**
00009  * @file
00010  * definitions for client socket abstraction api
00011  */
00012 
00013 #ifdef _WINDOWS
00014 #include <winsock2.h>
00015 #endif
00016 
00017 #include "common.h"
00018 
00019 __BEGIN_DECLS
00020 
00021 #include "config.h"
00022 
00023 #include "hashlist.h"
00024 #include "vector.h"
00025 #include "thread.h"
00026 
00027 /* this provides get_client_ssl_ctx */
00028 #include "socket.h"
00029 
00030 #if defined(unix) || defined(__unix__) || defined(__MACH__)
00031 #include <sys/time.h>
00032 #include <netinet/in.h>
00033 #endif
00034 
00035 #ifdef CP_USE_SSL
00036 #include <openssl/ssl.h>
00037 #endif
00038 
00039 #if defined(sun) || defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__APPLE__)
00040 #include <sys/types.h>
00041 #include <sys/socket.h>
00042 #endif
00043 
00044 #ifdef _WINDOWS
00045 #include "Windows.h"
00046 #include "Winsock.h"
00047 #endif
00048 
00049 /** seconds to wait for responses */
00050 #define DEFAULT_CLIENT_TIMEOUT 300
00051 
00052 /** default connect retries */
00053 #define DEFAULT_RETRIES 3
00054 
00055 /** recommended to call before using tcp client socket functions */
00056 CPROPS_DLL
00057 void cp_client_init();
00058 /** 
00059  * call from signal handler to stop sockets in waiting select() and close all 
00060  * connections
00061  */
00062 CPROPS_DLL
00063 void cp_client_stop_all();
00064 /** performs cleanup */
00065 CPROPS_DLL
00066 void cp_client_shutdown();
00067 
00068 #ifdef CP_USE_SSL
00069 CPROPS_DLL
00070 void cp_client_ssl_init();
00071 CPROPS_DLL
00072 void cp_client_ssl_shutdown();
00073 
00074 CPROPS_DLL
00075 char *ssl_verification_error_str(int code);
00076 #endif /* CP_USE_SSL */
00077 
00078 CPROPS_DLL
00079 void cp_client_init();
00080 
00081 CPROPS_DLL
00082 void cp_client_shutdown();
00083 
00084 /**
00085  * add callback to be made on tcp layer shutdown
00086  */
00087 CPROPS_DLL
00088 void cp_tcp_add_shutdown_callback(void (*cb)(void *), void *prm);
00089 
00090 
00091 CPROPS_DLL
00092 struct _cp_client; /* fwd declaration */
00093 
00094 /**
00095  * cp_client is a 'client socket'. create a cp_client with address information,
00096  * call cp_client_connect() and communicate on the resulting file descriptor. 
00097  */
00098 typedef CPROPS_DLL struct _cp_client
00099 {
00100         int id;                                           /**< socket id                         */
00101         struct sockaddr_in *addr;     /**< address                           */
00102         struct hostent *hostspec;     /**< aliases                           */
00103         char *host;                   /**< host literal                      */
00104         char *found_host;             /**< actual hostname                   */
00105         int port;                     /**< the port this socket listens on   */
00106         struct timeval timeout;       /**< max blocking time                 */
00107         struct timeval created;           /**< creation time                     */
00108         unsigned long bytes_read;     /**< bytes read                        */
00109         unsigned long bytes_sent;     /**< bytes written                     */
00110 #if defined(unix) || defined(__unix__) || defined(__MACH__)
00111         int fd;                       /**< listener                          */
00112 #else 
00113 #ifdef _WINDOWS
00114         SOCKET fd;
00115 #endif /* _WINDOWS */
00116 #endif /* unix */
00117         int closing;                              /**< shutdown flag                     */
00118         int retry;
00119         void *owner;
00120 #ifdef CP_USE_SSL
00121         int use_ssl;                              /**< ssl connection                    */
00122         SSL_CTX *ctx;                             /**< ssl context                       */
00123         SSL *ssl;                                         /**< ssl object                        */
00124         X509 *server_certificate;     /**< server certificate if provided    */
00125 #endif /* CP_USE_SSL */
00126 } cp_client;
00127 
00128 /** create a client socket */
00129 CPROPS_DLL
00130 cp_client *cp_client_create(char *host, int port);
00131 /** create a client socket with a struct sockaddr * */
00132 CPROPS_DLL
00133 cp_client *cp_client_create_addr(struct sockaddr_in *);
00134 #ifdef CP_USE_SSL
00135 /** create an ssl client socket */
00136 CPROPS_DLL
00137 cp_client *cp_client_create_ssl(char *host, int port, 
00138                                         char *CA_file, char *CA_path, 
00139                                                                 int verification_mode);
00140 /** create an ssl client socket with a struct sockaddr * */
00141 CPROPS_DLL
00142 cp_client *cp_client_create_ssl_addr(struct sockaddr *,
00143                                              char *CA_file, char *CA_path);
00144 #endif /* CP_USE_SSL */
00145 /** set the timeout - (0, 0) for no timeout */
00146 CPROPS_DLL
00147 void cp_client_set_timeout(cp_client *client, int sec, int usec);
00148 /** number of connection retries */
00149 CPROPS_DLL
00150 void cp_client_set_retry(cp_client *client, int retry_count);
00151 /** useful free pointer for client code */
00152 CPROPS_DLL
00153 void cp_client_set_owner(cp_client *client, void *owner);
00154 /** 
00155  * opens a connection. may return: 
00156  * <li> 0 on success
00157  * <li> -1 on failure
00158  * <li> > 0 on SSL verification errors. a connection has been established but 
00159  * couldn't be properly verified. Client code should decide whether to proceed 
00160  * or not. The <code>server_certificate</code> field on the <code>client</code>
00161  * will have been set to the server certificate if one has been presented. 
00162  * <br>
00163  * return codes correspond to SSL_get_verify_result codes with the addition
00164  * of X509_V_ERR_APPLICATION_VERIFICATION possibly indicating that no server
00165  * certificate was presented. In this case the <code>server_certificate</code>
00166  * field will be <code>NULL</code>.
00167  */
00168 CPROPS_DLL
00169 int cp_client_connect(cp_client *client);
00170 
00171 #ifdef CP_USE_SSL
00172 /** (internal) perform ssl handshake on a new connection */
00173 CPROPS_DLL
00174 int cp_client_connect_ssl(cp_client *client);
00175 #endif /* CP_USE_SSL */
00176 /** 
00177  * use the same wrapper for a different address. this will close an existing 
00178  * connection, change the host and port settings on the wrapper and attempt to
00179  * connect. maybe rename this function. 
00180  */
00181 CPROPS_DLL
00182 int cp_client_reopen(cp_client *client, char *host, int port);
00183 
00184 #ifdef CP_USE_SSL
00185 /** return the server certificate */
00186 CPROPS_DLL
00187 X509 *cp_client_get_server_certificate(cp_client *client);
00188 /** check whether the host name given in the server certificate matches the name used for the connection */
00189 CPROPS_DLL
00190 int cp_client_verify_hostname(cp_client *client);
00191 #endif /* CP_USE_SSL */
00192 
00193 /** close a client connection */
00194 CPROPS_DLL
00195 int cp_client_close(cp_client *client);
00196 /** deallocate a cp_client */
00197 CPROPS_DLL
00198 void cp_client_destroy(cp_client *client);
00199 
00200 CPROPS_DLL
00201 int cp_client_read(cp_client *client, char *buf, int len);
00202 CPROPS_DLL
00203 int cp_client_read_string(cp_client *client, cp_string *str, int len);
00204 CPROPS_DLL
00205 int cp_client_write(cp_client *client, char *buf, int len);
00206 CPROPS_DLL
00207 int cp_client_write_string(cp_client *client, cp_string *str);
00208 
00209 __END_DECLS
00210 
00211 /** @} */
00212 
00213 #endif /* _CP_TCP_CLIENT_H */

Generated on Fri Oct 22 2010 11:02:22 for SST by  doxygen 1.7.1