CURL integration library

Download JSON using libcurl. More...

Collaboration diagram for CURL integration library:

Data Structures
struct	GNUNET_CURL_DownloadBuffer
	Buffer data structure we use to buffer the HTTP download before giving it to the JSON parser. More...
struct	GNUNET_CURL_StreamHandlers
	What to call for a job added with GNUNET_CURL_job_add_stream(). More...

Macros
#define	GNUNET_CURL_STREAM_PAUSE   CURL_WRITEFUNC_PAUSE
	Return value from a GNUNET_CURL_StreamCallback asking for delivery to stop until GNUNET_CURL_job_set_paused() is called.

Typedefs
typedef void(*	GNUNET_CURL_RescheduleCallback) (void *cls)
	Function called by the context to ask for the event loop to be rescheduled, that is the application should call GNUNET_CURL_get_select_info() as the set of sockets we care about just changed.
typedef void *(*	GNUNET_CURL_RawParser) (struct GNUNET_CURL_DownloadBuffer *db, CURL *eh, long *response_code)
	Parses the raw response we got from the Web server.
typedef void(*	GNUNET_CURL_ResponseCleaner) (void *response)
	Deallocate the response.
typedef void(*	GNUNET_CURL_JobCompletionCallback) (void *cls, long response_code, const void *response)
	Function to call upon completion of a job.
typedef void(*	GNUNET_CURL_RawJobCompletionCallback) (void *cls, long response_code, const void *body, size_t body_size)
	Function to call upon completion of a raw job.
typedef enum GNUNET_GenericReturnValue(*	GNUNET_CURL_StreamHeaderCallback) (void *cls, const char *line, size_t line_size)
	Function called with one raw header line of the response, as it arrives.
typedef size_t(*	GNUNET_CURL_StreamCallback) (void *cls, const void *data, size_t data_size)
	Function called with a chunk of the response body as it arrives.

Functions
struct GNUNET_CURL_Context *	GNUNET_CURL_init (GNUNET_CURL_RescheduleCallback cb, void *cb_cls)
	Initialise this library.
void	GNUNET_CURL_get_select_info (struct GNUNET_CURL_Context *ctx, fd_set *read_fd_set, fd_set *write_fd_set, fd_set *except_fd_set, int *max_fd, long *timeout)
	Obtain the information for a select() call to wait until GNUNET_CURL_perform() is ready again.
enum GNUNET_GenericReturnValue	GNUNET_CURL_append_header (struct GNUNET_CURL_Context *ctx, const char *header)
	Add custom request header.
void	GNUNET_CURL_perform (struct GNUNET_CURL_Context *ctx)
	Run the main event loop for the CURL interaction.
void	GNUNET_CURL_perform2 (struct GNUNET_CURL_Context *ctx, GNUNET_CURL_RawParser rp, GNUNET_CURL_ResponseCleaner rc)
	Run the main event loop for the HTTP interaction.
void	GNUNET_CURL_fini (struct GNUNET_CURL_Context *ctx)
	Cleanup library initialisation resources.
struct GNUNET_CURL_Job *	GNUNET_CURL_job_add_stream (struct GNUNET_CURL_Context *ctx, CURL *eh, const struct curl_slist *job_headers, const struct GNUNET_CURL_StreamHandlers *sh)
	Schedule a CURL request whose response is delivered incrementally, rather than buffered in full and handed over at the end.
void	GNUNET_CURL_job_set_paused (struct GNUNET_CURL_Job *job, bool recv_paused, bool send_paused)
	Say which directions of job are to be paused from now on.
struct GNUNET_CURL_Job *	GNUNET_CURL_job_add (struct GNUNET_CURL_Context *ctx, CURL *eh, GNUNET_CURL_JobCompletionCallback jcc, void *jcc_cls)
	Schedule a CURL request to be executed and call the given jcc upon its completion.
struct GNUNET_CURL_Job *	GNUNET_CURL_job_add_with_ct_json (struct GNUNET_CURL_Context *ctx, CURL *eh, GNUNET_CURL_JobCompletionCallback jcc, void *jcc_cls)
	Schedule a CURL request to be executed and call the given jcc upon its completion.
void	GNUNET_CURL_set_userpass (struct GNUNET_CURL_Context *ctx, const char *userpass)
	Force use of the provided username and password for client authentication for all operations performed with ctx.
void	GNUNET_CURL_set_tlscert (struct GNUNET_CURL_Context *ctx, const char *certtype, const char *certfile, const char *keyfile, const char *keypass)
	Force use of the provided TLS client certificate for client authentication for all operations performed with ctx.
struct GNUNET_CURL_Job *	GNUNET_CURL_job_add2 (struct GNUNET_CURL_Context *ctx, CURL *eh, const struct curl_slist *job_headers, GNUNET_CURL_JobCompletionCallback jcc, void *jcc_cls)
	Schedule a CURL request to be executed and call the given jcc upon its completion.
struct GNUNET_CURL_Job *	GNUNET_CURL_job_add_raw (struct GNUNET_CURL_Context *ctx, CURL *eh, const struct curl_slist *job_headers, GNUNET_CURL_RawJobCompletionCallback jcc, void *jcc_cls)
	Schedule a CURL request to be executed and call the given jcc upon its completion.
void	GNUNET_CURL_extend_headers (struct GNUNET_CURL_Job *job, const struct curl_slist *extra_headers)
	Add extra_headers to the HTTP headers for job.
void	GNUNET_CURL_job_cancel (struct GNUNET_CURL_Job *job)
	Cancel a job.
struct GNUNET_CURL_RescheduleContext *	GNUNET_CURL_gnunet_rc_create (struct GNUNET_CURL_Context *ctx)
	Initialize reschedule context.
struct GNUNET_CURL_RescheduleContext *	GNUNET_CURL_gnunet_rc_create_with_parser (struct GNUNET_CURL_Context *ctx, GNUNET_CURL_RawParser rp, GNUNET_CURL_ResponseCleaner rc)
	Initialize reschedule context; with custom response parser.
void	GNUNET_CURL_gnunet_rc_destroy (struct GNUNET_CURL_RescheduleContext *rc)
	Destroy reschedule context.
void	GNUNET_CURL_gnunet_scheduler_reschedule (void *cls)
	Implementation of the GNUNET_CURL_RescheduleCallback for GNUnet's scheduler.
void	GNUNET_CURL_enable_async_scope_header (struct GNUNET_CURL_Context *ctx, const char *header_name)
	Enable sending the async scope ID as a header.
enum GNUNET_GenericReturnValue	GNUNET_CURL_is_valid_scope_id (const char *scope_id)
	Return GNUNET_YES if given a valid scope ID and GNUNET_NO otherwise.

Detailed Description

Download JSON using libcurl.

Macro Definition Documentation

GNUNET_CURL_STREAM_PAUSE

#define GNUNET_CURL_STREAM_PAUSE   CURL_WRITEFUNC_PAUSE

Return value from a GNUNET_CURL_StreamCallback asking for delivery to stop until GNUNET_CURL_job_set_paused() is called.

Nothing is lost: the same bytes are offered again after the job is resumed.

Definition at line 257 of file gnunet_curl_lib.h.

Typedef Documentation

GNUNET_CURL_RescheduleCallback

typedef void(* GNUNET_CURL_RescheduleCallback) (void *cls)

Function called by the context to ask for the event loop to be rescheduled, that is the application should call GNUNET_CURL_get_select_info() as the set of sockets we care about just changed.

Parameters

cls

closure

Definition at line 48 of file gnunet_curl_lib.h.

GNUNET_CURL_RawParser

typedef void *(* GNUNET_CURL_RawParser) (struct GNUNET_CURL_DownloadBuffer *db, CURL *eh, long *response_code)

Parses the raw response we got from the Web server.

Parameters

db	the raw data
eh	handle
response_code	HTTP response code

Returns

the parsed object

Definition at line 83 of file gnunet_curl_lib.h.

GNUNET_CURL_ResponseCleaner

typedef void(* GNUNET_CURL_ResponseCleaner) (void *response)

Deallocate the response.

Parameters

response

object to clean

Definition at line 93 of file gnunet_curl_lib.h.

GNUNET_CURL_JobCompletionCallback

typedef void(* GNUNET_CURL_JobCompletionCallback) (void *cls, long response_code, const void *response)

Function to call upon completion of a job.

Parameters

cls	closure
response_code	HTTP response code from server, 0 on hard error
response	in JSON, NULL if response was not in JSON format

Definition at line 200 of file gnunet_curl_lib.h.

GNUNET_CURL_RawJobCompletionCallback

typedef void(* GNUNET_CURL_RawJobCompletionCallback) (void *cls, long response_code, const void *body, size_t body_size)

Function to call upon completion of a raw job.

Parameters

cls	closure
response_code	HTTP response code from server, 0 on hard error
body	http body of the response
body_size	number of bytes in body

Definition at line 214 of file gnunet_curl_lib.h.

GNUNET_CURL_StreamHeaderCallback

typedef enum GNUNET_GenericReturnValue(* GNUNET_CURL_StreamHeaderCallback) (void *cls, const char *line, size_t line_size)

Function called with one raw header line of the response, as it arrives.

Only used by GNUNET_CURL_job_add_stream().

Everything the server sends in a header section is passed on, which is more than just the fields of the final response:

• the status line ("HTTP/1.1 200 OK") of every response, including the interim (1xx) ones and any that libcurl handles internally, such as an authentication round it replays;
• the empty line that terminates each header section;
• trailer fields, which arrive after the body and are indented from the header fields only by having come after that empty line.

A caller that wants "the headers of the final response" therefore has to track which section it is in; there is no other way to tell a trailer from a header, or a 1xx field from a real one.

Parameters

cls	closure
line	the header line; NOT 0-terminated, and still carrying its CRLF
line_size	number of bytes in line

Returns

GNUNET_OK to continue the transfer, GNUNET_SYSERR to fail it

Definition at line 214 of file gnunet_curl_lib.h.

GNUNET_CURL_StreamCallback

typedef size_t(* GNUNET_CURL_StreamCallback) (void *cls, const void *data, size_t data_size)

Function called with a chunk of the response body as it arrives.

Only used by GNUNET_CURL_job_add_stream().

Parameters

cls	closure
data	the bytes
data_size	number of bytes in data

Returns

data_size to accept the chunk, GNUNET_CURL_STREAM_PAUSE to stop delivery until GNUNET_CURL_job_set_paused() is called; returning any other value fails the transfer

Definition at line 272 of file gnunet_curl_lib.h.

Function Documentation

GNUNET_CURL_init()

struct GNUNET_CURL_Context * GNUNET_CURL_init	(	GNUNET_CURL_RescheduleCallback	cb,
		void *	cb_cls
	)

Initialise this library.

This function should be called before using any of the following functions.

Parameters

cb	function to call when rescheduling is required
cb_cls	closure for cb

Returns

library context

Definition at line 259 of file curl.c.

{
  struct GNUNET_CURL_Context *ctx;
  CURLM *multi;
  CURLSH *share;
 
  if (curl_fail)
  {
    GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                "Curl was not initialised properly\n");
    return NULL;
  }
  if (NULL == (multi = curl_multi_init ()))
  {
    GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                "Failed to create a Curl multi handle\n");
    return NULL;
  }
  if (NULL == (share = curl_share_init ()))
  {
    GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                "Failed to create a Curl share handle\n");
    return NULL;
  }
  ctx = GNUNET_new (struct GNUNET_CURL_Context);
  ctx->cb = cb;
  ctx->cb_cls = cb_cls;
  ctx->multi = multi;
  ctx->share = share;
  return ctx;
}

References GNUNET_CURL_Context::cb, GNUNET_CURL_Context::cb_cls, ctx, curl_fail, GNUNET_ERROR_TYPE_ERROR, GNUNET_log, GNUNET_new, multi, and GNUNET_CURL_Context::share.

GNUNET_CURL_get_select_info()

void GNUNET_CURL_get_select_info	(	struct GNUNET_CURL_Context *	ctx,
		fd_set *	read_fd_set,
		fd_set *	write_fd_set,
		fd_set *	except_fd_set,
		int *	max_fd,
		long *	timeout
	)

Obtain the information for a select() call to wait until GNUNET_CURL_perform() is ready again.

Basically, a client should use this API to prepare for select(), then block on select(), then call GNUNET_CURL_perform() and then start again until the work with the context is done.

This function will NOT zero out the sets and assumes that max_fd and timeout are already set to minimal applicable values. It is safe to give this API FD-sets and max_fd and timeout that are already initialized to some other descriptors that need to go into the select() call.

Parameters

ctx	context to get the event loop information for
read_fd_set	will be set for any pending read operations
write_fd_set	will be set for any pending write operations
except_fd_set	is here because curl_multi_fdset() has this argument
max_fd	set to the highest FD included in any set; if the existing sets have no FDs in it, the initial value should be "-1". (Note that max_fd + 1 will need to be passed to select().)
timeout	set to the timeout in milliseconds (!); -1 means no timeout (NULL, blocking forever is OK), 0 means to proceed immediately with GNUNET_CURL_perform().

Definition at line 1040 of file curl.c.

{
  long to;
  int m;
 
  m = -1;
  GNUNET_assert (CURLM_OK ==
                 curl_multi_fdset (ctx->multi,
                                   read_fd_set,
                                   write_fd_set,
                                   except_fd_set,
                                   &m));
  to = *timeout;
  *max_fd = GNUNET_MAX (m, *max_fd);
  GNUNET_assert (CURLM_OK ==
                 curl_multi_timeout (ctx->multi,
                                     &to));
 
  /* Only if what we got back from curl is smaller than what we
     already had (-1 == infinity!), then update timeout */
  if ((to < *timeout) && (-1 != to))
    *timeout = to;
  if ((-1 == (*timeout)) && (NULL != ctx->jobs_head))
    *timeout = to;
}

References ctx, GNUNET_assert, GNUNET_MAX, m, and timeout.

Referenced by context_task().

Here is the caller graph for this function:

GNUNET_CURL_append_header()

enum GNUNET_GenericReturnValue GNUNET_CURL_append_header	(	struct GNUNET_CURL_Context *	ctx,
		const char *	header
	)

Add custom request header.

Parameters

ctx	cURL context.
header	header string; will be given to the context AS IS.

Returns

GNUNET_OK if no errors occurred, GNUNET_SYSERR otherwise.

Definition at line 909 of file curl.c.

{
  struct curl_slist *job_headers;
 
  job_headers = curl_slist_append (ctx->common_headers,
                                   header);
  if (NULL == job_headers)
  {
    GNUNET_break (0);
    return GNUNET_SYSERR;
  }
  ctx->common_headers = job_headers;
  return GNUNET_OK;
}

References ctx, GNUNET_break, GNUNET_OK, and GNUNET_SYSERR.

GNUNET_CURL_perform()

void GNUNET_CURL_perform

(

struct GNUNET_CURL_Context *

ctx

)

Run the main event loop for the CURL interaction.

Parameters

ctx	the library context

Definition at line 1031 of file curl.c.

{
  GNUNET_CURL_perform2 (ctx,
                        &GNUNET_CURL_download_get_result_,
                        (GNUNET_CURL_ResponseCleaner) & json_decref);
}

References ctx, GNUNET_CURL_download_get_result_(), and GNUNET_CURL_perform2().

Here is the call graph for this function:

GNUNET_CURL_perform2()

void GNUNET_CURL_perform2	(	struct GNUNET_CURL_Context *	ctx,
		GNUNET_CURL_RawParser	rp,
		GNUNET_CURL_ResponseCleaner	rc
	)

Run the main event loop for the HTTP interaction.

Parameters

ctx	the library context
rp	parses the raw response returned from the Web server.
rc	cleans/frees the response

Definition at line 927 of file curl.c.

{
  CURLMsg *cmsg;
  int n_running;
  int n_completed;
 
  (void) curl_multi_perform (ctx->multi,
                             &n_running);
  while (NULL != (cmsg = curl_multi_info_read (ctx->multi,
                                               &n_completed)))
  {
    struct GNUNET_CURL_Job *job;
    struct GNUNET_TIME_Relative duration;
    long response_code;
    void *response;
 
    /* Only documented return value is CURLMSG_DONE */
    GNUNET_break (CURLMSG_DONE == cmsg->msg);
    GNUNET_assert (CURLE_OK ==
                   curl_easy_getinfo (cmsg->easy_handle,
                                      CURLINFO_PRIVATE,
                                      (char **) &job));
    GNUNET_assert (job->ctx == ctx);
    response_code = 0;
    duration = GNUNET_TIME_absolute_get_duration (job->start_time);
    if (job->streaming)
    {
      /* Body already delivered chunk by chunk; nothing was kept, so
         the completion callback is told about the outcome only.
 
         A streaming caller has forwarded the status line and part of
         the body long before this runs, so the one thing it still
         needs to know is whether the transfer actually finished --
         and a transfer that died mid-body still has a perfectly good
         CURLINFO_RESPONSE_CODE from the status line libcurl parsed at
         the start.  Reporting that would say "200 OK" about a
         connection that was cut in half.  Report the hard error
         instead, and leave telling the two apart to the caller, which
         knows whether it has already committed to a status. */
      if (CURLE_OK != cmsg->data.result)
      {
        GNUNET_log (GNUNET_ERROR_TYPE_INFO,
                    "Streaming transfer failed: %s\n",
                    curl_easy_strerror (cmsg->data.result));
      }
      else
      {
        GNUNET_break (CURLE_OK ==
                      curl_easy_getinfo (job->easy_handle,
                                         CURLINFO_RESPONSE_CODE,
                                         &response_code));
      }
      job->sh.jcc (job->sh.jcc_cls,
                   response_code,
                   NULL,
                   0);
    }
    else if (NULL != job->jcc_raw)
    {
      /* RAW mode, no parsing */
      GNUNET_break (CURLE_OK ==
                    curl_easy_getinfo (job->easy_handle,
                                       CURLINFO_RESPONSE_CODE,
                                       &response_code));
      job->jcc_raw (job->jcc_raw_cls,
                    response_code,
                    job->db.buf,
                    job->db.buf_size);
    }
    else
    {
      /* to be parsed via 'rp' */
      response = rp (&job->db,
                     job->easy_handle,
                     &response_code);
      job->jcc (job->jcc_cls,
                response_code,
                response);
      rc (response);
    }
    {
      const char *url = NULL;
 
      if (CURLE_UNKNOWN_OPTION ==
          curl_easy_getinfo (job->easy_handle,
                             CURLINFO_EFFECTIVE_URL,
                             &url))
        url = "<unknown>";
      GNUNET_log (GNUNET_ERROR_TYPE_INFO,
                  "HTTP request for `%s' finished with %u after %s\n",
                  url,
                  (unsigned int) response_code,
                  GNUNET_TIME_relative2s (duration,
                                          true));
      /* Note: we MUST NOT free 'url' here */
    }
    GNUNET_CURL_job_cancel (job);
  }
}

References ctx, duration, GNUNET_assert, GNUNET_break, GNUNET_CURL_job_cancel(), GNUNET_ERROR_TYPE_INFO, GNUNET_log, GNUNET_TIME_absolute_get_duration(), GNUNET_TIME_relative2s(), job, response, and rp.

Referenced by context_task(), and GNUNET_CURL_perform().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CURL_fini()

void GNUNET_CURL_fini

(

struct GNUNET_CURL_Context *

ctx

)

Cleanup library initialisation resources.

This function should be called after using this library to cleanup the resources occupied during library's initialisation.

Parameters

ctx	the library context

Definition at line 1073 of file curl.c.

{
  /* all jobs must have been cancelled at this time, assert this */
  GNUNET_assert (NULL == ctx->jobs_head);
  curl_share_cleanup (ctx->share);
  curl_multi_cleanup (ctx->multi);
  curl_slist_free_all (ctx->common_headers);
  GNUNET_free (ctx->userpass);
  GNUNET_free (ctx->certtype);
  GNUNET_free (ctx->certfile);
  GNUNET_free (ctx->keyfile);
  GNUNET_free (ctx->keypass);
  GNUNET_free (ctx);
}

References ctx, GNUNET_assert, and GNUNET_free.

GNUNET_CURL_job_add_stream()

struct GNUNET_CURL_Job * GNUNET_CURL_job_add_stream	(	struct GNUNET_CURL_Context *	ctx,
		CURL *	eh,
		const struct curl_slist *	job_headers,
		const struct GNUNET_CURL_StreamHandlers *	sh
	)

Schedule a CURL request whose response is delivered incrementally, rather than buffered in full and handed over at the end.

Use this when the response may be larger than memory, or when it has to start reaching its own consumer before the server has finished sending it. GNUNET_CURL_job_add_raw() is the buffering counterpart and remains the right choice for anything that fits.

The job takes over CURLOPT_WRITEFUNCTION, CURLOPT_WRITEDATA, CURLOPT_HEADERFUNCTION, CURLOPT_HEADERDATA and CURLOPT_PRIVATE on eh; setting any of them on the caller's side has no effect. CURLOPT_READFUNCTION is left alone, so a request body is still the caller's to supply, and it may pause the upload with CURL_READFUNC_PAUSE and resume it with GNUNET_CURL_job_set_paused().

Parameters

ctx	context to execute the job in
eh	curl easy handle for the request, will be executed AND cleaned up
job_headers	extra headers to add for this request
sh	what to call as the response arrives; copied, so it need not outlive this call

Returns

NULL on error (in this case, eh is still released!)

Definition at line 633 of file curl.c.

{
  struct GNUNET_CURL_Job *job;
  struct curl_slist *all_headers;
 
  GNUNET_assert (NULL != sh);
  GNUNET_assert (NULL != sh->scb);
  GNUNET_assert (NULL != sh->jcc);
  all_headers = setup_job_headers (ctx,
                                   job_headers);
  if (NULL == (job = setup_job (eh,
                                ctx,
                                all_headers,
                                sh)))
    return NULL;
  ctx->cb (ctx->cb_cls);
  return job;
}

References ctx, GNUNET_assert, job, setup_job(), setup_job_headers(), and sh.

Here is the call graph for this function:

GNUNET_CURL_job_set_paused()

void GNUNET_CURL_job_set_paused	(	struct GNUNET_CURL_Job *	job,
		bool	recv_paused,
		bool	send_paused
	)

Say which directions of job are to be paused from now on.

A job pauses itself by returning GNUNET_CURL_STREAM_PAUSE from its GNUNET_CURL_StreamCallback, or CURL_READFUNC_PAUSE from its CURLOPT_READFUNCTION; this is how it is let go again. The state is absolute, not a change: pass what should be true afterwards, so resuming everything is (false, false) and resuming only the receive side of a job whose send side is still paused is (false, true).

Deliberately not a "which direction(s) to resume" bitmask, which is how curl_easy_pause() reads at first glance and is not what it means. Its CURLPAUSE_RECV_CONT, CURLPAUSE_SEND_CONT and CURLPAUSE_CONT are all defined as 0 — a bitmask names the directions that stay paused — so "resume just the receive side" has no spelling there at all, and the natural-looking one silently resumes both. Two booleans cannot be got backwards without saying something visibly wrong.

Two further things are easy to get wrong:

• It may call back synchronously. libcurl hands over whatever it buffered while paused from inside curl_easy_pause(), so the stream callback (or the read callback) can run, and can pause again, before this function returns. A caller that is itself inside a callback of some other event source should defer this to its own event loop rather than call it there.
• It must not be called after the job's completion callback has run. The easy handle is destroyed with the job immediately afterwards, and job is a dangling pointer from then on.

Parameters

job	job whose pause state to set
recv_paused	true to hold the receive side paused
send_paused	true to hold the send side paused

Definition at line 657 of file curl.c.

{
  /* curl_easy_pause() takes the directions that are to REMAIN paused,
     which is why this function does not take the ones to resume: every
     way of naming a single direction to resume (CURLPAUSE_RECV_CONT,
     CURLPAUSE_SEND_CONT, CURLPAUSE_CONT) is defined as 0. */
  GNUNET_break (CURLE_OK ==
                curl_easy_pause (job->easy_handle,
                                 (recv_paused ? CURLPAUSE_RECV : 0)
                                 | (send_paused ? CURLPAUSE_SEND : 0)));
  /* Not optional: curl_multi_fdset() leaves out the socket of a
     paused handle, so until the event loop is told to ask again it
     will not wait on it -- and the transfer we just resumed would sit
     there until some other job happened to wake the loop up. */
  job->ctx->cb (job->ctx->cb_cls);
}

References GNUNET_break, and job.

GNUNET_CURL_job_add()

struct GNUNET_CURL_Job * GNUNET_CURL_job_add	(	struct GNUNET_CURL_Context *	ctx,
		CURL *	eh,
		GNUNET_CURL_JobCompletionCallback	jcc,
		void *	jcc_cls
	)

Schedule a CURL request to be executed and call the given jcc upon its completion.

Note that the context will make use of the CURLOPT_PRIVATE facility of the CURL eh.

Parameters

ctx	context to execute the job in
eh	curl easy handle for the request, will be executed AND cleaned up
jcc	callback to invoke upon completion
jcc_cls	closure for jcc

Returns

NULL on error (in this case, eh is still released!)

Definition at line 753 of file curl.c.

{
  return GNUNET_CURL_job_add2 (ctx,
                               eh,
                               NULL,
                               jcc,
                               jcc_cls);
}

References ctx, GNUNET_CURL_job_add2(), GNUNET_CURL_Job::jcc, and GNUNET_CURL_Job::jcc_cls.

Here is the call graph for this function:

GNUNET_CURL_job_add_with_ct_json()

struct GNUNET_CURL_Job * GNUNET_CURL_job_add_with_ct_json	(	struct GNUNET_CURL_Context *	ctx,
		CURL *	eh,
		GNUNET_CURL_JobCompletionCallback	jcc,
		void *	jcc_cls
	)

Schedule a CURL request to be executed and call the given jcc upon its completion.

Note that the context will make use of the CURLOPT_PRIVATE facility of the CURL eh.

This function modifies the CURL handle to add the "Content-Type: application/json" header.

Parameters

ctx	context to execute the job in
eh	curl easy handle for the request, will be executed AND cleaned up
jcc	callback to invoke upon completion
jcc_cls	closure for jcc

Returns

NULL on error (in this case, eh is still released!)

Definition at line 730 of file curl.c.

{
  struct GNUNET_CURL_Job *job;
  struct curl_slist *job_headers = NULL;
 
  GNUNET_assert (NULL != (job_headers =
                            curl_slist_append (NULL,
                                               "Content-Type: application/json")
                          ));
  job = GNUNET_CURL_job_add2 (ctx,
                              eh,
                              job_headers,
                              jcc,
                              jcc_cls);
  curl_slist_free_all (job_headers);
  return job;
}

References ctx, GNUNET_assert, GNUNET_CURL_job_add2(), and job.

Here is the call graph for this function:

GNUNET_CURL_set_userpass()

void GNUNET_CURL_set_userpass	(	struct GNUNET_CURL_Context *	ctx,
		const char *	userpass
	)

Force use of the provided username and password for client authentication for all operations performed with ctx.

Parameters

ctx	context to set authentication data for
userpass	string with "$USERNAME:$PASSWORD"

Definition at line 227 of file curl.c.

{
  GNUNET_free (ctx->userpass);
  if (NULL != userpass)
    ctx->userpass = GNUNET_strdup (userpass);
}

References ctx, GNUNET_free, and GNUNET_strdup.

GNUNET_CURL_set_tlscert()

void GNUNET_CURL_set_tlscert	(	struct GNUNET_CURL_Context *	ctx,
		const char *	certtype,
		const char *	certfile,
		const char *	keyfile,
		const char *	keypass
	)

Force use of the provided TLS client certificate for client authentication for all operations performed with ctx.

Note that if the provided information is incorrect, the earliest operation that could fail is GNUNET_CURL_job_add() or GNUNET_CURL_job_add2()!

Parameters

ctx	context to set authentication data for
certtype	type of the certificate
certfile	file with the certificate
keyfile	file with the private key
keypass	passphrase to decrypt keyfile (or NULL)

Definition at line 237 of file curl.c.

{
  GNUNET_free (ctx->certtype);
  GNUNET_free (ctx->certfile);
  GNUNET_free (ctx->keyfile);
  GNUNET_free (ctx->keypass);
  if (NULL != certtype)
    ctx->certtype = GNUNET_strdup (certtype);
  if (NULL != certfile)
    ctx->certfile = GNUNET_strdup (certfile);
  if (NULL != keyfile)
    ctx->keyfile = GNUNET_strdup (keyfile);
  if (NULL != keypass)
    ctx->keypass = GNUNET_strdup (keypass);
}

References ctx, GNUNET_free, and GNUNET_strdup.

GNUNET_CURL_job_add2()

struct GNUNET_CURL_Job * GNUNET_CURL_job_add2	(	struct GNUNET_CURL_Context *	ctx,
		CURL *	eh,
		const struct curl_slist *	job_headers,
		GNUNET_CURL_JobCompletionCallback	jcc,
		void *	jcc_cls
	)

Schedule a CURL request to be executed and call the given jcc upon its completion.

Note that the context will make use of the CURLOPT_PRIVATE facility of the CURL eh.

Parameters

ctx	context to execute the job in
eh	curl easy handle for the request, will be executed AND cleaned up
job_headers	extra headers to add for this request
jcc	callback to invoke upon completion
jcc_cls	closure for jcc

Returns

NULL on error (in this case, eh is still released!)

Definition at line 678 of file curl.c.

{
  struct GNUNET_CURL_Job *job;
  struct curl_slist *all_headers;
 
  GNUNET_assert (NULL != jcc);
  if ( (NULL != ctx->userpass) &&
       (0 != curl_easy_setopt (eh,
                               CURLOPT_USERPWD,
                               ctx->userpass)) )
    return NULL;
  if ( (NULL != ctx->certfile) &&
       (0 != curl_easy_setopt (eh,
                               CURLOPT_SSLCERT,
                               ctx->certfile)) )
    return NULL;
  if ( (NULL != ctx->certtype) &&
       (0 != curl_easy_setopt (eh,
                               CURLOPT_SSLCERTTYPE,
                               ctx->certtype)) )
    return NULL;
  if ( (NULL != ctx->keyfile) &&
       (0 != curl_easy_setopt (eh,
                               CURLOPT_SSLKEY,
                               ctx->keyfile)) )
    return NULL;
  if ( (NULL != ctx->keypass) &&
       (0 != curl_easy_setopt (eh,
                               CURLOPT_KEYPASSWD,
                               ctx->keypass)) )
    return NULL;
 
  all_headers = setup_job_headers (ctx,
                                   job_headers);
  if (NULL == (job = setup_job (eh,
                                ctx,
                                all_headers,
                                NULL)))
    return NULL;
 
  job->jcc = jcc;
  job->jcc_cls = jcc_cls;
  ctx->cb (ctx->cb_cls);
  return job;
}

References ctx, GNUNET_assert, job, setup_job(), and setup_job_headers().

Referenced by GNUNET_CURL_job_add(), and GNUNET_CURL_job_add_with_ct_json().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_CURL_job_add_raw()

struct GNUNET_CURL_Job * GNUNET_CURL_job_add_raw	(	struct GNUNET_CURL_Context *	ctx,
		CURL *	eh,
		const struct curl_slist *	job_headers,
		GNUNET_CURL_RawJobCompletionCallback	jcc,
		void *	jcc_cls
	)

Schedule a CURL request to be executed and call the given jcc upon its completion.

Note that the context will make use of the CURLOPT_PRIVATE facility of the CURL eh. Used to download resources that are NOT in JSON. The raw body will be returned.

Parameters

ctx	context to execute the job in
eh	curl easy handle for the request, will be executed AND cleaned up
job_headers	extra headers to add for this request
jcc	callback to invoke upon completion
jcc_cls	closure for jcc

Returns

NULL on error (in this case, eh is still released!)

Definition at line 608 of file curl.c.

{
  struct GNUNET_CURL_Job *job;
  struct curl_slist *all_headers;
 
  GNUNET_assert (NULL != jcc);
  all_headers = setup_job_headers (ctx,
                                   job_headers);
  if (NULL == (job = setup_job (eh,
                                ctx,
                                all_headers,
                                NULL)))
    return NULL;
  job->jcc_raw = jcc;
  job->jcc_raw_cls = jcc_cls;
  ctx->cb (ctx->cb_cls);
  return job;
}

References ctx, GNUNET_assert, job, setup_job(), and setup_job_headers().

Here is the call graph for this function:

GNUNET_CURL_extend_headers()

void GNUNET_CURL_extend_headers	(	struct GNUNET_CURL_Job *	job,
		const struct curl_slist *	extra_headers
	)

Add extra_headers to the HTTP headers for job.

Parameters

[in,out]	job	the job to modify
	extra_headers	headers to append

Definition at line 586 of file curl.c.

{
  struct curl_slist *all_headers = job->job_headers;
 
  for (const struct curl_slist *curr = extra_headers;
       NULL != curr;
       curr = curr->next)
  {
    GNUNET_assert (NULL !=
                   (all_headers = curl_slist_append (all_headers,
                                                     curr->data)));
  }
  job->job_headers = all_headers;
  GNUNET_break (CURLE_OK ==
                curl_easy_setopt (job->easy_handle,
                                  CURLOPT_HTTPHEADER,
                                  all_headers));
}

References GNUNET_assert, GNUNET_break, and job.

GNUNET_CURL_job_cancel()

void GNUNET_CURL_job_cancel

(

struct GNUNET_CURL_Job *

job

)

Cancel a job.

Must only be called before the job completion callback is called for the respective job.

Parameters

job	job to cancel

Definition at line 767 of file curl.c.

{
  struct GNUNET_CURL_Context *ctx = job->ctx;
 
  GNUNET_CONTAINER_DLL_remove (ctx->jobs_head,
                               ctx->jobs_tail,
                               job);
  GNUNET_break (CURLM_OK ==
                curl_multi_remove_handle (ctx->multi,
                                          job->easy_handle));
  curl_easy_cleanup (job->easy_handle);
  GNUNET_free (job->db.buf);
  curl_slist_free_all (job->job_headers);
  ctx->cb (ctx->cb_cls);
  GNUNET_free (job);
}

References ctx, GNUNET_break, GNUNET_CONTAINER_DLL_remove, GNUNET_free, and job.

Referenced by GNUNET_CURL_perform2().

Here is the caller graph for this function:

GNUNET_CURL_gnunet_rc_create()

struct GNUNET_CURL_RescheduleContext * GNUNET_CURL_gnunet_rc_create

(

struct GNUNET_CURL_Context *

ctx

)

Initialize reschedule context.

Parameters

ctx	context to manage

Returns

closure for GNUNET_CURL_gnunet_scheduler_reschedule().

Definition at line 87 of file curl_reschedule.c.

{
  struct GNUNET_CURL_RescheduleContext *rc;
 
  rc = GNUNET_new (struct GNUNET_CURL_RescheduleContext);
  rc->ctx = ctx;
  rc->parser = &GNUNET_CURL_download_get_result_;
  rc->cleaner = &clean_result;
  return rc;
}

References clean_result(), GNUNET_CURL_RescheduleContext::cleaner, ctx, GNUNET_CURL_RescheduleContext::ctx, GNUNET_CURL_download_get_result_(), GNUNET_new, and GNUNET_CURL_RescheduleContext::parser.

Here is the call graph for this function:

GNUNET_CURL_gnunet_rc_create_with_parser()

struct GNUNET_CURL_RescheduleContext * GNUNET_CURL_gnunet_rc_create_with_parser	(	struct GNUNET_CURL_Context *	ctx,
		GNUNET_CURL_RawParser	rp,
		GNUNET_CURL_ResponseCleaner	rc
	)

Initialize reschedule context; with custom response parser.

Parameters

ctx	context to manage

Returns

closure for GNUNET_CURL_gnunet_scheduler_reschedule().

Definition at line 59 of file curl_reschedule.c.

{
  struct GNUNET_CURL_RescheduleContext *rctx;
 
  rctx = GNUNET_new (struct GNUNET_CURL_RescheduleContext);
  rctx->ctx = ctx;
  rctx->parser = rp;
  rctx->cleaner = rc;
 
  return rctx;
}

References GNUNET_CURL_RescheduleContext::cleaner, ctx, GNUNET_CURL_RescheduleContext::ctx, GNUNET_new, GNUNET_CURL_RescheduleContext::parser, and rp.

GNUNET_CURL_gnunet_rc_destroy()

void GNUNET_CURL_gnunet_rc_destroy

(

struct GNUNET_CURL_RescheduleContext *

rc

)

Destroy reschedule context.

Parameters

rc	context to destroy

Definition at line 100 of file curl_reschedule.c.

{
  if (NULL != rc->task)
    GNUNET_SCHEDULER_cancel (rc->task);
  GNUNET_free (rc);
}

References GNUNET_free, GNUNET_SCHEDULER_cancel(), and GNUNET_CURL_RescheduleContext::task.

Here is the call graph for this function:

GNUNET_CURL_gnunet_scheduler_reschedule()

void GNUNET_CURL_gnunet_scheduler_reschedule

(

void *

cls

)

Implementation of the GNUNET_CURL_RescheduleCallback for GNUnet's scheduler.

Will run the CURL context using GNUnet's scheduler. Note that you MUST immediately destroy the reschedule context after calling GNUNET_CURL_fini().

Parameters

cls	must point to a struct GNUNET_CURL_RescheduleContext * (pointer to a pointer!)

Definition at line 166 of file curl_reschedule.c.

{
  struct GNUNET_CURL_RescheduleContext *rc = *(void **) cls;
 
  if (NULL != rc->task)
    GNUNET_SCHEDULER_cancel (rc->task);
  rc->task = GNUNET_SCHEDULER_add_now (&context_task,
                                       rc);
}

References context_task(), GNUNET_SCHEDULER_add_now(), GNUNET_SCHEDULER_cancel(), and GNUNET_CURL_RescheduleContext::task.

Here is the call graph for this function:

GNUNET_CURL_enable_async_scope_header()

void GNUNET_CURL_enable_async_scope_header	(	struct GNUNET_CURL_Context *	ctx,
		const char *	header_name
	)

Enable sending the async scope ID as a header.

Parameters

ctx	the context to enable this for
header_name	name of the header to send.

Definition at line 294 of file curl.c.

{
  ctx->async_scope_id_header = header_name;
}

References ctx.

GNUNET_CURL_is_valid_scope_id()

enum GNUNET_GenericReturnValue GNUNET_CURL_is_valid_scope_id

(

const char *

scope_id

)

Return GNUNET_YES if given a valid scope ID and GNUNET_NO otherwise.

See GNUNET_CURL_enable_async_scope_header() for the code that generates such a scope_id in an HTTP header.

Returns

GNUNET_YES iff given a valid scope ID

Definition at line 302 of file curl.c.

{
  if (strlen (scope_id) >= 64)
    return GNUNET_NO;
  for (size_t i = 0; i < strlen (scope_id); i++)
    if (! (isalnum (scope_id[i]) || (scope_id[i] == '-')))
      return GNUNET_NO;
  return GNUNET_YES;
}

References GNUNET_NO, and GNUNET_YES.