cp_socket

Section: cp_httpclient (3)
Updated: MAY 2006
Index Return to Main Contents

NAME

cp_httpclient_fetch, cp_httpclient_fetch_nb, cp_httpclient_fetch_ctl, cp_httpclient_fetch_nb_exec, cp_httpclient_fetch_ctl_exec - perfrom an http call

SYNOPSIS

#include <sys/poll.h>
#include <cprops/httpclient.h>

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);
int cp_httpclient_fetch_nb_exec();
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);

DESCRIPTION

the fetch functions operate on a successfully initialized the cp_httpclient object client and attempt to retrieve the content under the given uri value.

synchronous interface - cp_httpclient_fetch

cp_httpclient_fetch performs an HTTP call and returns a cp_httpclient_result(3) object containing a status code and the results, if any, represented as a cp_http_response(3) object. This method will block until fully reading the server response or an error occurs.

asynchronous interface - cp_httpclient_fetch_nb

cp_httpclient_fetch_nb adds the HTTP request to an execution stack and returns immediately. Results are obtained when a callback is made to the specified callback function, which must follow this prototype:

  void (*callback)(cp_httpclient_result *response);

The callback function is invoked once results have been read from the server or an error occurs.

If the background parameter is non-zero, requests will be performed by a background thread. Otherwise transfers must be driven by calling cp_httpclient_fetch_nb_exec which returns the number of on-going transfers. A return value of zero indicates all transfers have completed. If the return value is non-zero cp_httpclient_fetch_nb_exec must be called again. To prevent spinning, or more generally to determine whether there is data to send or receive on any of the connections, applications should retrieve an array of struct pollfd structures by calling cp_httpclient_ctl_default_get_pollfds and use this array to call poll(2) with a non-zero timeout value. Pass a non-null pointer to an int value to cp_httpclient_ctl_default_get_pollfds for the num parameter to be set to the size of the struct pollfd array.

grouping transfers

To execute requests by group or to control the number of threads involved in performing background transfers, applications may dynamically create a transfer control stack cp_httpclient_ctl(3). Adding requests is then done with cp_httpclient_fetch_ctl. If the control stack is not initialized to perform transfers in a separate thread (or threads), applications must control execution with cp_httpclient_fetch_ctl_exec and polling on the struct pollfd array given by cp_httpclient_ctl_get_pollfds as required.

RETURN VALUE

cp_httpclient_fetch returns NULL on internal memory allocation failures, a cp_httpclient_result object representing the transfer result otherwise.
cp_httpclient_fetch_nb and cp_httpclient_fetch_ctl return zero on success or non-zero if the request could not be registered.
cp_httpclient_fetch_nb_exec and cp_httpclient_fetch_ctl_exec return -1 on memory allocation failure, or the number of executing requests on the default or user created transfer stack respectively. A value of zero indicates that all transfers have completed (or none were requested yet).

Index

NAME

SYNOPSIS

DESCRIPTION

synchronous interface - cp_httpclient_fetch
asynchronous interface - cp_httpclient_fetch_nb
grouping transfers

RETURN VALUE

SEE ALSO

This document was created by man2html, using the manual pages.
Time: 23:42:32 GMT, May 09, 2006