HTTP

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Header

#include <inet/httpreq.h>

Functions

It is common for an application to need information beyond that stored on the computer itself. The simplest and most common way to share information is to store it on a Web Server and publish a URL that provides the desired content (Figure 1). This client/server scheme uses the HTTP/HTTPS protocol, which was originally designed to transmit HTML documents between Web servers and browsers. Due to the great impact it has had over the years, its use has been expanding for the exchange of structured information between any application that "understands" HTTP. The response from the server will typically be a block of text formatted in JSON or XML.

• Use http_dget to download a resource from its URL (Listing 1).

1 2 3 4 5 6 7 8 9

Stream *webpage = http_dget("https://nappgui.com/en/start/win_mac_linux.html", NULL, NULL); Stream *imgdata = http_dget("http://test.nappgui.com/image_formats/sea_02_rgb.png", NULL, NULL); Image *image = image_read(imgdata); if (webpage != NULL) { ... stm_close(&webpage); }

1. HTTP sessions

• Use http_create to create an HTTP session.
• Use http_secure to create an HTTPS (encrypted) session.
• Use http_add_header to add a header to the request.
• Use http_get to make a GET request.
• Use http_post to make a POST request.

If we are going to make successive calls to the same server or if we need greater control over the HTTP headers, we must create a session (Listing 2). On the same session, we can make different requests using the typical HTTP "verbs": GET, POST, PUT, PATCH, DELETE. In addition to the body (or payload) of the HTTP request, a series of headers are sent that include additional information for the server. By default, the typical headers expected by most servers are included, but it is possible to include additional headers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Stream *webpage = NULL;

const byte_t *body = ...
uint32_t size = ...
Http *http = http_secure("myserver.com", UINT16_MAX);
http_add_header(http, "MyHeader", "CustomValue");
if (http_post(http, "/en/start/win_mac_linux.html", body, size, NULL) == TRUE)
{
    if (http_response_status(http) == 200)
    {
        webpage = stm_memory(1024);
        if (http_response_body(http, webpage, NULL) == FALSE)
            stm_close(&webpage);
    }
}

http_destroy(&http);

if (webpage != NULL)
{
    ...
    stm_close(&webpage);
}

2. HTTP response

• Use http_response_status to get the response code.
• Use http_response_body to get the response body.
• Use http_response_header to get the value of a response header.

The response that the server sends after a call to http_get has a format similar to that of the request:

• Status code: 200, 400, 500, etc.
• Response body: Block of bytes.
• Response headers: Key/value pairs with additional information.

3. HTTP Cookies

• Use http_cookies_policy to set the session cookie policy.
• Use http_cookies_reload to reload the session cookies.
• Use http_cookie_search to get the value of a cookie.
• Use http_cookie_delete to delete a cookie.

HTTP cookies are small pieces of information that a web server sends to the client (usually the Web browser) to store data and maintain state between requests. In summary, work like this (Figure 2):

• The server sends a cookie using the Set-Cookie HTTP header in the response.
• The client saves the cookie in its local storage according to the domain and path rules.
• Every time the client makes a new HTTP request to the same domain and route, it automatically sends the corresponding cookies in the Cookie header.

By default, cookie management is done automatically and transparently for the application using the ekCOOKIES_ALL policy. If necessary, we have methods to read and delete cookies associated with a session. If we want greater control over the management, storage and sending of cookies to the server, we can disable automatic management using the ekCOOKIES_OFF policy, leaving the processing of the Set-Cookie and Cookie headers in the hands of the application itself.

http_create ()

Create an HTTP session.

Http*
http_create(const char_t *host,
            const uint16_t port);

Return

HTTP session.

Remarks

See HTTP sessions.

http_secure ()

Create an HTTPS session.

Http*
http_secure(const char_t *host,
            const uint16_t port);

Return

HTTPS session.

Remarks

See HTTP sessions.

http_destroy ()

Destroys an HTTP session.

void
http_destroy(Http **http);

http_clear_headers ()

Removes previously assigned HTTP headers.

void
http_clear_headers(Http *http);

Remarks

See HTTP sessions.

http_add_header ()

Add a header to the HTTP request.

void
http_add_header(Http *http,
                const char_t *name,
                const char_t *value);

Remarks

See HTTP sessions.

http_cookies_policy ()

Change the cookie policy.

void
http_cookies_policy(Http *http,
                    const cookies_t cookies);

Remarks

The set policy will be applied in future calls to http_get or similar. By default ekCOOKIES_ALL is applied. See HTTP Cookies.

http_cookies_reload ()

Reload the cookie cache.

void
http_cookies_reload(Http *http);

Remarks

We must call this function before accessing the content of the cookies. In ekCOOKIES_OFF policies the cache will always be empty. See HTTP Cookies.

http_cookies_size ()

Returns the number of cookies associated with this session.

uint32_t
http_cookies_size(const Http *http);

Return

The number of cookies.

Remarks

Call before http_cookies_reload. See HTTP Cookies.

http_cookie_name ()

Returns the name of a cookie associated with this session.

const char_t*
http_cookie_name(const Http *http,
                 const uint32_t index);

Return

Cookie name.

Remarks

Call before http_cookies_reload. See HTTP Cookies.

http_cookie_value ()

Returns the value of a cookie associated with this session.

const char_t*
http_cookie_value(const Http *http,
                  const uint32_t index);

Return

Cookie value.

Remarks

Call before http_cookies_reload. See HTTP Cookies.

http_cookie_search ()

Returns the value of a cookie, given its name.

const char_t*
http_cookie_search(const Http *http,
                   const char_t *name);

Return

Cookie value or empty string if the cookie does not exist.

Remarks

Call before http_cookies_reload. See HTTP Cookies.

http_cookie_delete ()

Delete a cookie associated with this session.

void
http_cookie_delete(Http *http,
                   const char_t *name);

Remarks

See HTTP Cookies.

http_cookie_delete_all ()

Delete all cookies associated with this session.

void
http_cookie_delete_all(Http *http);

Remarks

See HTTP Cookies.

http_get ()

Make a GET type request.

bool_t
http_get(Http *http,
         const char_t *path,
         const byte_t *data,
         const uint32_t size,
         ierror_t *error);

Return

TRUE if the request has been carried out correctly. If FALSE, in error we will have the cause.

Remarks

The request is synchronous, that is, the program will be stopped until the server responds. If we want an asynchronous model we must create a parallel thread that manages the request. HTTP redirects are resolved automatically. See HTTP sessions.

http_post ()

Make a POST type request.

bool_t
http_post(Http *http,
          const char_t *path,
          const byte_t *data,
          const uint32_t size,
          ierror_t *error);

Return

TRUE if the request has been carried out correctly. If FALSE, in error we will have the cause.

Remarks

See http_get.

http_put ()

Make a PUT type request.

bool_t
http_put(Http *http,
         const char_t *path,
         const byte_t *data,
         const uint32_t size,
         ierror_t *error);

Return

TRUE if the request has been carried out correctly. If FALSE, in error we will have the cause.

Remarks

See http_get.

http_patch ()

Make a PATCH type request.

bool_t
http_patch(Http *http,
           const char_t *path,
           const byte_t *data,
           const uint32_t size,
           ierror_t *error);

Return

TRUE if the request has been carried out correctly. If FALSE, in error we will have the cause.

Remarks

See http_get.

http_delete ()

Make a DELETE type request.

bool_t
http_delete(Http *http,
            const char_t *path,
            const byte_t *data,
            const uint32_t size,
            ierror_t *error);

Return

TRUE if the request has been carried out correctly. If FALSE, in error we will have the cause.

Remarks

See http_get.

http_response_status ()

Returns the response code of an HTTP request.

uint32_t
http_response_status(const Http *http);

Return

The server response code.

Remarks

See HTTP response.

http_response_protocol ()

Returns the protocol used by the HTTP server.

const char_t*
http_response_protocol(const Http *http);

Return

The server protocol.

Remarks

See HTTP response.

http_response_message ()

Returns the response message from the HTTP server.

const char_t*
http_response_message(const Http *http);

Return

The server's response message.

Remarks

See HTTP response.

http_response_size ()

Returns the number of response headers for an HTTP request.

uint32_t
http_response_size(const Http *http);

Return

The number of headers.

Remarks

See HTTP response.

http_response_name ()

Returns the name of the response header of an HTTP request.

const char_t*
http_response_name(const Http *http,
                   const uint32_t index);

Return

The name of the header.

Remarks

See HTTP response.

http_response_value ()

Returns the value of the response header of an HTTP request.

const char_t*
http_response_value(const Http *http,
                    const uint32_t index);

Return

The value of the header.

Remarks

See HTTP response.

http_response_header ()

Returns the value of a response header from an HTTP request.

const char_t*
http_response_header(const Http *http,
                     const char_t *name);

Return

The value of the header. If the header does not exist, it will return an empty string "".

Remarks

See HTTP response.

http_response_body ()

Returns the response body of an HTTP request.

bool_t
http_response_body(const Http *http,
                   Stream *body,
                   ierror_t *error);

Return

TRUE if it could be read correctly. If FALSE, in error we will have the cause.

Remarks

See HTTP response.

http_dget ()

Make a direct request for a Web resource.

Stream*
http_dget(const char_t *url,
          uint32_t *result,
          ierror_t *error);

1
2
3
4
5
6

Stream *json = http_dget("http://serv.nappgui.com:80/dproducts.php", NULL, NULL);
if (json)
{
    ...
    stm_close(&json);
}

Return

Stream with the result of the request.

Remarks

Use this function for direct access to an isolated resource. If you need to make multiple requests or configure headers, use http_create or http_secure.

http_exists ()

Checks if a Web resource is available/accessible.

bool_t
http_exists(const char_t *url);

Return

TRUE if the resource (Web page, file, etc.) is accessible.

Remarks

HTTP redirects are not resolved. Will return FALSE if the URL as is is not valid.