HTTP Client

Providing a custom HTTP implementation for the Vertices SDK

Our header, your implementation

We provide functions signatures in vertices_http.h .

The SDK will call those functions when needed.

Client Init/DeInit

The http_init function is called on Vertices SDK initialization.

/// Init HTTP client
/// \param provider Remote API URL, port, specific header and certificate if needed by the client
/// \param response_payload_cb Function callback to call when data is ready to be parsed
/// \return \c VTC_SUCCESS on success, otherwise error depends on implementation
ret_code_t
http_init(const provider_info_t *provider,
          size_t (*response_payload_cb)(char *chunk,
                                        size_t chunk_size));

/// Close/deinit the client
void
http_close(void);

The init function is simple: all you have to do is to init the HTTP client using the parameters. The URL, port, specific headers, and certificates are passed with the provider parameter.

The callback function reponse_payload_cb must be kept locally as we will need to call it whenever a response is received after a GET or a POST method call.

The callback

The callback function will be called whenever an HTTP response body is ready to be parsed: a pointer to the received bytes chunk and the size chunk_size will be provided to the Vertices SDK when calling the callback. The buffer can be a pointer allocated by the underlying HTTP client.

GET/POST methods

/// HTTP GET request
/// \param provider pointer to provider (url, port..)
/// \param relative_path path to append to the provider base URL
/// \param headers Headers string, each one must have the format "key:value\n\r"
/// \param response_code HTTP response code
/// \return error codes:
/// - \c VTC_SUCCESS on success
/// - \c VTC_ERROR_OFFLINE if offline
/// - \c VTC_HTTP_ERROR on HTTP error: check response_code.
ret_code_t
http_get(const provider_info_t *provider,
         const char *relative_path,
         const char *headers,
         uint32_t *response_code);

/// HTTP POST request
/// \param provider pointer to provider (url, port..)
/// \param relative_path path to append to the provider base URL
/// \param headers Headers string, each one must have the format "key:value\n\r"
/// \param body HTTP body
/// \param body_size size of \c body array
/// \param response_code HTTP response code
/// \return error codes:
/// - \c VTC_SUCCESS on success
/// - \c VTC_ERROR_OFFLINE if offline
/// - \c VTC_HTTP_ERROR on HTTP error: check response_code.
ret_code_t
http_post(const provider_info_t *provider,
          const char *relative_path,
          char *headers,
          const char *body,
          size_t body_size,
          uint32_t *response_code);

Some important information to keep in mind:

• The full URL is a concatenation of provider->url and relative_path.

• Headers are key-value pairs separated by \r , \n or both. The format of the key-value pair is as follow key:value\n\r.

• If the HTTP call fails, the HTTP response code must be set in response_code and the function must respond VTC_HTTP_ERROR.

• Once the full response is ready to be parsed, you will need to call the callback stored during the initialization of the module with a pointer to the raw buffer and its size: response_payload_cb(response_data, response_length);

Now that we are able to receive and send data using a configured provider, we are going to build transactions that will soon be sent on the blockchain. To do so, we will need to handle events.

Here is the link to our (partial) implementation of the above step.

For full implementation, you can take a look at our example for Unix and the ESP32, both using different HTTP clients 😉