Porting Guide

Guide for porting the HTTP client library to a new platform.

To use the HTTP client library, a platform must implement the following components:

1. Configuration Macros
2. Transport Interface

Configuration Macros

Settings that can be set as macros in the config header core_http_config.h, or passed in as compiler options.

Note

If the custom configuration header core_http_config.h is not provided, then the HTTP_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.

See also

Configurations

The following macros can be configured for this library:

• HTTP_MAX_RESPONSE_HEADERS_SIZE_BYTES
• HTTP_USER_AGENT_VALUE
• HTTP_SEND_RETRY_TIMEOUT_MS
• HTTP_RECV_RETRY_TIMEOUT_MS

In addition, the following logging macros are used throughout this library:

• LogError
• LogWarn
• LogInfo
• LogDebug

Transport Interface

The HTTP client library relies on transport interface callbacks that must be implemented in order to send and receive packets on a network.

See also

The Transport Interface documentation for more information.

The transport interface API used by the HTTP client is defined in transport_interface.h. A port must implement functions corresponding to the following functions pointers:

• Transport Receive: A function to receive bytes from a network.

  int32_t (* TransportRecv_t )(
      NetworkContext_t * pNetworkContext, void * pBuffer, size_t bytesToRecv
  );

• Transport Send: A function to send bytes over a network.

  int32_t (* TransportSend_t )(
      NetworkContext_t * pNetworkContext, const void * pBuffer, size_t bytesToSend
  );

The above two functions take in a pointer to a NetworkContext_t, the type name of a struct NetworkContext. The NetworkContext struct must also be defined by the user's implementation, and ought to contain any information necessary to send and receive data with the TransportSend_t and TransportRecv_t implementations, respectively:

struct NetworkContext {
    // Fields necessary for the transport implementations, e.g. a TCP socket descriptor.
};

Time Function

The HTTP library optionally relies on a function to generate millisecond timestamps, for the purpose of calculating the elapsed time when no data has been sent or received.

See also

HTTPClient_GetCurrentTimeFunc_t

Applications can supply their platform-specific function capable of generating 32-bit timestamps of millisecond resolution. These timestamps need not correspond with any real world clock; the only requirement is that the difference between two timestamps must be an accurate representation of the duration between them, in milliseconds.

This function is used in conjunction with macros HTTP_SEND_RETRY_TIMEOUT_MS and HTTP_RECV_RETRY_TIMEOUT_MS.