HTTP

Cabecera

#include <inet/httpreq.h>

Funciones

Es habitual que una aplicación necesite información más allá de la almacenada en el propio computador. La forma más sencilla y habitual de compartir información es almacenarla en un Servidor Web y publicar una URL que provea el contenido deseado (Figura 1). Este esquema cliente/servidor utiliza el protocolo HTTP/HTTPS, que fue originalmente diseñado para transmitir documentos HTML entre servidores Web y navegadores. Debido a la gran repercusión que ha tenido a lo largo de los años, se ha ido ampliando su uso para el intercambio de información estructurada entre cualquier aplicación que "entienda" HTTP. La respuesta del servidor será, por lo general, un bloque de texto formateado en JSON o XML.

• Utiliza http_dget para descargar un recurso a partir de su URL (Listado 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. Sesiones HTTP

• Utiliza http_create para crear una sesión HTTP.
• Utiliza http_secure para crear una sesión HTTPS (encriptado).
• Utiliza http_add_header para añadir una cabecera a la petición.
• Utiliza http_get para realizar una petición GET.
• Utiliza http_post para realizar una petición POST.

Si vamos a realizar sucesivas llamadas a un mismo servidor o si necesitamos mayor control sobre las cabeceras HTTP, deberemos crear una sesión (Listado 2). Sobre la misma sesión, podremos realizar diferentes peticiones utilizando los "verbos" típicos HTTP: GET, POST, PUT, PATCH, DELETE. Además del cuerpo (o payload) de la petición HTTP, se envían una serie de cabeceras donde se incluye información adicional para el servidor. Por defecto se incluyen las cabeceras típicas esperadas por la mayoría de servidores, pero es posible incluir cabeceras adicionales.

 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. Respuesta HTTP

• Utiliza http_response_status para obtener el código de respuesta.
• Utiliza http_response_body para obtener el cuerpo de la respuesta.
• Utiliza http_response_header para obtener el valor de una cabecera de respuesta.

La respuesta que el servidor envía tras una llamada a http_get tiene un formato similar al de la petición:

• Código de estado: 200, 400, 500, etc.
• Cuerpo de la respuesta: Bloque de bytes.
• Cabeceras de respuesta: Pares clave/valor con información adicional.

3. Cookies HTTP

• Utiliza http_cookies_policy para establecer la política de cookies de la sesión.
• Utiliza http_cookies_reload para recargar las cookies de la sesión.
• Utiliza http_cookie_search para obtener el valor de una cookie.
• Utiliza http_cookie_delete para eliminar una cookie.

Las HTTP cookies son pequeños fragmentos de información que un servidor web envía al cliente (normalmente el navegador Web) para almacenar datos y mantener el estado entre solicitudes. De forma resumida funcionan así (Figura 2):

• El servidor envía una cookie usando el encabezado HTTP Set-Cookie en la respuesta.
• El client guarda la cookie en su almacenamiento local según las reglas de dominio y ruta.
• Cada vez que el cliente hace una nueva solicitud HTTP al mismo dominio y ruta, envía automáticamente las cookies correspondientes en el encabezado Cookie.

Por defecto, la gestión de cookies se realiza de forma automática y transparente para la aplicación mediante la política ekCOOKIES_ALL. Si fuera necesario, disponemos de métodos para leer y eliminar las cookies asociadas a una sesión. Si queremos mayor control sobre la gestión, almacenamiento y envío de cookies al servidor, podremos deshabilitar la gestión automática mediante la política ekCOOKIES_OFF, dejando en manos de la propia aplicación el procesamiento de las cabeceras Set-Cookie y Cookie.

http_create ()

Crea una sesión HTTP.

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

Retorna

Sesión HTTP.

Observaciones

Ver Sesiones HTTP.

http_secure ()

Crea una sesión HTTPS.

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

Retorna

Sesión HTTPS.

Observaciones

Ver Sesiones HTTP.

http_destroy ()

Destruye una sesión HTTP.

void
http_destroy(Http **http);

http_clear_headers ()

Elimina las cabeceras HTTP previamente asignadas.

void
http_clear_headers(Http *http);

Observaciones

Ver Sesiones HTTP.

http_add_header ()

Añade una cabecera a la petición HTTP.

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

Observaciones

Ver Sesiones HTTP.

http_cookies_policy ()

Cambia la política de cookies.

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

Observaciones

La política establecida se aplicará en las próximas llamadas a http_get o similares. Por defecto se aplica ekCOOKIES_ALL. Ver Cookies HTTP.

http_cookies_reload ()

Recarga la caché de cookies.

void
http_cookies_reload(Http *http);

Observaciones

Deberemos llamar a esta función antes de acceder al contenido de las cookies. En políticas ekCOOKIES_OFF la caché siempre estará vacía. Ver Cookies HTTP.

http_cookies_size ()

Retorna el número de cookies asociadas a esta sesión.

uint32_t
http_cookies_size(const Http *http);

Retorna

El número de cookies.

Observaciones

Llamar antes a http_cookies_reload. Ver Cookies HTTP.

http_cookie_name ()

Retorna el nombre de una cookie asociada a esta sesión.

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

Retorna

Nombre de la cookie.

Observaciones

Llamar antes a http_cookies_reload. Ver Cookies HTTP.

http_cookie_value ()

Retorna el valor de una cookie asociada a esta sesión.

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

Retorna

Valor de la cookie.

Observaciones

Llamar antes a http_cookies_reload. Ver Cookies HTTP.

http_cookie_search ()

Retorna el valor de una cookie, dado su nombre.

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

Retorna

Valor de la cookie o cadena vacía si la cookie no existe.

Observaciones

Llamar antes a http_cookies_reload. Ver Cookies HTTP.

http_cookie_delete ()

Elimina una cookie asociada a esta sesión.

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

Observaciones

Ver Cookies HTTP.

http_cookie_delete_all ()

Elimina todas las cookie asociadas a esta sesión.

void
http_cookie_delete_all(Http *http);

Observaciones

Ver Cookies HTTP.

http_get ()

Realiza una petición tipo GET.

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

Retorna

TRUE si la petición se ha llevado a cabo correctamente. Si FALSE, en error tendremos la causa.

Observaciones

La petición es síncrona, es decir, el programa quedará detenido hasta que el servidor responda. Si queremos un modelo asíncrono deberemos crear un hilo paralelo que gestione la petición. Las redirecciones HTTP se resuelven automáticamente. Ver Sesiones HTTP.

http_post ()

Realiza una petición tipo POST.

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

Retorna

TRUE si la petición se ha llevado a cabo correctamente. Si FALSE, en error tendremos la causa.

Observaciones

Ver http_get.

http_put ()

Realiza una petición tipo PUT.

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

Retorna

TRUE si la petición se ha llevado a cabo correctamente. Si FALSE, en error tendremos la causa.

Observaciones

Ver http_get.

http_patch ()

Realiza una petición tipo PATCH.

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

Retorna

TRUE si la petición se ha llevado a cabo correctamente. Si FALSE, en error tendremos la causa.

Observaciones

Ver http_get.

http_delete ()

Realiza una petición tipo DELETE.

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

Retorna

TRUE si la petición se ha llevado a cabo correctamente. Si FALSE, en error tendremos la causa.

Observaciones

Ver http_get.

http_response_status ()

Devuelve el código de respuesta de una petición HTTP.

uint32_t
http_response_status(const Http *http);

Retorna

El código de respuesta del servidor.

Observaciones

Ver Respuesta HTTP.

http_response_protocol ()

Devuelve el protocolo utilizado por el servidor HTTP.

const char_t*
http_response_protocol(const Http *http);

Retorna

El protocolo del servidor.

Observaciones

Ver Respuesta HTTP.

http_response_message ()

Devuelve el mensaje de respuesta del servidor HTTP.

const char_t*
http_response_message(const Http *http);

Retorna

El mensaje de respuesta del servidor.

Observaciones

Ver Respuesta HTTP.

http_response_size ()

Devuelve el número de cabeceras de respuesta de una petición HTTP.

uint32_t
http_response_size(const Http *http);

Retorna

El número de cabeceras.

Observaciones

Ver Respuesta HTTP.

http_response_name ()

Devuelve el nombre de la cabecera de respuesta de una petición HTTP.

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

Retorna

El nombre de la cabecera.

Observaciones

Ver Respuesta HTTP.

http_response_value ()

Devuelve el valor de la cabecera de respuesta de una petición HTTP.

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

Retorna

El valor de la cabecera.

Observaciones

Ver Respuesta HTTP.

http_response_header ()

Devuelve el valor de una cabecera de respuesta de una petición HTTP.

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

Retorna

El valor de la cabecera. Si la cabecera no existe, devolverá una cadena vacía "".

Observaciones

Ver Respuesta HTTP.

http_response_body ()

Devuelve el cuerpo de la respuesta de una petición HTTP.

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

Retorna

TRUE si se ha podido leer correctamente. Si FALSE, en error tendremos la causa.

Observaciones

Ver Respuesta HTTP.

http_dget ()

Realiza una petición directa de un recurso Web.

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);
}

Retorna

Stream con el resultado de la petición.

Observaciones

Utiliza esta función para el acceso directo a un recurso aislado. Si necesitas realizar varias peticiones o configurar las cabeceras, utiliza http_create o http_secure.

http_exists ()

Chequea si un recurso Web está disponible/accesible.

bool_t
http_exists(const char_t *url);

Retorna

TRUE si el recurso (página Web, archivo, etc) está accesible.

Observaciones

No se resuelven las redirecciones HTTP. Retornará FALSE si la URL tal cual no es válida.