ThingWorx C SDK
Classes | Typedefs | Functions
twTunnelManager.h File Reference

ThingWorx tunneling structure definitions and function prototypes. More...

#include "twOSPort.h"
#include "twDefinitions.h"
#include "twDefaultSettings.h"
#include "twList.h"

Go to the source code of this file.

Classes

struct  twActiveTunnel
 Active tunnel structure definition. More...
 

Typedefs

typedef void(* tunnel_cb) (char started, const char *tid, const char *thingName, const char *peerName, const char *host, int16_t port, DATETIME startTime, DATETIME endTime, uint64_t bytesSent, uint64_t bytesRcvd, const char *type, const char *msg, void *userdata)
 Signature of a callback function that is registered to be called when a tunnel state changes. More...
 
typedef twList twActiveTunnelList
 
typedef struct twActiveTunnel twActiveTunnel
 Active tunnel structure definition.
 

Functions

int twTunnelManager_Create ()
 Creates the tunnel manager singleton. More...
 
int twTunnelManager_Delete ()
 Frees all memory associated with the tunnel manager singleton and all its owned substructures. More...
 
void twTunnelManager_TaskerFunction (DATETIME now, void *params)
 Executes all functions required for proper operation of tunnels. More...
 
int twTunnelManager_StopTunnel (char *id, char *msg)
 Shuts down a tunnel. More...
 
int twTunnelManager_StopAllTunnels ()
 Shuts down all tunnels. More...
 
int twTunnelManager_UpdateTunnelServerInfo (char *host, uint16_t port, char *appkey)
 Updates the host, port, and appkey of the tunnels related to connecting to the server. More...
 
int twTunnelManager_RegisterTunnelCallback (tunnel_cb cb, char *id, void *userdata)
 Registers a function to be called when a tunnel state changes. More...
 
int twTunnelManager_UnregisterTunnelCallback (tunnel_cb cb, char *id, void *userdata)
 Unregisters a tunnel callback function that was registered via twTunnelManager_RegisterTunnelCallback(). More...
 
twActiveTunnelListtwTunnelManager_ListActiveTunnels ()
 Return a list of the currently active tunnels. More...
 
void twTunnelManager_SetProxyInfo (char *proxyHost, uint16_t proxyPort, char *proxyUser, char *proxyPass)
 Sets the proxy information to be used when making a connection. More...
 
void twTunnelManager_SetSelfSignedOk (char state)
 Passthru to notify the TLS library to accept self-signed certificates. More...
 
void twTunnelManager_EnableFipsMode (char state)
 Passthru to enable FIPS mode for TLS providers that support to. More...
 
void twTunnelManager_DisableCertValidation (char state)
 Passthru to notify the TLS library to not validate the server certificate. More...
 
void twTunnelManager_DisableEncryption (char state)
 Passthru to notify the TLS library to disable encryption. More...
 
void twTunnelManager_SetX509Fields (char *subject_cn, char *subject_o, char *subject_ou, char *issuer_cn, char *issuer_o, char *issuer_ou)
 Defines which fields of an X509 certificate will be validated. NULL parameteres will not be checked against the deceived certificate. More...
 
void twTunnelManager_LoadCACert (const char *file, int type)
 Loads the local PEM or DER formatted certificate file used to validate the server. More...
 
void twTunnelManager_LoadClientCert (char *file)
 Loads the local PEM or DER formatted certificate file used to validate the client to the server. More...
 
void twTunnelManager_SetClientKey (const char *file, char *passphrase, int type)
 Sets the key of the client. More...
 

Detailed Description

ThingWorx tunneling structure definitions and function prototypes.

Contains structure type definitions and function prototypes for the ThingWorx API tunneling operations.

Typedef Documentation

typedef void(* tunnel_cb) (char started, const char *tid, const char *thingName, const char *peerName, const char *host, int16_t port, DATETIME startTime, DATETIME endTime, uint64_t bytesSent, uint64_t bytesRcvd, const char *type, const char *msg, void *userdata)

Signature of a callback function that is registered to be called when a tunnel state changes.

Parameters
[in]started#TRUE if the tunnel is started, #FALSE if the tunnel has ended.
[in]tidUnique ID of the tunnel.
[in]thingNameThe name of the thing the tunnel is targeted at.
[in]peerNameThe name of the peer user of the tunnel.
[in]hostThe hostname of the local connection that is tunneled to.
[in]portThe port number of the local connection that is tunneled to.
[in]startTimeThe time the tunnel started (0 if it hasn't started).
[in]endTimeThe time the tunnel ended (0 if it hasn't ended).
[in]bytesSentThe total number of bytes that were sent to the peer.
[in]bytesRcvdThe total number of bytes that were received from the peer.
[in]typeThe type of the tunnel.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
Nothing.
Note
The calling function will gain ownership of all pointers associated with the tunnel and is responsible for freeing them.

Function Documentation

int twTunnelManager_Create ( )

Creates the tunnel manager singleton.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The tunnel manager singleton must be freed via twTunnelManager_Delete().
int twTunnelManager_Delete ( )

Frees all memory associated with the tunnel manager singleton and all its owned substructures.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_DisableCertValidation ( char  state)

Passthru to notify the TLS library to not validate the server certificate.

Returns
Nothing.
Warning
Disabling certificate validation may induce a serious security risk.
void twTunnelManager_DisableEncryption ( char  state)

Passthru to notify the TLS library to disable encryption.

Returns
Nothing.
Warning
Disabling encryption may induce a serious security risk.
void twTunnelManager_EnableFipsMode ( char  state)

Passthru to enable FIPS mode for TLS providers that support to.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
twActiveTunnelList* twTunnelManager_ListActiveTunnels ( )

Return a list of the currently active tunnels.

Returns
A pointer to a twList of the currently active tunnels. NULL if an error was encountered.
Note
The calling function will gain ownership of the returned twList and is responsible for freeing it via twList_Delete().
void twTunnelManager_LoadCACert ( const char *  file,
int  type 
)

Loads the local PEM or DER formatted certificate file used to validate the server.

Parameters
[in]fileThe full path to the file containing the certificate.
[in]typeDefinition is dependent on the underlying TLS library (may be set to 0 for AxTLS).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_LoadClientCert ( char *  file)

Loads the local PEM or DER formatted certificate file used to validate the client to the server.

Parameters
[in]fileThe full path to the file containing the certificate.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTunnelManager_RegisterTunnelCallback ( tunnel_cb  cb,
char *  id,
void *  userdata 
)

Registers a function to be called when a tunnel state changes.

Parameters
[in]cbThe function to register.
[in]idID of tunnel to callback on state change ("*" or NULL signifies all tunnels).
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_SetClientKey ( const char *  file,
char *  passphrase,
int  type 
)

Sets the key of the client.

Parameters
[in]fileThe full path to the file containing the key.
[in]passphraseThe passphrase used to open the file.
[in]typeDefinition is dependent on the underlying TLS library (may be set to 0 for AxTLS).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_SetProxyInfo ( char *  proxyHost,
uint16_t  proxyPort,
char *  proxyUser,
char *  proxyPass 
)

Sets the proxy information to be used when making a connection.

Parameters
[in]proxyHostThe host name of the proxy.
[in]proxyPortThe port used by the proxy.
[in]proxyUserThe username to supply to the proxy (NULL if authentication is disabled).
[in]proxyPassThe password to supply to the proxy (NULL if authentication is disabled).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_SetSelfSignedOk ( char  state)

Passthru to notify the TLS library to accept self-signed certificates.

Returns
Nothing.
void twTunnelManager_SetX509Fields ( char *  subject_cn,
char *  subject_o,
char *  subject_ou,
char *  issuer_cn,
char *  issuer_o,
char *  issuer_ou 
)

Defines which fields of an X509 certificate will be validated. NULL parameteres will not be checked against the deceived certificate.

Parameters
[in]subject_cnThe common name of the subject in the certificate.
[in]subject_oThe organization of the subject in the certificate.
[in]subject_ouThe organizational unit of the subject in the certificate.
[in]issuer_cnThe common name of the issuer in the certificate.
[in]issuer_oThe organization of the issuer in the certificate.
[in]issuer_ouThe organizational unit of the issuer in the certificate.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTunnelManager_StopAllTunnels ( )

Shuts down all tunnels.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTunnelManager_StopTunnel ( char *  id,
char *  msg 
)

Shuts down a tunnel.

Parameters
[in]idThe ID of the tunnel to shutdown.
[in]msgMessage to be logged.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTunnelManager_TaskerFunction ( DATETIME  now,
void *  params 
)

Executes all functions required for proper operation of tunnels.

Parameters
[in]nowThe current timestamp.
[in]paramsRequired by the tasker function signature but currently not used.
Returns
Nothing.
int twTunnelManager_UnregisterTunnelCallback ( tunnel_cb  cb,
char *  id,
void *  userdata 
)

Unregisters a tunnel callback function that was registered via twTunnelManager_RegisterTunnelCallback().

Parameters
[in]cbPointer to the function to be unregistered.
[in]idID of the tunnel that the callback was registered to.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTunnelManager_UpdateTunnelServerInfo ( char *  host,
uint16_t  port,
char *  appkey 
)

Updates the host, port, and appkey of the tunnels related to connecting to the server.

Parameters
[in]hostThe new host name to use.
[in]portThe new port to use.
[in]appkeyThe new appkey to use.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.