thistle-sdk
Thistle SDK documentation
Loading...
Searching...
No Matches
tsc.h File Reference
#include <stdint.h>

Go to the source code of this file.

Typedefs

typedef enum tsc_result tsc_result
 
typedef struct tsc_http_request tsc_http_request
 
typedef struct tsc_http_response tsc_http_response
 
typedef struct tsc_http_session tsc_http_session
 

Enumerations

enum  tsc_result {
  TSC_RESULT_OK = 1000 ,
  TSC_RESULT_INVALID_URL = 1001 ,
  TSC_RESULT_UTF8_VALIDATION_FAILURE = 1002 ,
  TSC_RESULT_TOO_MANY_REDIRECTS = 1003 ,
  TSC_RESULT_TIMED_OUT = 1004 ,
  TSC_RESULT_RESPONSE_ERROR = 1005 ,
  TSC_RESULT_UNEXPECTED_ERROR = 1006 ,
  TSC_RESULT_DNS_LOOKUP_FAILURE = 1007 ,
  TSC_RESULT_CONNECTION_FAILED = 1008 ,
  TSC_RESULT_CONNECTION_ABORTED = 1009 ,
  TSC_RESULT_CONNECTION_REFUSED = 1010 ,
  TSC_RESULT_CONNECTION_RESET = 1011 ,
  TSC_RESULT_BAD_HEADER = 1012 ,
  TSC_RESULT_BAD_STATUS = 1013 ,
  TSC_RESULT_NO_PROXY_SUPPORT = 1014 ,
  TSC_RESULT_NO_HTTPS = 1015
}
 

Functions

const char * tsc_strerror (enum tsc_result error)
 
enum tsc_result tsc_http_request_send (struct tsc_http_request *request, struct tsc_http_response **response)
 
enum tsc_result tsc_http_request_send_bytes (struct tsc_http_request *request, const uint8_t *data, uintptr_t data_length, struct tsc_http_response **response)
 
enum tsc_result tsc_http_request_set_header (struct tsc_http_request *request, const char *name, const char *value)
 
enum tsc_result tsc_http_request_get_headers (const struct tsc_http_request *request, void(*callback)(const char *, size_t, const char *, size_t, void *), void *userdata)
 
void tsc_http_request_free (struct tsc_http_request *request)
 
uint16_t tsc_http_response_get_status (const struct tsc_http_response *response)
 
const unsigned char * tsc_http_response_get_status_text (const struct tsc_http_response *response)
 
const unsigned char * tsc_http_response_body (const struct tsc_http_response *response, uintptr_t *len)
 
void tsc_http_response_free (struct tsc_http_response *response)
 
enum tsc_result tsc_http_response_get_headers (const struct tsc_http_response *response, void(*callback)(const char *, size_t, const char *, size_t, void *), void *userdata)
 
struct tsc_http_sessiontsc_http_session_new (void)
 
void tsc_http_session_set_timeout (struct tsc_http_session *session, uint64_t timeout)
 
void tsc_http_session_set_timeout_connect (struct tsc_http_session *session, uint64_t timeout)
 
void tsc_http_session_set_max_redirects (struct tsc_http_session *session, uint32_t redirects)
 
void tsc_http_session_set_user_agent (struct tsc_http_session *session, const char *user_agent)
 
void tsc_http_session_free (struct tsc_http_session *session)
 
enum tsc_result tsc_http_session_set_url (struct tsc_http_session *session, const char *url)
 
struct tsc_http_requesttsc_http_session_get (struct tsc_http_session *session)
 
struct tsc_http_requesttsc_http_session_put (struct tsc_http_session *session)
 
struct tsc_http_requesttsc_http_session_post (struct tsc_http_session *session)
 
struct tsc_http_requesttsc_http_session_delete (struct tsc_http_session *session)
 
struct tsc_http_requesttsc_http_session_patch (struct tsc_http_session *session)
 

Typedef Documentation

◆ tsc_http_request

Struct for HTTP requests

◆ tsc_http_response

Struct for the HTTP response

◆ tsc_http_session

Struct for HTTP sessions

◆ tsc_result

typedef enum tsc_result tsc_result

Enumeration for different possible errors

Enumeration Type Documentation

◆ tsc_result

enum tsc_result

Enumeration for different possible errors

Enumerator
TSC_RESULT_OK 

Function did not have any failures

TSC_RESULT_INVALID_URL 

A URL with an invalid format was used

TSC_RESULT_UTF8_VALIDATION_FAILURE 

An input string where UTF8 is required failed validation

TSC_RESULT_TOO_MANY_REDIRECTS 

The HTTP connection exceeded the max redirects value

TSC_RESULT_TIMED_OUT 

The HTTP connection exceeded the connect or connection timeout

TSC_RESULT_RESPONSE_ERROR 

A non-200 HTTP response was returned

TSC_RESULT_UNEXPECTED_ERROR 

An unexpected error was found

TSC_RESULT_DNS_LOOKUP_FAILURE 

The DNS lookup failed

TSC_RESULT_CONNECTION_FAILED 

The connection failed to be established

TSC_RESULT_CONNECTION_ABORTED 

The connection was aborted

TSC_RESULT_CONNECTION_REFUSED 

The server refused the connection

TSC_RESULT_CONNECTION_RESET 

The server reset the connection

TSC_RESULT_BAD_HEADER 

A bad header was returned from the server

TSC_RESULT_BAD_STATUS 

A bad status was returned from the server

TSC_RESULT_NO_PROXY_SUPPORT 

An attempt was made to use a proxy but it is not supported

TSC_RESULT_NO_HTTPS 

An attempt was made using http, but client only accepts https

6 {
10 TSC_RESULT_OK = 1000,
tsc_result
Definition: tsc.h:6
@ TSC_RESULT_TIMED_OUT
Definition: tsc.h:26
@ TSC_RESULT_CONNECTION_REFUSED
Definition: tsc.h:50
@ TSC_RESULT_BAD_STATUS
Definition: tsc.h:62
@ TSC_RESULT_DNS_LOOKUP_FAILURE
Definition: tsc.h:38
@ TSC_RESULT_CONNECTION_RESET
Definition: tsc.h:54
@ TSC_RESULT_RESPONSE_ERROR
Definition: tsc.h:30
@ TSC_RESULT_NO_PROXY_SUPPORT
Definition: tsc.h:66
@ TSC_RESULT_CONNECTION_FAILED
Definition: tsc.h:42
@ TSC_RESULT_BAD_HEADER
Definition: tsc.h:58
@ TSC_RESULT_CONNECTION_ABORTED
Definition: tsc.h:46
@ TSC_RESULT_TOO_MANY_REDIRECTS
Definition: tsc.h:22
@ TSC_RESULT_UNEXPECTED_ERROR
Definition: tsc.h:34
@ TSC_RESULT_INVALID_URL
Definition: tsc.h:14
@ TSC_RESULT_UTF8_VALIDATION_FAILURE
Definition: tsc.h:18
@ TSC_RESULT_NO_HTTPS
Definition: tsc.h:70
@ TSC_RESULT_OK
Definition: tsc.h:10

Function Documentation

◆ tsc_http_request_free()

void tsc_http_request_free ( struct tsc_http_request request)

Deallocate a request. This function should be called when the request is no longer in use.

Parameters
requestA pointer to a request which was returned from tsc_http_session_get(), tsc_http_session_put(), tsc_http_session_patch(), tsc_http_session_delete(), or tsc_http_session_post().
Examples
tsc.c.

Referenced by main().

◆ tsc_http_request_get_headers()

enum tsc_result tsc_http_request_get_headers ( const struct tsc_http_request request,
void(*)(const char *, size_t, const char *, size_t, void *)  callback,
void *  userdata 
)

Get the current headers set for the request

Parameters
requestA pointer to a request which was returned from tsc_http_session_get(), tsc_http_session_put(), tsc_http_session_patch(), tsc_http_session_delete(), or tsc_http_session_post().
callbackA function pointer which will be called for each key/value pair along with the corresponding sizes and a pointer to 'userdata'
userdataA pointer to allow access to shared data operated on by the callback function.
Returns
A pointer to the internal buffer holding the response. The buffer will be deallocated once tsc_http_response_free() is called.

◆ tsc_http_request_send()

enum tsc_result tsc_http_request_send ( struct tsc_http_request request,
struct tsc_http_response **  response 
)

Issue the request to the network and get back a response. This function call will block until the request has succeeded, failed, or timed out. The status of the call can be read from the return value. If the function call returns TSC_RESULT_OK then the response is valid, otherwise the response should be not be used.

Parameters
requestA pointer to a request which was returned from tsc_http_session_get(), tsc_http_session_put(), tsc_http_session_patch(), tsc_http_session_delete(), or tsc_http_session_post().
responseAn unallocated pointer to a response struct. This function will allocate the response struct. After use the response struct should be unallocated by calling tsc_http_response_free(). The struct will only be allocated if the function is successful.
Returns
If the request fails for some reason it will be return here. Otherwise a value of TSC_RESULT_OK will be returned.
Examples
tsc.c.

Referenced by main().

◆ tsc_http_request_send_bytes()

enum tsc_result tsc_http_request_send_bytes ( struct tsc_http_request request,
const uint8_t *  data,
uintptr_t  data_length,
struct tsc_http_response **  response 
)

Issue the request to the network and get back a response. This request will upload data with the request. The 'Content-Length' header is implicitly set to data_length. This function call will block until the request has succeeded, failed, or timed out. The status of the call can be read from the return value. If the function call returns TSC_RESULT_OK then the response is valid, otherwise the response should be not be used.

Parameters
requestA pointer to a request which was returned from tsc_http_session_get(), tsc_http_session_put(), tsc_http_session_patch(), tsc_http_session_delete(), or tsc_http_session_post().
dataA pointer to the data to send. This is often a file or JSON document.
data_lengthThe length of the buffer pointed to by data.
responseAn unallocated pointer to a response struct. This function will allocate the response struct. After use the response struct should be unallocated by calling tsc_http_response_free(). The struct will only be allocated if the function is successful.
Returns
If the request fails for some reason it will be return here. Otherwise a value of TSC_RESULT_OK will be returned.

◆ tsc_http_request_set_header()

enum tsc_result tsc_http_request_set_header ( struct tsc_http_request request,
const char *  name,
const char *  value 
)

Issue the request to the network and get back a response. This request will upload data with the request. The 'Content-Length' header is implicitly set to data_length. This function call will block until the request has succeeded, failed, or timed out. The status of the call can be read from the return value. If the function call returns TSC_RESULT_OK then the response is valid, otherwise the response should be not be used.

Parameters
requestA pointer to a request which was returned from tsc_http_session_get(), tsc_http_session_put(), tsc_http_session_patch(), tsc_http_session_delete(), or tsc_http_session_post().
nameA pointer to a null terminated string which containing the name of the HTTP header to set
valueA pointer to a null terminated string containing the value of the HTTP header to set
Returns
If the name or value is not UTF-8 encoded an error will be returned. Otherwise a value of TSC_RESULT_OK will be returned on success.

◆ tsc_http_response_body()

const unsigned char * tsc_http_response_body ( const struct tsc_http_response response,
uintptr_t *  len 
)

Get the body of the response. This function will return a pointer to the internal buffer holding the response.

Parameters
responseA pointer to an http_response returned from tsc_http_request_send()
lengthReturns the length in bytes of the body
Returns
A pointer to the internal buffer holding the response. The buffer will be deallocated once tsc_http_response_free() is called.
Note
The returned pointer is not null terminated (i.e. it is not a string).
Examples
tsc.c.

Referenced by main().

◆ tsc_http_response_free()

void tsc_http_response_free ( struct tsc_http_response response)

Deallocate the response once it is no longer in use. Any pointers to data within the response will become invalid.

Parameters
responseA pointer to an http_response returned from tsc_http_request_send() or tsc_http_request_send_bytes()
Examples
tsc.c.

Referenced by main().

◆ tsc_http_response_get_headers()

enum tsc_result tsc_http_response_get_headers ( const struct tsc_http_response response,
void(*)(const char *, size_t, const char *, size_t, void *)  callback,
void *  userdata 
)

Get the headers in the response. The callback function will be called for each header and will be passed a pointer to userdata.

Parameters
responseA pointer to an http_response returned from tsc_http_request_send()
callbackA function pointer which will be called for each key/value pair along with the corresponding sizes and a pointer to 'userdata'
userdataA pointer to allow access to shared data operated on by the callback function.
Returns
A pointer to the internal buffer holding the response. The buffer will be deallocated once tsc_http_response_free() is called.

◆ tsc_http_response_get_status()

uint16_t tsc_http_response_get_status ( const struct tsc_http_response response)

Get the HTTP status code from the response.

Parameters
responseA pointer to an http_response returned from tsc_http_request_send()
Returns
An integer value for the HTTP status code returned.

◆ tsc_http_response_get_status_text()

const unsigned char * tsc_http_response_get_status_text ( const struct tsc_http_response response)

Get the status text from the response. This function will return a pointer to the internal buffer holding the status text. ///

Parameters
responseA pointer to an http_response returned from tsc_http_request_send()
Returns
A pointer to the internal buffer holding the status text. This will become invalid once the response is freed.

◆ tsc_http_session_delete()

struct tsc_http_request * tsc_http_session_delete ( struct tsc_http_session session)

Create an HTTP DELETE request. This type of request is often used to delete a resource on a server.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
Returns
A pointer to an internally allocated tsc_http_request structure. This request can be freed by calling tsc_http_request_free().

◆ tsc_http_session_free()

void tsc_http_session_free ( struct tsc_http_session session)

Free a secure HTTP session. This function will deallocate the tsc_http_session and any allocated requests or responses that have not already been freed.

Parameters
sessionA pointer to session which was allocated from tsc_http_session_new().
Examples
tsc.c.

Referenced by main().

◆ tsc_http_session_get()

struct tsc_http_request * tsc_http_session_get ( struct tsc_http_session session)

Create an HTTP GET request. This type of request is often used to request data from a server.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
Returns
A pointer to an internally allocated tsc_http_request structure. This request can be freed by calling tsc_http_request_free().
Examples
tsc.c.

Referenced by main().

◆ tsc_http_session_new()

struct tsc_http_session * tsc_http_session_new ( void  )

Create a new secure HTTP session. This function will return a pointer to an internally allocated struct for managing the HTTP session. This struct will manage settings and internal memory usage. The first call to this function may initialize some globally shared internal memory.

Returns
A pointer to an internally allocated struct. This pointer must be freed by being passed to tsc_http_session_free when no longer in use.
Examples
tsc.c.

Referenced by main().

◆ tsc_http_session_patch()

struct tsc_http_request * tsc_http_session_patch ( struct tsc_http_session session)

Create an HTTP PATCH request. This type of request is often used to modify a resource on a server.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
Returns
A pointer to an internally allocated tsc_http_request structure. This request can be freed by calling tsc_http_request_free().

◆ tsc_http_session_post()

struct tsc_http_request * tsc_http_session_post ( struct tsc_http_session session)

Create an HTTP POST request. This type of request is often used to send data to a server.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
Returns
A pointer to an internally allocated tsc_http_request structure. This request can be freed by calling tsc_http_request_free().

◆ tsc_http_session_put()

struct tsc_http_request * tsc_http_session_put ( struct tsc_http_session session)

Create an HTTP PUT request. This type of request is often used to send data to a server in an idempotent way.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
Returns
A pointer to an internally allocated tsc_http_request structure. This request can be freed by calling tsc_http_request_free().

◆ tsc_http_session_set_max_redirects()

void tsc_http_session_set_max_redirects ( struct tsc_http_session session,
uint32_t  redirects 
)

Set the max number of HTTP redirects for this session.

Parameters
sessionA pointer to session which was allocated from tsc_http_session_new().
redirectsThe max number of redirects allowed

◆ tsc_http_session_set_timeout()

void tsc_http_session_set_timeout ( struct tsc_http_session session,
uint64_t  timeout 
)

Set timeout for all connections in this session. Note: this does not include the connect timeout.

Parameters
sessionA pointer to session which was allocated from tsc_http_session_new().
timeoutThe length of time in seconds allowed before a connection will timeout.

◆ tsc_http_session_set_timeout_connect()

void tsc_http_session_set_timeout_connect ( struct tsc_http_session session,
uint64_t  timeout 
)

Set the connect timeout for all connections in this session. Note: this only includes the initial connect timeout, not the timeout for the overall connection.

Parameters
sessionA pointer to session which was allocated from tsc_http_session_new().
timeoutThe length of time in seconds allowed before a connection will timeout.

◆ tsc_http_session_set_url()

enum tsc_result tsc_http_session_set_url ( struct tsc_http_session session,
const char *  url 
)

Set the URL future requests will use. The URL must start with HTTPS. All requests made after calling this function will use this URL until this function is called again.

Parameters
sessionA pointer to a session which was allocated from tsc_http_session_new()
urlA pointer to a valid URL starting with https://.
Returns
If the URL fails to be parsed this function will return an error. Otherwise TSC_RESULT_OK will be returned.
Examples
tsc.c.

Referenced by main().

◆ tsc_http_session_set_user_agent()

void tsc_http_session_set_user_agent ( struct tsc_http_session session,
const char *  user_agent 
)

The user agent string will be copied so it can be freed after use

Parameters
sessionA pointer to session which was allocated from tsc_http_session_new().
user_agentA string to specify the user agent.

◆ tsc_strerror()

const char * tsc_strerror ( enum tsc_result  error)