httpc.h File Reference

HTTP service. More...

Go to the source code of this file.

## Data Structures

struct | httpcContext
| HTTP context. More...

## Macros

#define | HTTPC_RESULTCODE_DOWNLOADPENDING 0xd840a02b
| Result code returned when a download is pending.
#define | HTTPC_RESULTCODE_NOTFOUND 0xd840a028
#define | HTTPC_RESULTCODE_TIMEDOUT 0xd820a069

## Enumerations

enum | HTTPC_RequestMethod { HTTPC_METHOD_GET = 0x1 , HTTPC_METHOD_POST = 0x2 , HTTPC_METHOD_HEAD = 0x3 , HTTPC_METHOD_PUT = 0x4 , HTTPC_METHOD_DELETE = 0x5 }
| HTTP request method.
enum | HTTPC_RequestStatus { HTTPC_STATUS_REQUEST_IN_PROGRESS = 0x5 , HTTPC_STATUS_DOWNLOAD_READY = 0x7 }
| HTTP request status. More...
enum | HTTPC_KeepAlive { HTTPC_KEEPALIVE_DISABLED = 0x0 , HTTPC_KEEPALIVE_ENABLED = 0x1 }
| HTTP KeepAlive option.

## Functions

Result | httpcInit (u32 sharedmem_size)
| Initializes HTTPC. For HTTP GET the sharedmem_size can be zero. The sharedmem contains data which will be later uploaded for HTTP POST. sharedmem_size should be aligned to 0x1000-bytes.
void | httpcExit (void)
| Exits HTTPC.
Result | httpcOpenContext (httpcContext *context, HTTPC_RequestMethod method, const char *url, u32 use_defaultproxy)
| Opens a HTTP context. More...
Result | httpcCloseContext (httpcContext *context)
| Closes a HTTP context. More...
Result | httpcCancelConnection (httpcContext *context)
| Cancels a HTTP connection. More...
Result | httpcAddRequestHeaderField (httpcContext *context, const char *name, const char *value)
| Adds a request header field to a HTTP context. More...
Result | httpcAddPostDataAscii (httpcContext *context, const char *name, const char *value)
| Adds a POST form field to a HTTP context. More...
Result | httpcAddPostDataBinary (httpcContext *context, const char *name, const u8 *value, u32 len)
| Adds a POST form field with binary data to a HTTP context. More...
Result | httpcAddPostDataRaw (httpcContext *context, const u32 *data, u32 len)
| Adds a POST body to a HTTP context. More...
Result | httpcBeginRequest (httpcContext *context)
| Begins a HTTP request. More...
Result | httpcReceiveData (httpcContext *context, u8 *buffer, u32 size)
| Receives data from a HTTP context. More...
Result | httpcReceiveDataTimeout (httpcContext *context, u8 *buffer, u32 size, u64 timeout)
| Receives data from a HTTP context with a timeout value. More...
Result | httpcGetRequestState (httpcContext *context, HTTPC_RequestStatus *out)
| Gets the request state of a HTTP context. More...
Result | httpcGetDownloadSizeState (httpcContext *context, u32 *downloadedsize, u32 *contentsize)
| Gets the download size state of a HTTP context. More...
Result | httpcGetResponseStatusCode (httpcContext *context, u32 *out)
| Gets the response code of the HTTP context. More...
Result | httpcGetResponseStatusCodeTimeout (httpcContext *context, u32 *out, u64 timeout)
| Gets the response code of the HTTP context with a timeout value. More...
Result | httpcGetResponseHeader (httpcContext *context, const char *name, char *value, u32 valuebuf_maxsize)
| Gets a response header field from a HTTP context. More...
Result | httpcAddTrustedRootCA (httpcContext *context, const u8 *cert, u32 certsize)
| Adds a trusted RootCA cert to a HTTP context. More...
Result | httpcAddDefaultCert (httpcContext *context, SSLC_DefaultRootCert certID)
| Adds a default RootCA cert to a HTTP context. More...
Result | httpcSelectRootCertChain (httpcContext *context, u32 RootCertChain_contexthandle)
| Sets the RootCertChain for a HTTP context. More...
Result | httpcSetClientCert (httpcContext *context, const u8 *cert, u32 certsize, const u8 *privk, u32 privk_size)
| Sets the ClientCert for a HTTP context. More...
Result | httpcSetClientCertDefault (httpcContext *context, SSLC_DefaultClientCert certID)
| Sets the default clientcert for a HTTP context. More...
Result | httpcSetClientCertContext (httpcContext *context, u32 ClientCert_contexthandle)
| Sets the ClientCert contexthandle for a HTTP context. More...
Result | httpcSetSSLOpt (httpcContext *context, u32 options)
| Sets SSL options for the context. More...
Result | httpcSetSSLClearOpt (httpcContext *context, u32 options)
| Sets the SSL options which will be cleared for the context. More...
Result | httpcCreateRootCertChain (u32 *RootCertChain_contexthandle)
| Creates a RootCertChain. More...
Result | httpcDestroyRootCertChain (u32 RootCertChain_contexthandle)
| Destroy a RootCertChain. More...
Result | httpcRootCertChainAddCert (u32 RootCertChain_contexthandle, const u8 *cert, u32 certsize, u32 *cert_contexthandle)
| Adds a RootCA cert to a RootCertChain. More...
Result | httpcRootCertChainAddDefaultCert (u32 RootCertChain_contexthandle, SSLC_DefaultRootCert certID, u32 *cert_contexthandle)
| Adds a default RootCA cert to a RootCertChain. More...
Result | httpcRootCertChainRemoveCert (u32 RootCertChain_contexthandle, u32 cert_contexthandle)
| Removes a cert from a RootCertChain. More...
Result | httpcOpenClientCertContext (const u8 *cert, u32 certsize, const u8 *privk, u32 privk_size, u32 *ClientCert_contexthandle)
| Opens a ClientCert-context. More...
Result | httpcOpenDefaultClientCertContext (SSLC_DefaultClientCert certID, u32 *ClientCert_contexthandle)
| Opens a ClientCert-context with a default clientclient. More...
Result | httpcCloseClientCertContext (u32 ClientCert_contexthandle)
| Closes a ClientCert context. More...
Result | httpcDownloadData (httpcContext *context, u8 *buffer, u32 size, u32 *downloadedsize)
| Downloads data from the HTTP context into a buffer. More...
Result | httpcSetKeepAlive (httpcContext *context, HTTPC_KeepAlive option)
| Sets Keep-Alive for the context. More...

## Detailed Description

HTTP service.

## Enumeration Type Documentation

## HTTPC_RequestStatus

enum HTTPC_RequestStatus

HTTP request status.

Enumerator
HTTPC_STATUS_REQUEST_IN_PROGRESS | Request in progress.
HTTPC_STATUS_DOWNLOAD_READY | Download ready.

## Function Documentation

## httpcAddDefaultCert()

Result httpcAddDefaultCert | ( | httpcContext * | context,
|  | SSLC_DefaultRootCert | certID
| ) |  |

Adds a default RootCA cert to a HTTP context.

Parameters

  context | Context to use.
  certID | ID of the cert to add, see sslc.h.

## httpcAddPostDataAscii()

Result httpcAddPostDataAscii | ( | httpcContext * | context,
|  | const char * | name,
|  | const char * | value
| ) |  |

Adds a POST form field to a HTTP context.

Parameters

  context | Context to use.
  name | Name of the field.
  value | Value of the field.

## httpcAddPostDataBinary()

Result httpcAddPostDataBinary | ( | httpcContext * | context,
|  | const char * | name,
|  | const u8 * | value,
|  | u32 | len
| ) |  |

Adds a POST form field with binary data to a HTTP context.

Parameters

  context | Context to use.
  name | Name of the field.
  value | The binary data to pass as a value.
  len | Length of the binary data which has been passed.

## httpcAddPostDataRaw()

Result httpcAddPostDataRaw | ( | httpcContext * | context,
|  | const u32 * | data,
|  | u32 | len
| ) |  |

Adds a POST body to a HTTP context.

Parameters

  context | Context to use.
  data | The data to be passed as raw into the body of the post request.
  len | Length of data passed by data param.

Examples
  network/http_post/source/main.c.

## httpcAddRequestHeaderField()

Result httpcAddRequestHeaderField | ( | httpcContext * | context,
|  | const char * | name,
|  | const char * | value
| ) |  |

Adds a request header field to a HTTP context.

Parameters

  context | Context to use.
  name | Name of the field.
  value | Value of the field.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcAddTrustedRootCA()

Result httpcAddTrustedRootCA | ( | httpcContext * | context,
|  | const u8 * | cert,
|  | u32 | certsize
| ) |  |

Adds a trusted RootCA cert to a HTTP context.

Parameters

  context | Context to use.
  cert | Pointer to DER cert.
  certsize | Size of the DER cert.

## httpcBeginRequest()

Result httpcBeginRequest | ( | httpcContext * | context | ) |

Begins a HTTP request.

Parameters

  context | Context to use.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcCancelConnection()

Result httpcCancelConnection | ( | httpcContext * | context | ) |

Cancels a HTTP connection.

Parameters

  context | Context to close.

## httpcCloseClientCertContext()

Result httpcCloseClientCertContext | ( | u32 | ClientCert_contexthandle | ) |

Closes a ClientCert context.

Parameters

  ClientCert_contexthandle | ClientCert context to use.

## httpcCloseContext()

Result httpcCloseContext | ( | httpcContext * | context | ) |

Closes a HTTP context.

Parameters

  context | Context to close.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcCreateRootCertChain()

Result httpcCreateRootCertChain | ( | u32 * | RootCertChain_contexthandle | ) |

Creates a RootCertChain.

Up to 2 RootCertChains can be created under this user-process.

Parameters

  RootCertChain_contexthandle | Output RootCertChain contexthandle.

## httpcDestroyRootCertChain()

Result httpcDestroyRootCertChain | ( | u32 | RootCertChain_contexthandle | ) |

Destroy a RootCertChain.

Parameters

  RootCertChain_contexthandle | RootCertChain to use.

## httpcDownloadData()

Result httpcDownloadData | ( | httpcContext * | context,
|  | u8 * | buffer,
|  | u32 | size,
|  | u32 * | downloadedsize
| ) |  |

Downloads data from the HTTP context into a buffer.

The entire content must be downloaded before using httpcCloseContext(), otherwise httpcCloseContext() will hang.

Parameters

  context | Context to download data from.
  buffer | Buffer to write data to.
  size | Size of the buffer.
  downloadedsize | Pointer to write the size of the downloaded data to.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcGetDownloadSizeState()

Result httpcGetDownloadSizeState | ( | httpcContext * | context,
|  | u32 * | downloadedsize,
|  | u32 * | contentsize
| ) |  |

Gets the download size state of a HTTP context.

Parameters

  context | Context to use.
  downloadedsize | Pointer to output the downloaded size to.
  contentsize | Pointer to output the total content size to.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcGetRequestState()

Result httpcGetRequestState | ( | httpcContext * | context,
|  | HTTPC_RequestStatus * | out
| ) |  |

Gets the request state of a HTTP context.

Parameters

  context | Context to use.
  out | Pointer to output the HTTP request state to.

## httpcGetResponseHeader()

Result httpcGetResponseHeader | ( | httpcContext * | context,
|  | const char * | name,
|  | char * | value,
|  | u32 | valuebuf_maxsize
| ) |  |

Gets a response header field from a HTTP context.

Parameters

  context | Context to use.
  name | Name of the field.
  value | Pointer to output the value of the field to.
  valuebuf_maxsize | Maximum size of the value buffer.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcGetResponseStatusCode()

Result httpcGetResponseStatusCode | ( | httpcContext * | context,
|  | u32 * | out
| ) |  |

Gets the response code of the HTTP context.

Parameters

  context | Context to get the response code of.
  out | Pointer to write the response code to.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcGetResponseStatusCodeTimeout()

Result httpcGetResponseStatusCodeTimeout | ( | httpcContext * | context,
|  | u32 * | out,
|  | u64 | timeout
| ) |  |

Gets the response code of the HTTP context with a timeout value.

Parameters

  context | Context to get the response code of.
  out | Pointer to write the response code to.
  timeout | Maximum time in nanoseconds to wait for a reply.

## httpcOpenClientCertContext()

Result httpcOpenClientCertContext | ( | const u8 * | cert,
|  | u32 | certsize,
|  | const u8 * | privk,
|  | u32 | privk_size,
|  | u32 * | ClientCert_contexthandle
| ) |  |

Opens a ClientCert-context.

Up to 2 ClientCert-contexts can be open under this user-process.

Parameters

  cert | Pointer to DER cert.
  certsize | Size of the DER cert.
  privk | Pointer to the DER private key.
  privk_size | Size of the privk.
  ClientCert_contexthandle | Output ClientCert context handle.

## httpcOpenContext()

Result httpcOpenContext | ( | httpcContext * | context,
|  | HTTPC_RequestMethod | method,
|  | const char * | url,
|  | u32 | use_defaultproxy
| ) |  |

Opens a HTTP context.

Parameters

  context | Context to open.
  url | URL to connect to.
  use_defaultproxy | Whether the default proxy should be used (0 for default)

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcOpenDefaultClientCertContext()

Result httpcOpenDefaultClientCertContext | ( | SSLC_DefaultClientCert | certID,
|  | u32 * | ClientCert_contexthandle
| ) |  |

Opens a ClientCert-context with a default clientclient.

Up to 2 ClientCert-contexts can be open under this user-process.

Parameters

  certID | ID of the cert to add, see sslc.h.
  ClientCert_contexthandle | Output ClientCert context handle.

## httpcReceiveData()

Result httpcReceiveData | ( | httpcContext * | context,
|  | u8 * | buffer,
|  | u32 | size
| ) |  |

Receives data from a HTTP context.

Parameters

  context | Context to use.
  buffer | Buffer to receive data to.
  size | Size of the buffer.

## httpcReceiveDataTimeout()

Result httpcReceiveDataTimeout | ( | httpcContext * | context,
|  | u8 * | buffer,
|  | u32 | size,
|  | u64 | timeout
| ) |  |

Receives data from a HTTP context with a timeout value.

Parameters

  context | Context to use.
  buffer | Buffer to receive data to.
  size | Size of the buffer.
  timeout | Maximum time in nanoseconds to wait for a reply.

## httpcRootCertChainAddCert()

Result httpcRootCertChainAddCert | ( | u32 | RootCertChain_contexthandle,
|  | const u8 * | cert,
|  | u32 | certsize,
|  | u32 * | cert_contexthandle
| ) |  |

Adds a RootCA cert to a RootCertChain.

Parameters

  RootCertChain_contexthandle | RootCertChain to use.
  cert | Pointer to DER cert.
  certsize | Size of the DER cert.
  cert_contexthandle | Optional output ptr for the cert contexthandle(this can be NULL).

## httpcRootCertChainAddDefaultCert()

Result httpcRootCertChainAddDefaultCert | ( | u32 | RootCertChain_contexthandle,
|  | SSLC_DefaultRootCert | certID,
|  | u32 * | cert_contexthandle
| ) |  |

Adds a default RootCA cert to a RootCertChain.

Parameters

  RootCertChain_contexthandle | RootCertChain to use.
  certID | ID of the cert to add, see sslc.h.
  cert_contexthandle | Optional output ptr for the cert contexthandle(this can be NULL).

## httpcRootCertChainRemoveCert()

Result httpcRootCertChainRemoveCert | ( | u32 | RootCertChain_contexthandle,
|  | u32 | cert_contexthandle
| ) |  |

Removes a cert from a RootCertChain.

Parameters

  RootCertChain_contexthandle | RootCertChain to use.
  cert_contexthandle | Contexthandle of the cert to remove.

## httpcSelectRootCertChain()

Result httpcSelectRootCertChain | ( | httpcContext * | context,
|  | u32 | RootCertChain_contexthandle
| ) |  |

Sets the RootCertChain for a HTTP context.

Parameters

  context | Context to use.
  RootCertChain_contexthandle | Contexthandle for the RootCertChain.

## httpcSetClientCert()

Result httpcSetClientCert | ( | httpcContext * | context,
|  | const u8 * | cert,
|  | u32 | certsize,
|  | const u8 * | privk,
|  | u32 | privk_size
| ) |  |

Sets the ClientCert for a HTTP context.

Parameters

  context | Context to use.
  cert | Pointer to DER cert.
  certsize | Size of the DER cert.
  privk | Pointer to the DER private key.
  privk_size | Size of the privk.

## httpcSetClientCertContext()

Result httpcSetClientCertContext | ( | httpcContext * | context,
|  | u32 | ClientCert_contexthandle
| ) |  |

Sets the ClientCert contexthandle for a HTTP context.

Parameters

  context | Context to use.
  ClientCert_contexthandle | Contexthandle for the ClientCert.

## httpcSetClientCertDefault()

Result httpcSetClientCertDefault | ( | httpcContext * | context,
|  | SSLC_DefaultClientCert | certID
| ) |  |

Sets the default clientcert for a HTTP context.

Parameters

  context | Context to use.
  certID | ID of the cert to add, see sslc.h.

## httpcSetKeepAlive()

Result httpcSetKeepAlive | ( | httpcContext * | context,
|  | HTTPC_KeepAlive | option
| ) |  |

Sets Keep-Alive for the context.

Parameters

  context | Context to set the KeepAlive flag on.
  option | HTTPC_KeepAlive option.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.

## httpcSetSSLClearOpt()

Result httpcSetSSLClearOpt | ( | httpcContext * | context,
|  | u32 | options
| ) |  |

Sets the SSL options which will be cleared for the context.

The HTTPC SSL option bits are the same as those defined in sslc.h

Parameters

  context | Context to clear flags on.
  options | SSL option flags.

## httpcSetSSLOpt()

Result httpcSetSSLOpt | ( | httpcContext * | context,
|  | u32 | options
| ) |  |

Sets SSL options for the context.

The HTTPC SSL option bits are the same as those defined in sslc.h

Parameters

  context | Context to set flags on.
  options | SSL option flags.

Examples
  network/http/source/main.c, and network/http_post/source/main.c.