## section-www

section-www

## Functions

raptor_www * | raptor_new_www ()
raptor_www * | raptor_new_www_with_connection ()
void | raptor_free_www ()
void | (*raptor_www_write_bytes_handler) ()
void | (*raptor_www_content_type_handler) ()
int | raptor_www_set_user_agent2 ()
void | raptor_www_set_user_agent ()
int | raptor_www_set_proxy2 ()
void | raptor_www_set_proxy ()
int | raptor_www_set_http_accept2 ()
void | raptor_www_set_http_accept ()
int | raptor_www_set_http_cache_control ()
void | raptor_www_set_write_bytes_handler ()
void | raptor_www_set_connection_timeout ()
void | raptor_www_set_content_type_handler ()
int | (*raptor_uri_filter_func) ()
void | raptor_www_set_uri_filter ()
void | (*raptor_www_final_uri_handler) ()
raptor_uri * | raptor_www_get_final_uri ()
void | raptor_www_set_final_uri_handler ()
int | raptor_www_fetch ()
int | raptor_www_fetch_to_string ()
void * | raptor_www_get_connection ()
int | raptor_www_set_ssl_cert_options ()
int | raptor_www_set_ssl_verify_options ()
void | raptor_www_abort ()

## Types and Values

typedef | raptor_www

## Description

## Functions

### raptor_new_www ()

    raptor_www *
    raptor_new_www (raptor_world *world);

Constructor - create a new raptor_www object.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

www | WWW object |
userdata | user data |
content_type | content type seen |

### raptor_www_set_user_agent2 ()

    int
    raptor_www_set_user_agent2 (raptor_www *www,
                                const char *user_agent,
                                size_t user_agent_len);

Set the user agent value, for HTTP requests typically.

#### Parameters

www | WWW object |
user_agent | User-Agent string |
user_agent_len | Length of `user_agent` string or 0 to count it here. |

#### Returns

non-0 on failure

### raptor_www_set_user_agent ()

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

`raptor_www_set_user_agent` is deprecated and should not be used in newly-written code.

Set the user agent value, for HTTP requests typically.

`Deprecated` : use `raptor_www_set_user_agent2()` which takes a length parameter and returns a value to singify failure.

#### Parameters

www | WWW object |
user_agent | User-Agent string |

### raptor_www_set_proxy2 ()

    int
    raptor_www_set_proxy2 (raptor_www *www,
                           const char *proxy,
                           size_t proxy_len);

Set the proxy for the WWW object.

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

#### Parameters

www | WWW object |
proxy | proxy string. |
proxy_len | Length of `proxy` string or 0 to count it here. |

#### Returns

non-0 on failure

### raptor_www_set_proxy ()

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

`raptor_www_set_proxy` is deprecated and should not be used in newly-written code.

Set the proxy for the WWW object.

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

`Deprecated` : use `raptor_www_set_proxy2()` which takes an length parameter and returns a value to singify failure.

#### Parameters

www | WWW object |
proxy | proxy string. |

### raptor_www_set_http_accept2 ()

    int
    raptor_www_set_http_accept2 (raptor_www *www,
                                 const char *value,
                                 size_t value_len);

Set HTTP Accept header.

#### Parameters

www | raptor_www class |
value | Accept: header value or NULL to have an empty one. |
value_len | Length of `value` string or 0 to count it here. |

#### Returns

non-0 on failure

### raptor_www_set_http_accept ()

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

`raptor_www_set_http_accept` is deprecated and should not be used in newly-written code.

Set HTTP Accept header.

`Deprecated` : use `raptor_www_set_http_accept2()` which takes an length parameter and returns a value to singify failure.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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.

#### Parameters

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)

#### Parameters

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.

#### Parameters

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.

#### Parameters

www | WWW object |
reason | abort reason message |

## Types and Values

### raptor_www

    raptor_www* raptor_www;

Raptor WWW class