WWW

WWW — Retrieval of URI content from the web.

Synopsis

typedef             raptor_www;
raptor_www *        raptor_new_www                      (raptor_world *world);
raptor_www *        raptor_new_www_with_connection      (raptor_world *world,
                                                         void *connection);
void                raptor_free_www                     (raptor_www *www);
void                (*raptor_www_write_bytes_handler)   (raptor_www *www,
                                                         void *userdata,
                                                         const void *ptr,
                                                         size_t size,
                                                         size_t nmemb);
void                (*raptor_www_content_type_handler)  (raptor_www *www,
                                                         void *userdata,
                                                         const char *content_type);
void                raptor_www_set_user_agent           (raptor_www *www,
                                                         const char *user_agent);
void                raptor_www_set_proxy                (raptor_www *www,
                                                         const char *proxy);
void                raptor_www_set_http_accept          (raptor_www *www,
                                                         const char *value);
int                 raptor_www_set_http_cache_control   (raptor_www *www,
                                                         const char *cache_control);
void                raptor_www_set_write_bytes_handler  (raptor_www *www,
                                                         raptor_www_write_bytes_handler handler,
                                                         void *user_data);
void                raptor_www_set_connection_timeout   (raptor_www *www,
                                                         int timeout);
void                raptor_www_set_content_type_handler (raptor_www *www,
                                                         raptor_www_content_type_handler handler,
                                                         void *user_data);
int                 (*raptor_uri_filter_func)           (void *user_data,
                                                         raptor_uri *uri);
void                raptor_www_set_uri_filter           (raptor_www *www,
                                                         raptor_uri_filter_func filter,
                                                         void *user_data);
void                (*raptor_www_final_uri_handler)     (raptor_www *www,
                                                         void *userdata,
                                                         raptor_uri *final_uri);
raptor_uri *        raptor_www_get_final_uri            (raptor_www *www);
void                raptor_www_set_final_uri_handler    (raptor_www *www,
                                                         raptor_www_final_uri_handler handler,
                                                         void *user_data);
int                 raptor_www_fetch                    (raptor_www *www,
                                                         raptor_uri *uri);
int                 raptor_www_fetch_to_string          (raptor_www *www,
                                                         raptor_uri *uri,
                                                         void **string_p,
                                                         size_t *length_p,
                                                         raptor_data_malloc_handler const malloc_handler);
void *              raptor_www_get_connection           (raptor_www *www);
int                 raptor_www_set_ssl_cert_options     (raptor_www *www,
                                                         const char *cert_filename,
                                                         const char *cert_type,
                                                         const char *cert_passphrase);
int                 raptor_www_set_ssl_verify_options   (raptor_www *www,
                                                         int verify_peer,
                                                         int verify_host);
void                raptor_www_abort                    (raptor_www *www,
                                                         const char *reason);

Description

Provides a wrapper to the resolution of URIs to give content using an underlying WWW-retrieval library. The content is delivered by callbacks and includes returning content type for handling content-negotation by the caller as well as chunks of byte content.

Details

raptor_www

raptor_www* raptor_www;

Raptor WWW class


raptor_new_www ()

raptor_www *        raptor_new_www                      (raptor_world *world);

Constructor - create a new raptor_www object.

world :

raptor_world object

Returns :

a new raptor_www or NULL on failure.

raptor_new_www_with_connection ()

raptor_www *        raptor_new_www_with_connection      (raptor_world *world,
                                                         void *connection);

Constructor - create a new raptor_www object over an existing WWW connection.

At present this only works with a libcurl CURL handle object when raptor is compiled with libcurl suppport. Otherwise the connection is ignored. This allows such things as setting up special flags on the curl handle before passing into the constructor.

world :

raptor_world object

connection :

external WWW connection object.

Returns :

a new raptor_www object or NULL on failure.

raptor_free_www ()

void                raptor_free_www                     (raptor_www *www);

Destructor - destroy a raptor_www object.

www :

WWW object.

raptor_www_write_bytes_handler ()

void                (*raptor_www_write_bytes_handler)   (raptor_www *www,
                                                         void *userdata,
                                                         const void *ptr,
                                                         size_t size,
                                                         size_t nmemb);

Receiving bytes of data from WWW retrieval handler.

Set by raptor_www_set_write_bytes_handler().

www :

WWW object

userdata :

user data

ptr :

data pointer

size :

size of individual item

nmemb :

number of items

raptor_www_content_type_handler ()

void                (*raptor_www_content_type_handler)  (raptor_www *www,
                                                         void *userdata,
                                                         const char *content_type);

Receiving Content-Type: header from WWW retrieval handler.

Set by raptor_www_set_content_type_handler().

www :

WWW object

userdata :

user data

content_type :

content type seen

raptor_www_set_user_agent ()

void                raptor_www_set_user_agent           (raptor_www *www,
                                                         const char *user_agent);

Set the user agent value, for HTTP requests typically.

www :

WWW object

user_agent :

User-Agent string

raptor_www_set_proxy ()

void                raptor_www_set_proxy                (raptor_www *www,
                                                         const char *proxy);

Set the proxy for the WWW object.

The proxy usually a string of the form http://server.domain:port.

www :

WWW object

proxy :

proxy string.

raptor_www_set_http_accept ()

void                raptor_www_set_http_accept          (raptor_www *www,
                                                         const char *value);

Set HTTP Accept header.

www :

raptor_www class

value :

Accept: header value or NULL to have an empty one.

raptor_www_set_http_cache_control ()

int                 raptor_www_set_http_cache_control   (raptor_www *www,
                                                         const char *cache_control);

Set HTTP Cache-Control:header (default none)

The cache_control value can be a string to set it, "" to send a blank header or NULL to not set the header at all.

www :

WWW object

cache_control :

Cache-Control header value (or NULL to disable)

Returns :

non-0 on failure

raptor_www_set_write_bytes_handler ()

void                raptor_www_set_write_bytes_handler  (raptor_www *www,
                                                         raptor_www_write_bytes_handler handler,
                                                         void *user_data);

Set the handler to receive bytes written by the raptor_www implementation.

www :

WWW object

handler :

bytes handler function

user_data :

bytes handler data

raptor_www_set_connection_timeout ()

void                raptor_www_set_connection_timeout   (raptor_www *www,
                                                         int timeout);

Set WWW connection timeout

www :

WWW object

timeout :

Timeout in seconds

raptor_www_set_content_type_handler ()

void                raptor_www_set_content_type_handler (raptor_www *www,
                                                         raptor_www_content_type_handler handler,
                                                         void *user_data);

Set the handler to receive the HTTP Content-Type header value.

This is called if or when the value is discovered during retrieval by the raptor_www implementation. Not all implementations provide access to this.

www :

WWW object

handler :

content type handler function

user_data :

content type handler data

raptor_uri_filter_func ()

int                 (*raptor_uri_filter_func)           (void *user_data,
                                                         raptor_uri *uri);

Callback function for raptor_www_set_uri_filter

user_data :

user data

uri :

raptor_uri URI to check

Returns :

non-0 to filter the URI

raptor_www_set_uri_filter ()

void                raptor_www_set_uri_filter           (raptor_www *www,
                                                         raptor_uri_filter_func filter,
                                                         void *user_data);

Set URI filter function for WWW retrieval.

www :

WWW object

filter :

URI filter function

user_data :

User data to pass to filter function

raptor_www_final_uri_handler ()

void                (*raptor_www_final_uri_handler)     (raptor_www *www,
                                                         void *userdata,
                                                         raptor_uri *final_uri);

Receiving the final resolved URI from a WWW retrieval

Set by raptor_www_set_final_uri_handler().

www :

WWW object

userdata :

user data

final_uri :

final URI seen

raptor_www_get_final_uri ()

raptor_uri *        raptor_www_get_final_uri            (raptor_www *www);

Get the WWW final resolved URI.

This returns the URI used after any protocol redirection.

www :

raptor_www object

Returns :

a new URI or NULL if not known.

raptor_www_set_final_uri_handler ()

void                raptor_www_set_final_uri_handler    (raptor_www *www,
                                                         raptor_www_final_uri_handler handler,
                                                         void *user_data);

Set the handler to receive the HTTP Content-Type header value.

This is called if or when the value is discovered during retrieval by the raptor_www implementation. Not all implementations provide access to this.

www :

WWW object

handler :

content type handler function

user_data :

content type handler data

raptor_www_fetch ()

int                 raptor_www_fetch                    (raptor_www *www,
                                                         raptor_uri *uri);

Start a WWW content retrieval for the given URI, returning data via the write_bytes handler.

www :

WWW object

uri :

URI to read from

Returns :

non-0 on failure.

raptor_www_fetch_to_string ()

int                 raptor_www_fetch_to_string          (raptor_www *www,
                                                         raptor_uri *uri,
                                                         void **string_p,
                                                         size_t *length_p,
                                                         raptor_data_malloc_handler const malloc_handler);

Start a WWW content retrieval for the given URI, returning the data in a new string.

If malloc_handler is null, raptor will allocate it using it's own memory allocator. *string_p is set to NULL on failure (and *length_p to 0 if length_p is not NULL).

www :

raptor_www object

uri :

raptor_uri to retrieve

string_p :

pointer to location to hold string

length_p :

pointer to location to hold length of string (or NULL)

malloc_handler :

pointer to malloc() to use to make string (or NULL)

Returns :

non-0 on failure

raptor_www_get_connection ()

void *              raptor_www_get_connection           (raptor_www *www);

Get WWW library connection object.

Return the internal WWW connection handle. For libcurl, this returns the CURL handle and for libxml the context. Otherwise it returns NULL.

www :

raptor_www object

Returns :

connection pointer

raptor_www_set_ssl_cert_options ()

int                 raptor_www_set_ssl_cert_options     (raptor_www *www,
                                                         const char *cert_filename,
                                                         const char *cert_type,
                                                         const char *cert_passphrase);

Set SSL client certificate options (where supported)

www :

WWW object

cert_filename :

SSL client certificate file

cert_type :

SSL client certificate type (default is "PEM")

cert_passphrase :

SSL client certificate password

Returns :

non-0 when setting options is not supported

raptor_www_set_ssl_verify_options ()

int                 raptor_www_set_ssl_verify_options   (raptor_www *www,
                                                         int verify_peer,
                                                         int verify_host);

Set whether SSL verifies the authenticity of the peer's certificate

These options correspond to setting the curl CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options.

www :

WWW object

verify_peer :

SSL verify peer - non-0 to verify peer SSL certificate (default)

verify_host :

SSL verify host - 0 none, non-0 to require a CN match (default).

Returns :

non-0 on failure

raptor_www_abort ()

void                raptor_www_abort                    (raptor_www *www,
                                                         const char *reason);

Abort an ongoing raptor WWW operation and pass back a reason.

This is typically used within one of the raptor WWW handlers when retrieval need no longer continue due to another processing issue or error.

www :

WWW object

reason :

abort reason message


Navigation: Redland Home Page

Copyright 2000-2014 Dave Beckett