client.h File Reference

Contains functions for dealing with the client convenience struct. More...

#include <he.h>

Include dependency graph for client.h:

Go to the source code of this file.

Macros
#define	HE_WOLF_TIMEOUT_MULTIPLIER   100
#define	HE_WOLF_RENEGOTIATION_TIMEOUT_MULTIPLIER   1000

Functions
he_client_t *	he_client_create (void)
	Creates a Helium client. More...
he_return_code_t	he_client_destroy (he_client_t *client)
	Releases all memory allocate by Helium including for the crypto layer. More...
he_return_code_t	he_client_connect (he_client_t *client)
	Tries to establish a connection with a Helium server. More...
he_return_code_t	he_client_disconnect (he_client_t *client)
	Try to cleanly disconnect from the remote server. More...
he_return_code_t	he_client_is_config_valid (he_client_t *client)
	Checks whether the client context has the basic configuration to allow Helium to connect. More...

Detailed Description

Contains functions for dealing with the client convenience struct.

Function Documentation

he_return_code_t he_client_connect

(

he_client_t *

client

)

Tries to establish a connection with a Helium server.

Parameters

client

A pointer to a valid client context

Returns

HE_ERR_NULL_POINTER The client pointer supplied is NULL

HE_ERR_CONF_USERNAME_NOT_SET The username has not been set

HE_ERR_CONF_PASSWORD_NOT_SET The password has not been set

HE_ERR_CONF_CA_NOT_SET The CA has not been set

HE_ERR_CONF_MTU_NOT_SET The external MTU has not been set

HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set

HE_ERR_INIT_FAILED Helium was unable to initialise itself

HE_ERR_SSL_BAD_FILETYPE The SSL certificate was not provided in PEM format

HE_ERR_SSL_BAD_FILE The SSL certificate is corrupt or damaged

HE_ERR_SSL_OUT_OF_MEMORY The crypto engine ran out of memory

HE_ERR_SSL_ASN_INPUT The certificate does not comply to ASN formatting

HE_ERR_SSL_BUFFER Ran out of memory trying to allocate buffers for the SSL layer

HE_ERR_SSL_CERT Generic failure in the SSL engine

HE_ERR_CONNECT_FAILED There was an I/O issue trying to connect to the server.

HE_SUCCESS Helium is in the process of connecting

Note

This function triggers the initialisation and initial connection to a Helium server. However it is asynchronous, Helium is not connected when this function returns, merely that the connection is in progress. Use event and state change callbacks to determine the actual state of Helium

This function has a lot of return codes as it is where Helium tries to apply and configure the crypto engine. All of the return codes except for HE_SUCCESS are effectively fatal errors. Trying to call he_client_connect again without changing the configuration is unlikely to succeed.

he_client_t* he_client_create

(

void

)

Creates a Helium client.

Returns

he_client_t* Returns a pointer to a valid Helium context

Note

This function allocates memory

This function must be called to create the initial Helium context for use with other functions

he_return_code_t he_client_destroy

(

he_client_t *

client

)

Releases all memory allocate by Helium including for the crypto layer.

Parameters

client

A pointer to a valid client context

Returns

HE_SUCCESS This function cannot fail

Note

The crypto layer initialises a limited amount of global state, which Helium does not free because there could be multiple Helium instances. The memory used is minimal and will not impact creating new Helium instances

It will first remove all of the callbacks which means no Helium callbacks will be triggered after calling this function. It is thus an error to call any Helium functions on this context after it has been destroyed.

he_return_code_t he_client_disconnect

(

he_client_t *

client

)

Try to cleanly disconnect from the remote server.

Parameters

client

A pointer to a valid client context

Returns

HE_ERR_NEVER_CONNECTED The client context has never been connected and so cannot be disconnected. It is safe to destroy the client state here.

HE_ERR_INVALID_CLIENT_STATE This function should only be used when Helium is in the online state. It is safe to destroy the client in other states.

HE_SUCCESS The disconnect process has started

Note

Like he_client_connect, this is an asynchronous process. Watch state changes to determine when Helium has actually disconnected

This function is not yet well described and is likely to change

he_return_code_t he_client_is_config_valid

(

he_client_t *

client

)

Checks whether the client context has the basic configuration to allow Helium to connect.

Parameters

client

A pointer to a valid client context

Returns

HE_ERR_NULL_POINTER The client pointer supplied is NULL

HE_ERR_CONF_USERNAME_NOT_SET The username has not been set

HE_ERR_CONF_PASSWORD_NOT_SET The password has not been set

HE_ERR_CONF_CA_NOT_SET The CA has not been set

HE_ERR_CONF_MTU_NOT_SET The external MTU has not been set

HE_ERR_CONF_OUTSIDE_WRITE_CB_NOT_SET The outside write callback has not been set

HE_SUCCESS The basic configuration options have been set

Note

These return codes are similar to he_client_connect because that function will call this function before attempting to connect.