cp_socket
Section: cp_httpclient (3)
Updated: MAY 2006
Index
Return to Main Contents
[view source]
NAME
cp_httpclient - http client api
SYNOPSIS
#include <cprops/httpclient.h>
API INITIALIZATION / FINALIZATION
int cp_httpclient_init();
int cp_httpclient_shutdown();
CLIENT CREATION / CLEANUP
cp_httpclient *cp_httpclient_create(char *host, int port);
cp_httpclient *
cp_httpclient_create_proxy(char *host, int port,
char *proxy_host, int proxy_port);
cp_httpclient *cp_httpclient_create_ssl(char *host, int port,
char *CA_file, char *CA_path,
int verification_mode);
cp_httpclient *
cp_httpclient_create_proxy_ssl(char *host, int port,
char *proxy_host, int proxy_port),
char *CA_file, char *CA_path,
int verification_mode);
void cp_httpclient_destroy(cp_httpclient *client);
int cp_httpclient_reopen(cp_httpclient *client, char *host, int port);
HTTP SETTINGS
void cp_httpclient_set_header(cp_httpclient *client,
char *header, char *value);
void cp_httpclient_set_auto_drop_headers(cp_httpclient *client,
short mode);
void cp_httpclient_drop_headers(cp_httpclient *client);
void *cp_httpclient_set_parameter(cp_httpclient *client,
char *name, char *value);
void cp_httpclient_set_auto_drop_parameters(cp_httpclient *client,
short mode);
void cp_httpclient_drop_parameters(cp_httpclient *client);
void cp_httpclient_set_http_version(cp_httpclient *client,
cp_http_version version);
void cp_httpclient_set_request_type(cp_httpclient *client,
cp_http_request_type type);
void cp_httpclient_set_user_agent(cp_httpclient *client, char *agent);
void cp_httpclient_set_timeout(cp_httpclient *client,
int sec, int usec);
void cp_httpclient_set_retry(cp_httpclient *client, int retry_count);
void cp_httpclient_set_max_redirects(cp_httpclient *client, int max);
void cp_httpclient_set_cookie_jar(cp_httpclient *client, cp_trie *jar);
ISSUING REQUESTS
cp_httpclient_result *
cp_httpclient_fetch(cp_httpclient *client, char *uri);
int cp_httpclient_fetch_nb(cp_httpclient *client, char *uri,
void *id, cp_httpclient_callback callback,
int background);
struct pollfd *cp_httpclient_ctl_default_get_pollfds(int *num);
fd_set *cp_httpclient_ctl_default_get_read_fd_set(int *num);
fd_set *cp_httpclient_ctl_default_get_write_fd_set(int *num);
int cp_httpclient_fetch_nb_exec();
GENERALIZED INTERFACE
cp_httpclient_ctl *cp_httpclient_ctl_create(int background);
void cp_httpclient_ctl_destroy(cp_httpclient_ctl *ctl);
struct pollfd *
cp_httpclient_ctl_get_pollfds(cp_httpclient_ctl *ctl, int *num);
fd_set *
cp_httpclient_ctl_get_read_fd_set(cp_httpclient_ctl *ctl, int *num);
fd_set *
cp_httpclient_ctl_get_write_fd_set(cp_httpclient_ctl *ctl, int *num);
int cp_httpclient_fetch_ctl(cp_httpclient_ctl *ctl,
cp_httpclient *client,
char *uri, void *id,
cp_httpclient_callback callback);
int cp_httpclient_fetch_ctl_exec(cp_httpclient_ctl *ctl);
RESULT HANDLING
void cp_httpclient_result_destroy(cp_httpclient_result *res);
cp_httpclient *
cp_httpclient_result_get_client(cp_httpclient_result *res);
void *cp_httpclient_result_id(cp_httpclient_result *res);
cp_http_result_status
cp_httpclient_result_status(cp_httpclient_result *res);
cp_http_response *
cp_httpclient_result_get_response(cp_httpclient_result *res);
DESCRIPTION
cp_httpclient represents a tcp connection to a specific host on a specific port
and other information required to relay HTTP requests and retrieve server
responses. Requests may be issued using a blocking interface, a non-blocking
interface and a non-blocking background interface, in which case they are
performed by a different thread. Using the non blocking interfaces, requests
are processed by polling on an internal cp_httpclient_ctl object. Requests may
be assigned to dynamically created cp_httpclient_ctl objects so as to separate
execution into different groups.
Here is a description of possible scenarios for performing HTTP calls.
single thread, blocking:
o create a client
o issue a call to cp_httpclient_fetch, specifying a uri. The call is
processed inline and blocks until a response is read or an error
occurs.
o once done processing the result structure, release it by calling
cp_httpclient_result_destroy()
single thread, multiple requests - non-blocking:
o create a client for each distinct host : port pair
o for each client, issue a call to cp_httpclient_fetch_nb,
specifying a uri, an id and a callback, with a value of 0 for the
background parameter. The request is added to an internal control
stack.
o repeatedly call cp_httpclient_fetch_nb_exec() until it returns 0.
o you might want to call poll() to prevent spinning on the call to
cp_httpclient_fetch_nb_exec(). use
cp_httpclient_ctl_default_get_pollfds() to retrieve an array
of struct pollfd objects for the underlying file descriptors and
call poll() with a non-zero timeout.
On systems where poll (2) is unavailable, equivalent select (2) based
functions are available - see cp_httpclient_ctl (3).
o cp_httpclient_fetch_nb_exec will perform the callbacks given when
issuing the requests. Do not call cp_httpclient_result_destroy -
the cp_httpclient_result objects are released by the framework in
this case.
multi-threaded
o create a client for each distinct host : port pair
o for each client, issue a call to cp_httpclient_fetch_nb,
specifying a uri, an id and a callback, with a value of 1 for the
background parameter. The request is added to an internal control
stack and the requests are processed in a separate thread.
Completed requests or errors will trigger the respective callbacks
with cp_httpclient_result objects describing the server response.
The result objects are released by the framework.
grouping transfers
o create an asynchronous interface control block by calling
cp_httpclient_ctl(). The background value determines the control
block behavior as follows:
o with a background value of 0 proceed as detailed under single
thread, but use cp_httpclient_fetch_ctl(),
cp_httpclient_fetch_ctl_exec and cp_httpclient_ctl_get_pollfds()
rather than the functions for the default group transferring.
o with a non-zero background value proceed as detailed under
multi-threaded. For values of 2 or above a thread pool of the given
size will be used to perform transfers. Which could make sense on
machines with more than one cpu when the callback processing time
is comparable to the network time.
In all cases, a call to cp_httpclient_init() to initialize the api must be made
before issuing requests. cp_httpclient_shutdown() must be called to perform
cleanup.
for more detail see the man pages for specific functions.
SEE ALSO
cp_httpclient_create(3),
cp_httpclient_set_header(3),
cp_httpclient_fetch(3),
cp_httpclient_ctl(3),
cp_httpclient_result(3)
Index
- NAME
-
- SYNOPSIS
-
- API INITIALIZATION / FINALIZATION
-
- CLIENT CREATION / CLEANUP
-
- HTTP SETTINGS
-
- ISSUING REQUESTS
-
- GENERALIZED INTERFACE
-
- RESULT HANDLING
-
- DESCRIPTION
-
- single thread, blocking:
-
- single thread, multiple requests - non-blocking:
-
- multi-threaded
-
- grouping transfers
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 23:42:32 GMT, May 09, 2006
|
|