cp_httpclient(3) - Linux man page

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)