ThingWorx C SDK
Classes | Macros | Typedefs | Enumerations | Functions
twWebsocket.h File Reference

Websocket client abstraction layer. More...

#include "twOSPort.h"
#include "twDefinitions.h"

Go to the source code of this file.

Classes

struct  twWs
 Websocket entity structure definition. More...
 

Macros

#define WS_TLS_CONN(a)   (twTlsClient *)a->connection
 

Typedefs

typedef int(* ws_cb) (struct twWs *ws)
 
typedef int(* ws_data_cb) (struct twWs *ws, const char *at, size_t length)
 
typedef struct twWs twWs
 Websocket entity structure definition.
 

Enumerations

enum  close_status {
  SERVER_CLOSED = 0, NORMAL_CLOSE = 1000, GOING_TO_SLEEP, PROTOCOL_ERROR,
  UNSUPPORTED_DATA_TYPE, RESERVED1, RESERVED2, RESERVED3,
  INVALID_DATA, POLICY_VIOLATION, FRAME_TOO_LARGE, NO_EXTENSION_FOUND,
  UNEXPECTED_CONDITION
}
 Websocket close reasoning enumeration. More...
 

Functions

int twWs_Create (char *host, uint16_t port, char *resource, char *api_key, char *gatewayName, uint32_t messageChunkSize, uint16_t frameSize, twWs **entity)
 Creates a new websocket struct and the underlying dependent components. More...
 
int twWs_Delete (twWs *ws)
 Frees all memory associated with a twWs structure and all its owned substructures. More...
 
int twWs_Connect (twWs *ws, uint32_t timeout)
 Establishes a websocket connection to the server. More...
 
int twWs_Disconnect (twWs *ws, enum close_status code, char *reason)
 Disconnect a websocket connection from the server. More...
 
char twWs_IsConnected (twWs *ws)
 Gets the connection status of a websocket entity structure. More...
 
int twWs_RegisterConnectCallback (twWs *ws, ws_cb cb)
 Registers a function to be called when the websocket is successfully connected. More...
 
int twWs_RegisterCloseCallback (twWs *ws, ws_data_cb cb)
 Registers a function to be called when the websocket is closed by the server. More...
 
int twWs_RegisterBinaryMessageCallback (twWs *ws, ws_data_cb cb)
 Registers a function to be called when the websocket receives a complete binary message. More...
 
int twWs_RegisterTextMessageCallback (twWs *ws, ws_data_cb cb)
 Registers a function to be called when the websocket receives a complete text message. More...
 
int twWs_RegisterPingCallback (twWs *ws, ws_data_cb cb)
 Registers a function to be called when the websocket receives a Ping message. More...
 
int twWs_RegisterPongCallback (twWs *ws, ws_data_cb cb)
 Registers a function to be called when the websocket receives a Pong message. More...
 
int twWs_Receive (twWs *ws, uint32_t timeout)
 Check the websocket for data and drive the state machine of the websocket. More...
 
int twWs_SendMessage (twWs *ws, char *buf, uint32_t length, char isText)
 Send a message over the websocket. More...
 
int twWs_SendPing (twWs *ws, char *msg)
 Send a Ping message over the websocket. More...
 
int twWs_SendPong (twWs *ws, char *msg)
 Send a Pong message over the websocket. More...
 

Detailed Description

Websocket client abstraction layer.

Contains structure type definitions and function prototypes for ThingWorx Websockets.

Enumeration Type Documentation

Websocket close reasoning enumeration.

Enumerator
SERVER_CLOSED 

0 - Server closed.

NORMAL_CLOSE 

1000 - Normal close.

GOING_TO_SLEEP 

1001 - Going to sleep.

PROTOCOL_ERROR 

1002 - Protocol error.

UNSUPPORTED_DATA_TYPE 

1003 - Unsupported data type.

RESERVED1 

1004 - RESERVED.

RESERVED2 

1005 - RESERVED.

RESERVED3 

1006 - RESERVED.

INVALID_DATA 

1007 - Invalid data.

POLICY_VIOLATION 

1008 - Policy violation.

FRAME_TOO_LARGE 

1009 - Frame too large.

NO_EXTENSION_FOUND 

1010 - No extension found.

UNEXPECTED_CONDITION 

1011 - Unexpected condition.

Function Documentation

int twWs_Connect ( twWs ws,
uint32_t  timeout 
)

Establishes a websocket connection to the server.

Parameters
[in]wsThe twWs structure to connect.
[in]timeoutThe amount of time (in milliseconds) to wait for the connection to be established.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_Create ( char *  host,
uint16_t  port,
char *  resource,
char *  api_key,
char *  gatewayName,
uint32_t  messageChunkSize,
uint16_t  frameSize,
twWs **  entity 
)

Creates a new websocket struct and the underlying dependent components.

Parameters
[in]hostThe hostname of the websocket server.
[in]portThe port that the websocket server is listening on.
[in]resourceThe HTTP resource to use when establishing a connection.
[in]api_keyThe api key that will be used during an ensuing authentication process.
[in]gatewayNameAn optional name used if the SDK is being used to develop a gateway application which allows multiple Things to connect through it. If not NULL, this is used during the binding process.
[in]messageChunkSizeThe maximum size (in bytes) of a multipart message chunk.
[in]frameSizeThe maximum websocket frame size (not to be confused with the maximum ThingWorx message size).
[out]entityA pointer to the newly allocated twWs structure.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This function does not attempt to establish a connection.
The calling function retains ownership of the entity pointer and is responsible for freeing it via twWs_Delete().

Context manipulation functions

int twWs_Delete ( twWs ws)

Frees all memory associated with a twWs structure and all its owned substructures.

Parameters
[in]wsThe twWs structure to delete.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This function will shut down any connection associated with the structure before deleting it.
int twWs_Disconnect ( twWs ws,
enum close_status  code,
char *  reason 
)

Disconnect a websocket connection from the server.

Parameters
[in]wsThe twWs structure to disconnect. [in] code Close status code.
[in]reasonThe reason for the disconnection.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
char twWs_IsConnected ( twWs ws)

Gets the connection status of a websocket entity structure.

Parameters
[in]wsThe websocket entity structure to get the connection status of.
Returns
#TRUE if ws is connected, #FALSE if it isn't.
int twWs_Receive ( twWs ws,
uint32_t  timeout 
)

Check the websocket for data and drive the state machine of the websocket.

Parameters
[in]wsThe twWs structure to utilize.
[in]timeoutTime (in miliseconds) to wait for data on the socket.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This function must be called on a regular basis.
No data is returned as the data is delivered through the state machine callback functions.
int twWs_RegisterBinaryMessageCallback ( twWs ws,
ws_data_cb  cb 
)

Registers a function to be called when the websocket receives a complete binary message.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_RegisterCloseCallback ( twWs ws,
ws_data_cb  cb 
)

Registers a function to be called when the websocket is closed by the server.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_RegisterConnectCallback ( twWs ws,
ws_cb  cb 
)

Registers a function to be called when the websocket is successfully connected.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_RegisterPingCallback ( twWs ws,
ws_data_cb  cb 
)

Registers a function to be called when the websocket receives a Ping message.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_RegisterPongCallback ( twWs ws,
ws_data_cb  cb 
)

Registers a function to be called when the websocket receives a Pong message.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_RegisterTextMessageCallback ( twWs ws,
ws_data_cb  cb 
)

Registers a function to be called when the websocket receives a complete text message.

Parameters
[in]wsThe twWs structure to register with.
[in]cbA pointer to the function to register.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twWs_SendMessage ( twWs ws,
char *  buf,
uint32_t  length,
char  isText 
)

Send a message over the websocket.

Parameters
[in]wsThe twWs structure to utilize.
[in]bufA pointer to the buffer containing the message.
[in]lengthThe length of the message.
[in]isTextIf #TRUE, will be sent as a text message, if #FALSE will be sent as a binary message.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The message will be broken up into a series of multipart messages if necessary.
int twWs_SendPing ( twWs ws,
char *  msg 
)

Send a Ping message over the websocket.

Parameters
[in]wsThe twWs structure to utilize.
[in]msgLess than 126 byte NULL-terminated string to send with the Ping.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The msg data must be NULL-terminated and less than 126 bytes.
int twWs_SendPong ( twWs ws,
char *  msg 
)

Send a Pong message over the websocket.

Parameters
[in]wsThe twWs structure to utilize.
[in]msgLess than 126 byte NULL-terminated string to send with the Pong.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The msg data must be NULL-terminated and less than 126 bytes.