## Core

Core — Core library functions

## Synopsis

    typedef             flickcurl;
    extern const char* const flickcurl_version_string;
    extern const char* const flickcurl_license_string;
    extern const char* const flickcurl_copyright_string;
    extern const char* const flickcurl_short_copyright_string;
    extern const char* const flickcurl_home_url_string;
    extern const char* const flickcurl_flickr_replace_service_uri;
    extern const char* const flickcurl_flickr_service_uri;
    extern const char* const flickcurl_flickr_upload_service_uri;
    void                (*flickcurl_message_handler)        (void *user_data,
                                                             const char *message);
    int                 flickcurl_init                      (void);
    void                flickcurl_finish                    (void);
    flickcurl *         flickcurl_new                       (void);
    flickcurl *         flickcurl_new_with_handle           (void *curl_handle);
    void                flickcurl_free                      (flickcurl *fc);
    int                 flickcurl_get_current_request_wait  (flickcurl *fc);
    int                 flickcurl_get_extras_format_info    (int extras_format,
                                                             const char **name_p,
                                                             const char **label_p);
    int                 flickcurl_get_feed_format_info      (int feed_format,
                                                             const char **name_p,
                                                             const char **label_p,
                                                             const char **mime_type_p);
    void                (*flickcurl_curl_setopt_handler)    (void *user_data,
                                                             void *curl_handle);
    void                flickcurl_set_curl_setopt_handler   (flickcurl *fc,
                                                             flickcurl_curl_setopt_handler curl_handler,
                                                             void *curl_handler_data);
    void                flickcurl_set_data                  (flickcurl *fc,
                                                             void *data,
                                                             size_t data_length);
    void                flickcurl_set_error_handler         (flickcurl *fc,
                                                             flickcurl_message_handler error_handler,
                                                             void *error_data);
    void                flickcurl_set_http_accept           (flickcurl *fc,
                                                             const char *value);
    void                flickcurl_set_proxy                 (flickcurl *fc,
                                                             const char *proxy);
    void                flickcurl_set_request_delay         (flickcurl *fc,
                                                             long delay_msec Param2);
    void                flickcurl_set_service_uri           (flickcurl *fc,
                                                             const char *uri);
    void                flickcurl_set_replace_service_uri   (flickcurl *fc,
                                                             const char *uri);
    void                flickcurl_set_upload_service_uri    (flickcurl *fc,
                                                             const char *uri);
    void                flickcurl_set_sign                  (flickcurl *fc);
    void                flickcurl_set_tag_handler           (flickcurl *fc,
                                                             flickcurl_tag_handler tag_handler,
                                                             void *tag_data);
    void                flickcurl_set_user_agent            (flickcurl *fc,
                                                             const char *user_agent);
    void                flickcurl_set_write                 (flickcurl *fc,
                                                             int is_write);
    void                flickcurl_set_xml_data              (flickcurl *fc,
                                                             xmlDocPtr doc);

## Description

Core library functions

## Details

### flickcurl

    typedef struct flickcurl_s flickcurl;

Flickcurl session object created by `flickcurl_new()` and destroyed by `flickcurl_free()`

### flickcurl_version_string

    extern const char* const flickcurl_version_string;

### flickcurl_license_string

    extern const char* const flickcurl_license_string;

### flickcurl_copyright_string

    extern const char* const flickcurl_copyright_string;

### flickcurl_short_copyright_string

    extern const char* const flickcurl_short_copyright_string;

### flickcurl_home_url_string

    extern const char* const flickcurl_home_url_string;

### flickcurl_flickr_replace_service_uri

    extern const char* const flickcurl_flickr_replace_service_uri;

### flickcurl_flickr_service_uri

    extern const char* const flickcurl_flickr_service_uri;

### flickcurl_flickr_upload_service_uri

    extern const char* const flickcurl_flickr_upload_service_uri;

### flickcurl_message_handler ()

    void                (*flickcurl_message_handler)        (void *user_data,
                                                             const char *message);

Flickcurl Message handler callback.

`user_data` : | user data pointer
`message` : | error message

### flickcurl_init ()

    int                 flickcurl_init                      (void);

Initialise Flickcurl library.

Returns : | non-0 on failure

### flickcurl_finish ()

    void                flickcurl_finish                    (void);

Terminate Flickcurl library.

### flickcurl_new ()

    flickcurl *         flickcurl_new                       (void);

Create a Flickcurl sesssion

Returns : | new flickcurl object or NULL on fialure

### flickcurl_new_with_handle ()

    flickcurl *         flickcurl_new_with_handle           (void *curl_handle);

Create a Flickcurl sesssion from an existing CURL* handler

This allows setting up or re-using an existing CURL handle with Flickcurl, however the library will call curl_easy_setopt to set options based on the operation being performed. If these need to be over-ridden, use `flickcurl_set_curl_setopt_handler()` to adjust the options.

NOTE: The type of `handle` is void* so that curl headers are optional when compiling against flickcurl.

`curl_handle` : | CURL* handle
Returns : | new flickcurl object or NULL on fialure

### flickcurl_free ()

    void                flickcurl_free                      (flickcurl *fc);

Destroy flickcurl session

`fc` : | flickcurl object

### flickcurl_get_current_request_wait ()

    int                 flickcurl_get_current_request_wait  (flickcurl *fc);

Get current wait that would be applied for a web service request called now

Returns the wait time that would be applied in order to delay a web service request such that the web service rate limit is met.

See `flickcurl_set_request_delay()` which by default is set to 1000ms.

`fc` : | flickcurl object
Returns : | delay in usecs or < 0 if delay is more than 247 seconds ('infinity')

### flickcurl_get_extras_format_info ()

    int                 flickcurl_get_extras_format_info    (int extras_format,
                                                             const char **name_p,
                                                             const char **label_p);

Get APi extras format parameter value information

As described 2008-08-19 in http://code.flickr.com/blog/2008/08/19/standard-photos-response-apis-for-civilized-age/

`extras_format` : | input param - extras format index
`name_p` : | output param - pointer to store feed format name
`label_p` : | output param - pointer to store feed format label
Returns : | non-0 if extras_format is out of range

### flickcurl_get_feed_format_info ()

    int                 flickcurl_get_feed_format_info      (int feed_format,
                                                             const char **name_p,
                                                             const char **label_p,
                                                             const char **mime_type_p);

Get feed format parameter value information

As announced 2008-08-25 in http://code.flickr.com/blog/2008/08/25/api-responses-as-feeds/

`feed_format` : | input param - feed format index
`name_p` : | output param - pointer to store feed format name
`label_p` : | output param - pointer to store feed format label
`mime_type_p` : | output param - pointer to store feed format mime type
Returns : | non-0 if feed_format is out of range

### flickcurl_curl_setopt_handler ()

    void                (*flickcurl_curl_setopt_handler)    (void *user_data,
                                                             void *curl_handle);

Flickcurl curl options handle callback.

For use with `flickcurl_set_curl_setopt_handler()` to set curl handle options once Flickcurl has created the CURL* handle internally.

NOTE: The type of `curl_handle` is void* so that curl headers are optional when compiling against flickcurl.

WARNING: This callback is called with two void args in the order curl handler user data, curl handle (CURL* pointer) - take care in getting them correct in implementation.

`user_data` : | user data pointer
`curl_handle` : | curl CURL* handle

### flickcurl_set_curl_setopt_handler ()

    void                flickcurl_set_curl_setopt_handler   (flickcurl *fc,
                                                             flickcurl_curl_setopt_handler curl_handler,
                                                             void *curl_handler_data);

Set curl set option callback handler.

This handler is called for every curl request after all internal curl_easy_setopt calls are made on the internal CURL* handle and just before curl_easy_perform is invoked to start the retrieval. Thus, this callback can override any internal configuration.

If a simple once-only CURL configuration is needed, using `flickcurl_new_with_handle()` may be easier.

WARNING: The `curl_handler` callback is called with 2 void args in the order user data (`curl_handler_data` value), curl_handle (CURL* pointer) - take care to use them correct in implementation.

`fc` : | flickcurl object
`curl_handler` : | curl set options handler (or NULL)
`curl_handler_data` : | user data for handler (or NULL)

### flickcurl_set_data ()

    void                flickcurl_set_data                  (flickcurl *fc,
                                                             void *data,
                                                             size_t data_length);

Set web service request content data.

`fc` : | flickcurl object
`data` : | data pointer
`data_length` : | data length

### flickcurl_set_error_handler ()

    void                flickcurl_set_error_handler         (flickcurl *fc,
                                                             flickcurl_message_handler error_handler,
                                                             void *error_data);

Set Flickcurl error handler.

`fc` : | flickcurl object
`error_handler` : | error handler function
`error_data` : | error handler data

### flickcurl_set_http_accept ()

    void                flickcurl_set_http_accept           (flickcurl *fc,
                                                             const char *value);

Set HTTP accept header value for flickcurl requests

`fc` : | flickcurl object
`value` : | HTTP Accept header value

### flickcurl_set_proxy ()

    void                flickcurl_set_proxy                 (flickcurl *fc,
                                                             const char *proxy);

Set HTTP proxy for flickcurl requests

`fc` : | flickcurl object
`proxy` : | HTTP proxy string

### flickcurl_set_request_delay ()

    void                flickcurl_set_request_delay         (flickcurl *fc,
                                                             long delay_msec Param2);

Set web service request delay

`fc` : | flickcurl object

### flickcurl_set_service_uri ()

    void                flickcurl_set_service_uri           (flickcurl *fc,
                                                             const char *uri);

Set Web Service URI for flickcurl requests

Sets the service to the default (Flickr API web service) if `uri` is NULL.

`fc` : | flickcurl object
`uri` : | Service URI (or NULL)

### flickcurl_set_replace_service_uri ()

    void                flickcurl_set_replace_service_uri   (flickcurl *fc,
                                                             const char *uri);

Set Web Replace Service URI for flickcurl requests

Sets the replace service to the default (Flickr API web replace_service) if `uri` is NULL.

`fc` : | flickcurl object
`uri` : | Replace Service URI (or NULL)

### flickcurl_set_upload_service_uri ()

    void                flickcurl_set_upload_service_uri    (flickcurl *fc,
                                                             const char *uri);

Set Web Upload Service URI for flickcurl requests

Sets the upload service to the default (Flickr API web upload_service) if `uri` is NULL.

`fc` : | flickcurl object
`uri` : | Upload Service URI (or NULL)

### flickcurl_set_sign ()

    void                flickcurl_set_sign                  (flickcurl *fc);

Make the next request signed.

`fc` : | flickcurl object

### flickcurl_set_tag_handler ()

    void                flickcurl_set_tag_handler           (flickcurl *fc,
                                                             flickcurl_tag_handler tag_handler,
                                                             void *tag_data);

Set Flickcurl tag handler.

`fc` : | flickcurl object
`tag_handler` : | tag handler function
`tag_data` : | tag handler data

### flickcurl_set_user_agent ()

    void                flickcurl_set_user_agent            (flickcurl *fc,
                                                             const char *user_agent);

Set Flickcurl HTTP user agent string

`fc` : | flickcurl object
`user_agent` : | user agent string

### flickcurl_set_write ()

    void                flickcurl_set_write                 (flickcurl *fc,
                                                             int is_write);

Set writeable flag.

`fc` : | flickcurl object
`is_write` : | writeable flag

### flickcurl_set_xml_data ()

    void                flickcurl_set_xml_data              (flickcurl *fc,
                                                             xmlDocPtr doc);

Set web service request content data from XML DOM.

`fc` : | flickcurl object
`doc` : | XML dom