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

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

Go to the documentation of this file.
00001 #ifndef _CP_HTTP_CLIENT_H
00002 #define _CP_HTTP_CLIENT_H
00003 
00004 /**
00005  * @addtogroup cp_socket
00006  */
00007 /** @{ */
00008 /**
00009  * @file
00010  * definitions for http client socket api
00011  */
00012 
00013 #include "common.h"
00014 
00015 #ifdef _WINDOWS
00016 #include <Winsock2.h>
00017 #endif
00018 
00019 __BEGIN_DECLS
00020 
00021 #include <time.h>
00022 
00023 #include "config.h"
00024 #include "hashtable.h"
00025 #include "vector.h"
00026 #include "thread.h"
00027 #include "http.h"
00028 #include "client.h"
00029 
00030 #ifdef HAVE_POLL
00031 #include <sys/poll.h>
00032 #else
00033 #ifdef HAVE_SYS_SELECT_H
00034 #include <sys/select.h>
00035 #endif
00036 #endif /* HAVE_POLL */
00037 
00038 #ifdef CP_USE_COOKIES
00039 #include "trie.h"
00040 
00041 /**
00042  * descriptor for an http cookie
00043  */
00044 typedef CPROPS_DLL struct _cp_http_cookie
00045 {
00046     char *content;      /**< cookie value */
00047     char *domain;       /**< domain cookie is valid for */
00048     char *path;         /**< uri path */
00049     struct tm expires;  /**< expiry date */
00050     int secure;       
00051     int version;
00052     int http_only;
00053     cp_hashtable *fld;  /**< unrecognized fields */
00054 } cp_http_cookie;
00055 
00056 /** 
00057  * create a cookie structure. used internally by cp_cookie_parse.
00058  */
00059 CPROPS_DLL
00060 cp_http_cookie *cp_http_cookie_create(char *content, 
00061                                       char *domain, 
00062                                       char *path, 
00063                                       char *expires, 
00064                                       int secure,
00065                                       int version,
00066                                       int http_only);
00067 
00068 /**
00069  * parse an http cookie
00070  */
00071 CPROPS_DLL
00072 cp_http_cookie *cp_http_cookie_parse(char *src);
00073 
00074 /** release cookie memory */
00075 CPROPS_DLL
00076 void cp_http_cookie_destroy(cp_http_cookie *c);
00077 
00078 /** dump cookie fields to log */
00079 CPROPS_DLL
00080 void cp_http_cookie_dump(cp_http_cookie *c);
00081 
00082 #endif /* CP_USE_COOKIES */
00083 
00084 /** api initialization function */
00085 CPROPS_DLL
00086 int cp_httpclient_init();
00087 
00088 /** api cleanup function */
00089 CPROPS_DLL
00090 int cp_httpclient_shutdown();
00091 
00092 
00093 #define DEFAULT_MAX_REDIRECTS 10
00094 /**
00095  * http client socket wrapper
00096  */
00097 typedef CPROPS_DLL struct _cp_httpclient
00098 {
00099         int id;
00100     cp_http_version version;
00101     cp_http_request_type type;
00102     cp_hashtable *header;
00103     cp_hashtable *cgi_parameters;
00104         short auto_drop_parameters;
00105         short auto_drop_headers;
00106         cp_string *content;
00107         char *host; /**< may differ from requested host if redirect enabled */
00108         int port;   /**< may differ from requested port if redirect enabled */
00109         char *proxy_host;
00110         int proxy_port;
00111 #ifdef CP_USE_SSL
00112         short proxy_ssl;
00113 #endif /* CP_USE_SSL */
00114 #ifdef CP_USE_COOKIES
00115     cp_trie *cookie_jar;
00116 #endif /* CP_USE_COOKIES */
00117     short connected;
00118     short persistent;
00119     int keep_alive;
00120     short pipeline_requests;
00121     short follow_redirects;
00122     short max_redirects;
00123 
00124     cp_client *socket;
00125 } cp_httpclient;
00126 
00127 /** 
00128  * create an http client wrapper to communicate with the given host on the 
00129  * given port
00130  */
00131 CPROPS_DLL
00132 cp_httpclient *cp_httpclient_create(char *host, int port);
00133 /**
00134  * create an http client wrapper to communicate with the given host on the
00135  * given port using the given proxy settings
00136  */
00137 CPROPS_DLL
00138 cp_httpclient *
00139         cp_httpclient_create_proxy(char *host, int port, 
00140                                                            char *proxy_host, int proxy_port);
00141 #ifdef CP_USE_SSL
00142 /**
00143  * create an https client wrapper to communicate with the given host on the
00144  * given port using the specified certificate file or path. Verification mode
00145  * can be either SSL_VERIFY_NONE or SSL_VERIFY_PEER.
00146  */
00147 CPROPS_DLL
00148 cp_httpclient *cp_httpclient_create_ssl(char *host, int port, 
00149                                         char *CA_file, char *CA_path, 
00150                                         int verification_mode);
00151 
00152 /**
00153  * create an https client wrapper to communicate with the given host on the
00154  * given port using the specified proxy settings and the specified certificate 
00155  * file or path. Verification mode can be either SSL_VERIFY_NONE or 
00156  * SSL_VERIFY_PEER.
00157  */
00158 CPROPS_DLL
00159 cp_httpclient *
00160         cp_httpclient_create_proxy_ssl(char *host, int port, 
00161                                                                    char *proxy_host, int proxy_port, 
00162                                                                    char *CA_file, char *CA_path, 
00163                                                                    int verification_mode);
00164 #endif /* CP_USE_SSL */
00165 
00166 /** deallocate a cp_httpclient wrapper. */
00167 CPROPS_DLL
00168 void cp_httpclient_destroy(cp_httpclient *client);
00169 
00170 /** set the HTTP version for subsequent requests */
00171 CPROPS_DLL
00172 void cp_httpclient_set_http_version(cp_httpclient *client, 
00173                                     cp_http_version version);
00174 /** set the request type for subsequent requests. GET by default. */
00175 CPROPS_DLL
00176 void cp_httpclient_set_request_type(cp_httpclient *client, 
00177                                     cp_http_request_type type);
00178 /** set an arbitrary header. Any existing value is overriden. */
00179 CPROPS_DLL
00180 void cp_httpclient_set_header(cp_httpclient *client, char *header, char *value);
00181 /** 
00182  * determine whether headers are automatically deleted or not - disabled
00183  * by default
00184  */
00185 CPROPS_DLL 
00186 void cp_httpclient_set_auto_drop_headers(cp_httpclient *client, short mode);
00187 /** deallocate cgi parameters */
00188 CPROPS_DLL
00189 void cp_httpclient_drop_headers(cp_httpclient *client);
00190 /** set a cgi parameter */
00191 CPROPS_DLL
00192 void *cp_httpclient_set_parameter(cp_httpclient *client, 
00193                                                                   char *name, char *value);
00194 /** 
00195  * determine whether cgi parameters are automatically deleted or not - enabled
00196  * by default
00197  */
00198 CPROPS_DLL 
00199 void cp_httpclient_set_auto_drop_parameters(cp_httpclient *client, short mode);
00200 /** deallocate cgi parameters */
00201 CPROPS_DLL
00202 void cp_httpclient_drop_parameters(cp_httpclient *client);
00203 /** set a value for the 'User-Agent' header. Default is libcprops-(version) */
00204 CPROPS_DLL
00205 void cp_httpclient_set_user_agent(cp_httpclient *client, char *agent);
00206 /** set the timeout value for the underlying tcp socket */
00207 CPROPS_DLL
00208 void cp_httpclient_set_timeout(cp_httpclient *client, 
00209                                       int sec, int usec);
00210 /** set the number of times to retry a connection on failure */
00211 CPROPS_DLL
00212 void cp_httpclient_set_retry(cp_httpclient *client, int retry_count);
00213 /** set client behavior on HTTP 302, 302 etc. responses */
00214 CPROPS_DLL
00215 void cp_httpclient_allow_redirects(cp_httpclient *client, int mode);
00216 /** maximal number of server redirect directives to follow - default is 10 */
00217 CPROPS_DLL
00218 void cp_httpclient_set_max_redirects(cp_httpclient *client, int max);
00219 #ifdef CP_USE_COOKIES
00220 /** 
00221  * by default all cp_httpclients share the same cookie jar. use this function
00222  * to specify a different cookie jar.
00223  */
00224 CPROPS_DLL
00225 void cp_httpclient_set_cookie_jar(cp_httpclient *client, cp_trie *jar);
00226 #endif /* CP_USE_COOKIES */
00227 
00228 /** 
00229  * use the same wrapper for a different address. this will close an existing 
00230  * connection, change the host and port settings on the wrapper and attempt to
00231  * connect. maybe rename this function. 
00232  */
00233 CPROPS_DLL
00234 int cp_httpclient_reopen(cp_httpclient *client, char *host, int port);
00235 
00236 
00237 typedef CPROPS_DLL struct _cp_url_descriptor
00238 {
00239     short ssl;
00240     char *host;
00241     int port;
00242     char *uri;
00243 } cp_url_descriptor; /**< wrapper for url information */
00244 
00245 CPROPS_DLL
00246 cp_url_descriptor *
00247     cp_url_descriptor_create(char *host, short ssl, int port, char *uri);
00248 CPROPS_DLL
00249 void cp_url_descriptor_destroy(cp_url_descriptor *desc);
00250 CPROPS_DLL
00251 short cp_url_descriptor_ssl(cp_url_descriptor *desc);
00252 CPROPS_DLL
00253 char *cp_url_descriptor_host(cp_url_descriptor *desc);
00254 CPROPS_DLL
00255 int cp_url_descriptor_port(cp_url_descriptor *desc);
00256 CPROPS_DLL
00257 char *cp_url_descriptor_uri(cp_url_descriptor *desc);
00258 CPROPS_DLL
00259 cp_url_descriptor *cp_url_descriptor_parse(char *url);
00260 
00261 /** result codes for HTTP requests */
00262 typedef enum 
00263         { 
00264                 CP_HTTP_RESULT_SUCCESS,
00265                 CP_HTTP_RESULT_CONNECTION_FAILED,
00266                 CP_HTTP_RESULT_CONNECTION_RESET,
00267                 CP_HTTP_RESULT_TIMED_OUT,
00268                 CP_HTTP_RESULT_WRITE_ERROR,
00269                 CP_HTTP_RESULT_READ_ERROR
00270         } cp_http_result_status;
00271 
00272 /**
00273  * wrapper for asynchronous interface callback
00274  */
00275 typedef CPROPS_DLL struct _cp_httpclient_result
00276 {
00277         void *id;
00278         cp_http_result_status result;
00279         cp_httpclient *client;
00280         cp_http_response *response;
00281 } cp_httpclient_result;
00282 
00283 /** (internal) create a cp_httpclient_result object */
00284 CPROPS_DLL
00285 cp_httpclient_result * cp_httpclient_result_create(cp_httpclient *client);
00286 
00287 /** destructor for cp_httpclient_result objects */
00288 CPROPS_DLL
00289 void cp_httpclient_result_destroy(cp_httpclient_result *res);
00290 /** get the client assigned id from a result descriptor */
00291 CPROPS_DLL
00292 void *cp_httpclient_result_id(cp_httpclient_result *res);
00293 /** get the result status code from a result descriptor */
00294 CPROPS_DLL 
00295 cp_http_result_status cp_httpclient_result_status(cp_httpclient_result *res);
00296 /** get the response object from a result descriptor */
00297 CPROPS_DLL 
00298 cp_http_response *cp_httpclient_result_get_response(cp_httpclient_result *res);
00299 /** get the client object the response was made on */
00300 CPROPS_DLL 
00301 cp_httpclient *cp_httpclient_result_get_client(cp_httpclient_result *res);
00302 
00303 /** read uri content - synchronous interface */
00304 CPROPS_DLL
00305 cp_httpclient_result *cp_httpclient_fetch(cp_httpclient *client, char *uri);
00306 
00307 
00308 /* ------------------------------------------------------------------------ *
00309  *                             async interface                              *
00310  * ------------------------------------------------------------------------ */
00311 
00312 
00313 /**
00314  * asynchronous interface control block. By default asynchronous transfers use
00315  * a static block shared between all client transfers. To separate transfers 
00316  * into different groups, create a cp_httpclient_ctl control block and use 
00317  * _fetch_ctl_nb and _fetch_ctl_nb_exec().
00318  */
00319 typedef CPROPS_DLL struct _cp_httpclient_ctl
00320 {
00321         cp_hashlist *stack;
00322 #ifdef HAVE_POLL
00323         struct pollfd *ufds; /* pollfd allows specifying poll type (r/w etc) */
00324 #else
00325         fd_set ufds_r; /* select requires separate sets for reading and writing */
00326         fd_set ufds_w;
00327         unsigned int fdmax;
00328 #endif /* HAVE_POLL */
00329         void **desc;
00330         int size;
00331         int nfds;
00332 
00333         /* background transfers */
00334         int running;
00335         cp_thread bg;
00336         cp_thread_pool *pool;
00337         cp_mutex bg_lock;
00338         cp_cond bg_cond;
00339 } cp_httpclient_ctl;
00340 
00341 /**
00342  * create an asynchronous client transfer block for separate transfers. if
00343  * background is 0, transfers must be driven by calling 
00344  * cp_httpclient_fetch_ctl_exec(). If background is 1, transfers will be run 
00345  * on a separate thread. If background is greater than 1, a thread pool is 
00346  * created to perform background transfers and the given value is used as the 
00347  * maximal size of the thread pool. 
00348  */
00349 CPROPS_DLL
00350 cp_httpclient_ctl *cp_httpclient_ctl_create(int background);
00351 
00352 /**
00353  * transfer blocks created with cp_httpclient_ctl_create() are not released by
00354  * the framework and must be finalized by calling cp_httpclient_ctl_destroy().
00355  */
00356 CPROPS_DLL
00357 void cp_httpclient_ctl_destroy(cp_httpclient_ctl *ctl);
00358 
00359 #ifdef HAVE_POLL
00360 /** 
00361  * retrieve a pollfd array prepared for polling for the default transfer
00362  * control block. If num is non-null it is set to the number of entries in the 
00363  * pollfd array.
00364  */
00365 CPROPS_DLL
00366 struct pollfd *cp_httpclient_ctl_default_get_pollfds(int *num);
00367 
00368 /** 
00369  * retrieve a pollfd array prepared for polling. If num is non-null it is set 
00370  * to the number of entries in the pollfd array.
00371  */
00372 CPROPS_DLL
00373 struct pollfd *cp_httpclient_ctl_get_pollfds(cp_httpclient_ctl *ctl, int *num);
00374 #else
00375 /** 
00376  * retrieve a read file descriptor set for select() for the default transfer 
00377  * control block. If num is non-null it is set to the number of entries in the
00378  * file descriptor array.
00379  */
00380 CPROPS_DLL
00381 fd_set *cp_httpclient_ctl_default_get_read_fd_set(int *num);
00382 
00383 /** 
00384  * retrieve a read file descriptor set prepared for select(). If num is non-
00385  * null it is set to the number of entries in the file descriptor array.
00386  */
00387 CPROPS_DLL
00388 fd_set *cp_httpclient_ctl_get_read_fd_set(cp_httpclient_ctl *ctl, int *num);
00389 
00390 /** 
00391  * retrieve a write file descriptor set for select() for the default transfer 
00392  * control block. If num is non-null it is set to the number of entries in the
00393  * file descriptor array.
00394  */
00395 CPROPS_DLL
00396 fd_set *cp_httpclient_ctl_default_get_write_fd_set(int *num);
00397 
00398 /** 
00399  * retrieve a write file descriptor set prepared for select(). If num is non-
00400  * null it is set to the number of entries in the file descriptor array.
00401  */
00402 CPROPS_DLL
00403 fd_set *cp_httpclient_ctl_get_write_fd_set(cp_httpclient_ctl *ctl, int *num);
00404 #endif /* HAVE_POLL */
00405 typedef 
00406 void (*cp_httpclient_callback)(cp_httpclient_result *response);
00407 
00408 /** transfer descriptor for async interface */
00409 typedef CPROPS_DLL struct _cp_http_transfer_descriptor
00410 {
00411         void *id;                               /**< user assigned id */
00412         char *uri;                      /**< target uri */
00413         cp_httpclient *owner;   /**< client */
00414         cp_http_response *res;  /**< result */
00415         cp_string *buf;                 /**< io buffer */
00416         char *read_ptr;                 /**< pointer to processed stage within buf */
00417         int skip;               /**< read pointer offset */
00418         int stage;                      /**< connecting, writing, reading */
00419         int read_stage;                 /**< read status line, header, body */
00420         int transfer;                   /**< chunked, content-length, EOF */
00421         int remaining;                  /**< io bytes yet to be transfered */
00422         int redirects;                  /**< number of redirects */
00423         int status;                     /**< transfer result */
00424         cp_httpclient_callback callback;
00425 } cp_http_transfer_descriptor;
00426 
00427 CPROPS_DLL
00428 cp_http_transfer_descriptor *
00429         cp_http_transfer_descriptor_create(void *id, 
00430                                                                            cp_httpclient *client, 
00431                                                                            cp_httpclient_callback callback, 
00432                                                                            char *uri);
00433 CPROPS_DLL
00434 void cp_http_transfer_descriptor_destroy(cp_http_transfer_descriptor *desc);
00435 
00436 /** 
00437  * perform an asynchronous fetch. If background is non-zero, the fetch happens
00438  * in a separate thread and the callback is invoked asynchronously. Otherwise
00439  * the caller must make repeated calls to cp_httpclient_fetch_nb_exec() until
00440  * all transfers complete. cp_httpclient_fetch_nb_next() returns the number of
00441  * active transfers. cp_httpclient_fetch_nb returns zero if the request could
00442  * be registered, non-zero otherwise.
00443  */
00444 CPROPS_DLL 
00445 int cp_httpclient_fetch_nb(cp_httpclient *client, char *uri, void *id, 
00446                                                    cp_httpclient_callback callback, int background);
00447 
00448 /**
00449  * same as cp_httpclient_fetch_nb but allows specifying a different 
00450  * asynchronous transfer control block.
00451  */
00452 CPROPS_DLL
00453 int cp_httpclient_fetch_ctl(cp_httpclient_ctl *ctl, cp_httpclient *client, 
00454                                                         char *uri, void *id, 
00455                                                         cp_httpclient_callback callback);
00456 
00457 /**
00458  * non-blocking fetches executing in the foreground must be driven by calls to
00459  * cp_httpclient_fetch_nb_exec(). The callback for each request is made once it
00460  * completes or if an error occurs. cp_httplcient_fetch_nb_exec() returns the
00461  * number of active requests. Zero indicates all transfers have completed. 
00462  */
00463 CPROPS_DLL
00464 int cp_httpclient_fetch_nb_exec();
00465 
00466 /**
00467  * same as cp_httpclient_fetch_nb_exec() but allows specifying a different
00468  * aysnchronous transfer control block.
00469  */
00470 CPROPS_DLL
00471 int cp_httpclient_fetch_ctl_exec(cp_httpclient_ctl *ctl);
00472 
00473 __END_DECLS
00474 
00475 /** @} */
00476 
00477 #endif /* _CP_HTTP_CLIENT_H */

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