## section-core

section-core

## Functions

void | (*flickcurl_message_handler) ()
int | flickcurl_init ()
void | flickcurl_finish ()
flickcurl * | flickcurl_new ()
flickcurl * | flickcurl_new_with_handle ()
void | flickcurl_free ()
int | flickcurl_get_current_request_wait ()
int | flickcurl_get_extras_format_info ()
int | flickcurl_get_feed_format_info ()
void | (*flickcurl_curl_setopt_handler) ()
void | flickcurl_set_curl_setopt_handler ()
void | flickcurl_set_data ()
void | flickcurl_set_error_handler ()
void | flickcurl_set_http_accept ()
void | flickcurl_set_proxy ()
void | flickcurl_set_request_delay ()
void | flickcurl_set_service_uri ()
void | flickcurl_set_replace_service_uri ()
void | flickcurl_set_upload_service_uri ()
void | flickcurl_set_sign ()
void | flickcurl_set_tag_handler ()
void | flickcurl_set_user_agent ()
void | flickcurl_set_write ()
void | flickcurl_set_xml_data ()

## Types and Values

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

## Description

## Functions

### flickcurl_message_handler ()

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

Flickcurl Message handler callback.

#### Parameters

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.

#### Parameters

curl_handle | CURL* handle |

#### Returns

new flickcurl object or NULL on fialure

### flickcurl_free ()

    void
    flickcurl_free (flickcurl *fc);

Destroy flickcurl session

#### Parameters

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.

#### Parameters

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/

#### Parameters

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/

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

fc | flickcurl object |
delay_msec | web service delay in milliseconds |

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### flickcurl_set_sign ()

    void
    flickcurl_set_sign (flickcurl *fc);

Make the next request signed.

#### Parameters

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.

#### Parameters

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

#### Parameters

fc | flickcurl object |
user_agent | user agent string |

### flickcurl_set_write ()

    void
    flickcurl_set_write (flickcurl *fc,
                         int is_write);

Set writeable flag.

#### Parameters

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.

#### Parameters

fc | flickcurl object |
doc | XML dom |

## Types and Values

### 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;