libctru  v1.6.0
Data Structures | Macros | Enumerations | Functions
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

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
contextContext to use.
certIDID 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
contextContext to use.
nameName of the field.
valueValue 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
contextContext to use.
nameName of the field.
valueThe binary data to pass as a value.
lenLength 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
contextContext to use.
dataThe data to be passed as raw into the body of the post request.
lenLength 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
contextContext to use.
nameName of the field.
valueValue 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
contextContext to use.
certPointer to DER cert.
certsizeSize of the DER cert.

◆ httpcBeginRequest()

Result httpcBeginRequest ( httpcContext context)

Begins a HTTP request.

Parameters
contextContext 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
contextContext to close.

◆ httpcCloseClientCertContext()

Result httpcCloseClientCertContext ( u32  ClientCert_contexthandle)

Closes a ClientCert context.

Parameters
ClientCert_contexthandleClientCert context to use.

◆ httpcCloseContext()

Result httpcCloseContext ( httpcContext context)

Closes a HTTP context.

Parameters
contextContext 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_contexthandleOutput RootCertChain contexthandle.

◆ httpcDestroyRootCertChain()

Result httpcDestroyRootCertChain ( u32  RootCertChain_contexthandle)

Destroy a RootCertChain.

Parameters
RootCertChain_contexthandleRootCertChain 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
contextContext to download data from.
bufferBuffer to write data to.
sizeSize of the buffer.
downloadedsizePointer 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
contextContext to use.
downloadedsizePointer to output the downloaded size to.
contentsizePointer 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
contextContext to use.
outPointer 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
contextContext to use.
nameName of the field.
valuePointer to output the value of the field to.
valuebuf_maxsizeMaximum 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
contextContext to get the response code of.
outPointer 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
contextContext to get the response code of.
outPointer to write the response code to.
timeoutMaximum 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
certPointer to DER cert.
certsizeSize of the DER cert.
privkPointer to the DER private key.
privk_sizeSize of the privk.
ClientCert_contexthandleOutput ClientCert context handle.

◆ httpcOpenContext()

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

Opens a HTTP context.

Parameters
contextContext to open.
urlURL to connect to.
use_defaultproxyWhether 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
certIDID of the cert to add, see sslc.h.
ClientCert_contexthandleOutput ClientCert context handle.

◆ httpcReceiveData()

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

Receives data from a HTTP context.

Parameters
contextContext to use.
bufferBuffer to receive data to.
sizeSize 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
contextContext to use.
bufferBuffer to receive data to.
sizeSize of the buffer.
timeoutMaximum 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_contexthandleRootCertChain to use.
certPointer to DER cert.
certsizeSize of the DER cert.
cert_contexthandleOptional 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_contexthandleRootCertChain to use.
certIDID of the cert to add, see sslc.h.
cert_contexthandleOptional 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_contexthandleRootCertChain to use.
cert_contexthandleContexthandle of the cert to remove.

◆ httpcSelectRootCertChain()

Result httpcSelectRootCertChain ( httpcContext context,
u32  RootCertChain_contexthandle 
)

Sets the RootCertChain for a HTTP context.

Parameters
contextContext to use.
RootCertChain_contexthandleContexthandle 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
contextContext to use.
certPointer to DER cert.
certsizeSize of the DER cert.
privkPointer to the DER private key.
privk_sizeSize of the privk.

◆ httpcSetClientCertContext()

Result httpcSetClientCertContext ( httpcContext context,
u32  ClientCert_contexthandle 
)

Sets the ClientCert contexthandle for a HTTP context.

Parameters
contextContext to use.
ClientCert_contexthandleContexthandle for the ClientCert.

◆ httpcSetClientCertDefault()

Result httpcSetClientCertDefault ( httpcContext context,
SSLC_DefaultClientCert  certID 
)

Sets the default clientcert for a HTTP context.

Parameters
contextContext to use.
certIDID of the cert to add, see sslc.h.

◆ httpcSetKeepAlive()

Result httpcSetKeepAlive ( httpcContext context,
HTTPC_KeepAlive  option 
)

Sets Keep-Alive for the context.

Parameters
contextContext to set the KeepAlive flag on.
optionHTTPC_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
contextContext to clear flags on.
optionsSSL 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
contextContext to set flags on.
optionsSSL option flags.
Examples
network/http/source/main.c, and network/http_post/source/main.c.