ua_easy_run - quickly perform a transfer#

ORCAcode ua_easy_run(struct user_agent *ua, struct ua_info *info, struct ua_resp_handle *handle, struct ua_conn_attr *attr)#

Perform a blocking REST transfer.

Note

This is an easy, yet highly abstracted way of performing requests. If a higher control is necessary, users are better off using the functions of ua_conn_xxx() family.

Parameters:

  • ua – the User-Agent handle created with ua_init()

  • info – optional informational handle on how the request went

  • handle – the optional response callbacks, can be NULL

  • attr – connection attributes

  • body – the optional request body, can be NULL

  • method – the HTTP method of this transfer (GET, POST, …)

  • endpoint – the endpoint to be appended to the URL set at ua_set_url()

Returns:

ORCAcode for how the operation went, ORCA_OK means nothing out of the ordinary

Response handle#

typedef void (*ua_load_obj_cb)(char *str, size_t len, void *p_obj)#

Callback for object to be loaded by api response.

struct ua_resp_handle#

User callback to be called on request completion.

Public Members

ua_load_obj_cb ok_cb#

callback called when a successful transfer occurs

void *ok_obj#

the pointer to be passed to ok_cb

ua_load_obj_cb err_cb#

callback called when a failed transfer occurs

void *err_obj#

the pointer to be passed to err_cb

Example#

void done(char *body, size_t len, void *data)
{
  printf("Success! Receive a response body of %zu bytes!\n", len);
}

void fail(char *body, size_t len, void *data)
{
  printf("Failure! Receive a response body of %zu bytes!\n", len);
}

int main(void)
{
  struct user_agent *ua = ua_init(NULL);
  ua_set_url(ua, "https://www.example.com");

  struct ua_conn_attr conn_attr = { .method = HTTP_GET };
  struct ua_resp_handle handle = { .ok_cb = &done, .err_cb = &fail };

  ua_easy_run(ua, NULL, &handle, &conn_attr);

  ua_cleanup(ua);
}