Structure and Methods

Setup

To use the HTTP client in an XDK application, its header file has to be included in the source file as follows.

// includes all functions neccessary for the HTTP Client
#include "Serval_HttpClient.h"

Before using the module for the first time, it also needs to be initialized by calling the following function.

// loads all require dmodules for the HTTP Client
HttpClient_initialize();

GET

The next code show how to send a GET request for the resource “23.22.14.18:80/ip”

// Insert this code after HttpClient_initialize() and Network Setup
Ip_Address_T destAddr;
Ip_convertOctetsToAddr(23, 22, 14, 18, &destAddr);
Ip_Port_T port = Ip_convertIntToPort(80);

Msg_T* msg_ptr;
HttpClient_initRequest(&destAddr, port, &msg_ptr);
HttpMsg_setReqMethod(msg_ptr, Http_Method_Get);
HttpMsg_setReqUrl(msg_ptr, "/ip");

// send the request
static Callable_T sentCallable;
Callable_assign(&sentCallable, &onHTTPRequestSent);
HttpClient_pushRequest(msg_ptr, &sentCallable, &onHTTPResponseReceived)

The central object here is the struct Msg_T. It contains all the information required to create HTTP request. The struct is created using HttpClient_initRequest(). Parameters are the address and port of the server that should receive the request. This call will trigger an assertion if no network connections is available.

HttpMsg_setReqMethod() is used to set the HTTP method of the request, in this case Http_Method_Get.

The last piece of information that needs to be set is the resource that we want to request. This can be done with the function HttpMsg_setReqUrl() that takes a simple c string as its argument.

An operation that is executed synchronously will block its thread until the operation is finished. However, this is an undesired behaviour in a real-time environment like the XDK. The other option is to perform an operation asynchronously, using callback functions that are called when the operation finished. This way, execution can continue immediately after initiating the operation.

The HttpClient_pushRequest() function, that is used to send a the HTTP request, takes two callback functions:

The first function (second parameter) is called when the request was successfully sent, or if an error occurred that prevented the system from sending the request.

The second function (third parameter) is called when the system received a response.

The following two code snippets provide sample implementations of both required callback functions. The first function simply validates the status code and prints an error message if something went wrong.

static retcode_t onHTTPRequestSent(Callable_T *callfunc, retcode_t status)
{
  (void) (callfunc);
  if (status != RC_OK) {
    printf("Failed to send HTTP request!\r\n");
  }
  return(RC_OK);
}

If no error occured and a response was received, the following function will print the response’s status code, content type and payload to the XDK Workbench console.

static retcode_t onHTTPResponseReceived(HttpSession_T *httpSession,
Msg_T *msg_ptr, retcode_t status)
{
  (void) (httpSession);

  if (status == RC_OK && msg_ptr != NULL) {
    Http_StatusCode_T statusCode = HttpMsg_getStatusCode(msg_ptr);
    char const *contentType = HttpMsg_getContentType(msg_ptr);

    char const *content_ptr;
    unsigned int contentLength = 0;
    HttpMsg_getContent(msg_ptr, &content_ptr, &contentLength);
    char content[contentLength+1];
    strncpy(content, content_ptr, contentLength);
    content[contentLength] = 0;

    printf("HTTP RESPONSE: %d [%s]\r\n", statusCode, contentType);
    printf("%s\r\n", content);
  } else {
    printf("Failed to receive HTTP response!\r\n");
  }
  return(RC_OK);
}

The Msg_T parameter that is passed to the response callback function is the same struct that was initially passed to the HttpClient_pushReques() function, only now containing the HTTP response data as well. The individual parts of the received response can be extracted using the functions HttpMsg_getStatusCode(), HttpMsg_getContentType()and HttpMsg_getContent(), with a pointer to the struct as argument. Since the response payload (if existing) is stored as a plain byte buffer in memory, HttpMsg_getContent() cannot simply return a reference to this buffer, but has to provide its length too. This is done using additional out parameters.

POST

The following code will create and send a POST request to “23.22.14.18:80/post”.

// Insert this after HttpClient_initialize() and Network Setup
// assemble the request message
Ip_Address_T destAddr;
Ip_convertOctetsToAddr(23, 22, 14, 18, &destAddr);
Ip_Port_T port = Ip_convertIntToPort(80);

Msg_T* msg_ptr;
HttpClient_initRequest(&destAddr, port, &msg_ptr);
HttpMsg_setReqMethod(msg_ptr, Http_Method_Post);
HttpMsg_setReqUrl(msg_ptr, "/post");

Msg_prependPartFactory(msg_ptr, &writeNextPartToBuffer);

// send the request
static Callable_T sentCallable;
Callable_assign(&sentCallable, &onHTTPRequestSent);
HttpClient_pushRequest(msg_ptr, &sentCallable, &onHTTPResponseReceived);

The code for the POST request looks very similar to the code for a GET request. There are only two differences:

• The method is set to Http_Method_Post

• Msg_prependPartFactory() is used to pass a function pointer in the Msg_T struct.

  The HTTP API uses chunked transfer encoding for POST requests. The HTTP stack sends a new chunk whenever data is available. The pointer that is passed here to the message struct is a pointer to a functions that generates exactly these chunks. This function is called a part factory. It sequentially writes the payload into a handover buffer which then gets encoded and transferred to the server.

Set Host Header

The Host header is used to differentiate between multiple domains that run on a common IP. In this way, a single web server can receive requests that are addressed to different domains, and forward them to the corresponding virtual servers for processing.

The following code will set the host-header, using the Http API.

HttpMsg_setHost(msg_ptr,"your.host.address");

This can be directly copied to your sending-implementation and has to be called before HttpClient_pushRequest() and after HttpClient_initRequest().