HTTP Functions

All of the functions described below return a 32-bit integer that is one of the values from the standard Microvisor enumeration MvStatus. All possible error values for a given system call are provided with each function's description.

Success is always signaled by a return value of zero (MV_STATUS_OKAY).

Issue an HTTP request via a channel

This call, if successful, may subsequently yield any of the following notifications.

The application makes use of channels of type MV_CHANNELTYPE_HTTP to issue HTTP requests to remote servers. The channel must be open for the request to be issued and of the correct type.

For each channel, only one request can be issued. If Microvisor returns MV_STATUS_PARAMETERFAULT, MV_STATUS_INVALIDHANDLE, MV_STATUS_INVALIDBUFFERSIZE or MV_STATUS_CHANNELCLOSED, then the request will not have been issued, and you can reconfigure the request and try again. Any other value indicates that the request has been sent, and any attempt to issue it again, or to use the channel for a fresh request, will result in MV_STATUS_REQUESTALREADYSENT being returned. Instead, send any subsequent HTTP request through a new channel. You can re-use the channel definition structure and buffers if you wish. Be sure to close the channel used for a given HTTP request once you have received the response or a failure notification.

The type of HTTP request is specified as the scheme prefix of the target URL. Only HTTPS — i.e., https:// — is supported. If your URL is prefixed http://, or some other scheme, the request will be rejected: the device will receive an MvHttpResponseData record with its result field equal to MV_HTTPRESULT_UNSUPPORTED_URI_SCHEME. Please see mvReadHttpResponseData() for details of the MvHttpResponseData structure.

The call's request parameter takes a pointer to a MvHttpRequest structure:

1
struct MvHttpRequest {
2
  struct MvSizedString method;
3
  struct MvSizedString url;
4
  uint32_t num_headers;
5
  const struct MvHttpHeader *headers;
6
  struct MvSizedString body;
7
  uint32_t timeout_ms;
8
};

This structure's properties are:

• method — A data structure comprising the request HTTP method, i.e., GET, HEAD, POST, PUT, DELETE, PATCH or OPTIONS, as bytes and the number of bytes.
• url — A data structure comprising the target URL as bytes and the number of bytes. Only https:// is supported as a prefix.
• num_headers — The number of headers included in the headers array.
• headers — A pointer to an array of one or more MvHttpHeader structures.
• body — A data structure comprising the request body content as bytes and the number of bytes. Include an empty string if there is no body content.
• timeout_ms — The request timeout in milliseconds. Microvisor supports timeouts from 5000ms to 10000ms.

Each entry in the headers array, if any, is a pointer to an MvHttpHeader structure:

1
struct MvHttpHeader {
2
  const uint8_t *data;
3
  uint32_t length;
4
};

This structure's properties are:

• data — A pointer to the header content. Do not terminate the header with <CR><LF>.
• length — The number of bytes in data.

Microvisor automatically adds a Host: header for you. It also inserts a Content-Length: header based on the size of any data you include. Again, you do not need to add this yourself, and if you do include one, it will be overwritten by Microvisor.

The maximum number of headers you may attach is 32. An MV_STATUS_TOOMANYELEMENTS is issued for higher values.

This snippet from our sample HTTP code shows how we use mvSendHttpRequest() to issue an HTTP request via the Microvisor cloud. The calls takes an MvHttpRequest struct which defines the request. The function server_log() is not included here, but can be viewed in the sample HTTP code.

1
// Set up the request
2
unit32_t item_number = 1;
3
const char verb[] = "GET";
4
const char body[] = "";
5
char uri[46] = "";
6
sprintf(uri, "https://jsonplaceholder.typicode.com/todos/%u", item_number);
7
struct MvHttpHeader hdrs[] = {};
8
struct MvHttpRequest request_config = {
9
  .method = {
10
    .data = (uint8_t *)verb,
11
    .length = strlen(verb)
12
  },
13
  .url = {
14
    .data = (uint8_t *)uri,
15
    .length = strlen(uri)
16
  },
17
  .num_headers = 0,
18
  .headers = hdrs,
19
  .body = {
20
    .data = (uint8_t *)body,
21
    .length = strlen(body)
22
  },
23
  .timeout_ms = 10000
24
};
25

26
// Issue the request -- and check its status
27
enum MvStatus status = mvSendHttpRequest(http_handles.channel, &request_config);
28
if (status == MV_STATUS_OKAY) {
29
  server_log("Request sent to the Microvisor cloud");
30
  return true;
31
}

Read the status of an HTTP response

Your application should call mvReadHttpResponseData() when the HTTP channel receives a notification of type MV_EVENTTYPE_CHANNELDATAREADABLE. Microvisor will write an MvHttpResponseData record which your code can then parse:

1
struct MvHttpResponseData {
2
  enum MvHttpResult result;
3
  uint32_t status_code;
4
  uint32_t num_headers;
5
  uint32_t body_length;
6
};

This structure's properties are:

• result — A value indicating the outcome of the request operation.
• status_code — The standard HTTP status code returned.
• num_headers — The number of headers in the response.
• body_length — The length of the response body in bytes.

The value written to the record's result field will be one of the following:

This snippet from our sample HTTP code shows how we use mvReadHttpResponseData() to access the response to a previously issued HTTP request. The functions server_log() and server_error() are not included here, but can be viewed in the sample HTTP code.

1
static struct MvHttpResponseData resp_data;
2
enum MvStatus status = mvReadHttpResponseData(http_handles.channel, &resp_data);
3
if (status == MV_STATUS_OKAY) {
4
  // Check we successfully issued the request (`result` is OK) and
5
  // the request was successful (status code 200)
6
  if (resp_data.result == MV_HTTPRESULT_OK) {
7
    if (resp_data.status_code == 200) {
8
      server_log("HTTP response header count: %lu", resp_data.num_headers);
9
      server_log("HTTP response body length: %lu", resp_data.body_length);
10
    } else {
11
      server_error("HTTP status code: %lu", resp_data.status_code);
12
    }
13
  } else {
14
    server_error("Request failed. Status: %i", resp_data.result);;
15
  }
16
} else {
17
  server_error("Response data read failed. Status: %i", status);
18
}

Read header data from an HTTP response

Your call to mvReadHttpResponseData() will indicate the number of headers, if any, included in the response. To read one of these headers, call this function and pass in a header_index value indicating the desired header's position in the sequence of headers. Microvisor will write the header into the buffer you specify in the call.

The following function demonstrates how you can use mvReadHttpResponseHeader() to extract one or more headers from the response to a previously issued HTTP request and log them. The functions server_log() and server_error() are not included here, but can be viewed in our sample HTTP code.

1
/**
2
 * @brief Output all received headers.
3
 *
4
 * @param n: The number of headers to list.
5
 */
6
void output_headers(uint32_t n) {
7
  if (n > 0) {
8
    uint8_t buffer[2048];
9
    for (uint32_t i = 0 ; i < n ; ++i) {
10
      memset((void *)buffer, 0x00, 256);
11
      enum MvStatus status = mvReadHttpResponseHeader(http_handles.channel, i, buffer, 2048);
12
      if (status == MV_STATUS_OKAY) {
13
        server_log("%lu. %s", i + 1, buffer);
14
      } else {
15
        server_error("Could not read header %lu", i + 1);
16
      }
17
    }
18
  }
19
}

Read body data from an HTTP response

Your call to mvReadHttpResponseData() will indicate the length of the response's body, if any. To read all or part of the body data, call this function.

To read just a portion of the body, set a non-zero value of offset as the start byte and/or specify a buffer size below that of the response body's length. Microvisor will read from the response body from the byte at offset up to the end of the target buffer.

This snippet from our sample HTTP code shows how we use mvReadHttpResponseBody() to access the body data within the response to a previously issued HTTP request. See the mvReadHttpResponseData() example for the code that wraps this stanza. The functions server_log() and server_error() are not included here, but can be viewed in the sample HTTP code.

1
// Set up a buffer that we'll get Microvisor to write
2
// the response body into
3
uint8_t buffer[resp_data.body_length + 1];
4
memset((void *)buffer, 0x00, resp_data.body_length + 1);
5
status = mvReadHttpResponseBody(http_handles.channel, 0, buffer, resp_data.body_length);
6
if (status == MV_STATUS_OKAY) {
7
  // Retrieved the body data successfully so log it
8
  server_log("Message JSON:\n%s", buffer);
9
} else {
10
  server_error("HTTP response body read status %i", status);
11
}