RTM CORE SDK documentation. More...

#include <stddef.h>
#include <time.h>
#include <rtm_config.h>

Include dependency graph for rtm.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	rtm_list_iterator_t
	SDK uses this type to return collections of strings, for example messages in subscription_data PDUs. User code repeatedly calls rtm_iterate with the iterator, getting all messages one by one. More...

struct	_rtm_pdu
	Structure containing information about the received PDU. More...

struct	_rtm_client_priv

struct	rtm_client

Macros
#define	RTM_API

#define	RTM_TEST_API

#define	_RTM_SCRATCH_BUFFER_SIZE (256)

#define	_RTM_WS_PRE_BUFFER 16

#define	RTM_MAX_CHANNEL_SIZE (256)
	Maximum size of a channel name.

#define	RTM_MAX_MESSAGE_SIZE (65536)
	Maximum size of a message.

#define	RTM_PATH ("/v2")
	RTM path.

#define	RTM_MAX_ENDPOINT_SIZE (256)
	Maximum size of the endpoint parameter.

#define	RTM_MAX_APPKEY_SIZE (32)
	Maximum size of the appkey parameter.

#define	RTM_MAX_ROLE_NAME_SIZE (512)
	Maximum size of the role name parameter.

#define	RTM_AUTHENTICATION_HASH_SIZE (24)
	Expected size of the authentication hash parameter in bytes.

#define	RTM_CLIENT_SIZE_WITH_BUFFERS(buffer_size) (sizeof(struct _rtm_client_priv) + _RTM_WS_PRE_BUFFER + 2*buffer_size)
	Calculate the size requirements for a RTM client. More...

#define	RTM_CLIENT_SIZE (RTM_CLIENT_SIZE_WITH_BUFFERS(RTM_MAX_MESSAGE_SIZE))
	Preferred size of a RTM client.

Typedefs
typedef struct _rtm_pdu	rtm_pdu_t
	Structure containing information about the received PDU. More...

typedef struct rtm_client	rtm_client_t
	Opaque rtm client structure.

typedef void(	rtm_message_handler_t) (rtm_client_t rtm, const char subscription_id, const char *message)
	Type of callback function invoked when client receives messages from RTM. More...

typedef void(	rtm_pdu_handler_t) (rtm_client_t rtm, const rtm_pdu_t pdu)
	Type of callback function invoked when client receives PDU from RTM. More...

typedef void(	rtm_raw_pdu_handler_t) (rtm_client_t rtm, char const raw_pdu)

typedef void(	rtm_error_logger_t) (const char *message)
	Error logging function.

typedef void *(	rtm_malloc_fn_t) (rtm_client_t *rtm, size_t size)
	malloc() like function for use with RTM. More...

typedef void(	rtm_free_fn_t) (rtm_client_t rtm, void ptr)
	free() like function for use with RTM. More...

Enumerations
enum	rtm_action_t { RTM_ACTION_UNKNOWN = 0, RTM_ACTION_AUTHENTICATE_ERROR, RTM_ACTION_AUTHENTICATE_OK, RTM_ACTION_DELETE_ERROR, RTM_ACTION_DELETE_OK, RTM_ACTION_GENERAL_ERROR, RTM_ACTION_HANDSHAKE_ERROR, RTM_ACTION_HANDSHAKE_OK, RTM_ACTION_PUBLISH_ERROR, RTM_ACTION_PUBLISH_OK, RTM_ACTION_READ_ERROR, RTM_ACTION_READ_OK, RTM_ACTION_SUBSCRIBE_ERROR, RTM_ACTION_SUBSCRIBE_OK, RTM_ACTION_SUBSCRIPTION_DATA, RTM_ACTION_SUBSCRIPTION_ERROR, RTM_ACTION_SUBSCRIPTION_INFO, RTM_ACTION_UNSUBSCRIBE_ERROR, RTM_ACTION_UNSUBSCRIBE_OK, RTM_ACTION_WRITE_ERROR, RTM_ACTION_WRITE_OK, RTM_ACTION_SENTINEL }
	The set of all possible actions that PDUs incoming from RTM can have.

enum	rtm_status { RTM_OK = 0, RTM_WOULD_BLOCK, RTM_ERR_OOM = -100, RTM_ERR_PARAM = -99, RTM_ERR_PARAM_INVALID = -98, RTM_ERR_CONNECT = -97, RTM_ERR_NETWORK = -96, RTM_ERR_CLOSED = -95, RTM_ERR_READ = -94, RTM_ERR_WRITE = -93, RTM_ERR_PROTOCOL = -92, RTM_ERR_TLS = -91, RTM_ERR_TIMEOUT = -90 }
	Type used internally to report errors. More...

Functions
RTM_API char *	rtm_iterate (rtm_list_iterator_t const *iterator)
	get next element in iterator or NULL if there are none

RTM_API void	rtm_set_error_logger (rtm_client_t rtm, rtm_error_logger_t error_logger)
	Set the error logger used by the RTM structure. The default value is `rtm_default_error_logger`.

RTM_API void *	rtm_system_malloc (rtm_client_t *rtm, size_t size)
	malloc() implementation using the system's malloc()

RTM_API void	rtm_system_free (rtm_client_t rtm, void mem)
	free() implementation using the system's free()

RTM_API void *	rtm_null_malloc (rtm_client_t *rtm, size_t size)
	malloc() implementation that always fails gracefully More...

RTM_API void	rtm_null_free (rtm_client_t rtm, void mem)
	free() implementation that does nothing

RTM_API void	rtm_set_allocator (rtm_client_t rtm, rtm_malloc_fn_t malloc_ptr, rtm_free_fn_t *free_ptr)
	Set the allocator used by the RTM structure. More...

RTM_API void	rtm_default_error_logger (const char *message)
	Default error handler. More...

RTM_API void	rtm_default_message_handler (rtm_client_t rtm, const char channel, const char *message)
	Default message handler prints all messages to stdout. More...

RTM_API void	rtm_default_pdu_handler (rtm_client_t rtm, const rtm_pdu_t pdu)
	Default PDU handler prints all PDUs to stdout. More...

RTM_API time_t	rtm_get_ws_ping_interval (rtm_client_t *rtm)
	Returns current WS ping interval (sec) More...

RTM_API void	rtm_set_connection_timeout (rtm_client_t *rtm, unsigned timeout_in_seconds)
	Sets the given connection timeout in seconds. Default is 5 seconds. More...

RTM_API void	rtm_set_ws_ping_interval (rtm_client_t *rtm, time_t ws_ping_interval)
	Sets new WS ping interval. A ws ping frame will be perodically sent to server to avoid connection refusing. Default: 45 (sec) More...

RTM_API rtm_client_t *	rtm_init (void memory, rtm_pdu_handler_t pdu_handler, void *user_context)
	Initialize an instance of rtm_client_t. More...

RTM_API rtm_client_t *	rtm_init_ex (void memory, size_t memory_size, rtm_pdu_handler_t pdu_handler, void *user_context)
	Initialize an instance of rtm_client_t with a custom buffer size. More...

RTM_API rtm_status	rtm_connect (rtm_client_t rtm, const char endpoint, const char *appkey)
	Connects to RTM. More...

RTM_API rtm_status	rtm_connect_via_https_proxy (rtm_client_t rtm, char const endpoint, char const appkey, char const proxy_endpoint)
	Connects to RTM via an https proxy. More...

RTM_API void	rtm_set_raw_pdu_handler (rtm_client_t rtm, rtm_raw_pdu_handler_t handler)
	Set the handler for not yet parsed PDUs. More...

RTM_API void	rtm_enable_verbose_logging (rtm_client_t *rtm)
	Enable logging of incoming and outcoming PDUs. More...

RTM_API void	rtm_disable_verbose_logging (rtm_client_t *rtm)
	Disable logging of incoming and outcoming PDUs. More...

RTM_API void	rtm_close (rtm_client_t *rtm)
	Close an RTM connection. More...

RTM_API rtm_status	rtm_handshake (rtm_client_t rtm, const char role, unsigned *ack_id)
	Send the handshake request to obtain nonce from the server. More...

RTM_API rtm_status	rtm_authenticate (rtm_client_t rtm, const char role_secret, const char nonce, unsigned ack_id)
	Send the authenticate request to establish the identity of the client. More...

RTM_API rtm_status	rtm_publish_json (rtm_client_t rtm, const char channel, const char json, unsigned ack_id)
	Publish the well-formed JSON string to RTM. More...

RTM_API rtm_status	rtm_publish_string (rtm_client_t rtm, const char channel, const char string, unsigned ack_id)
	Publish the string to RTM. More...

RTM_API rtm_status	rtm_subscribe (rtm_client_t rtm, const char channel, unsigned *ack_id)
	Subscribe to a specific channel. More...

RTM_API rtm_status	rtm_subscribe_with_body (rtm_client_t rtm, const char body, unsigned *ack_id)
	Subscribe with specifying a full body of subscribe PDU request. More...

RTM_API rtm_status	rtm_unsubscribe (rtm_client_t rtm, const char channel, unsigned *ack_id)
	Unsubscribe from a channel. More...

RTM_API rtm_status	rtm_parse_pdu (char message, rtm_pdu_t pdu)
	Parse string as top-level PDU object. More...

RTM_API rtm_status	rtm_read (rtm_client_t rtm, const char channel, unsigned *ack_id)
	Read the latest published message. More...

RTM_API rtm_status	rtm_read_with_body (rtm_client_t rtm, const char body, unsigned *ack_id)
	Read the latest published message with specifying a full body of read PDU request. More...

RTM_API rtm_status	rtm_send_ws_ping (rtm_client_t *rtm)
	Send a websocket ping frame. More...

RTM_API rtm_status	rtm_write_string (rtm_client_t rtm, const char key, const char string, unsigned ack_id)
	Write the string value to a specific channel. More...

RTM_API rtm_status	rtm_write_json (rtm_client_t rtm, const char key, const char json, unsigned ack_id)
	Write the well-formed JSON value to a specific channel. More...

RTM_API rtm_status	rtm_delete (rtm_client_t rtm, const char key, unsigned *ack_id)
	Delete the value of a specific channel. More...

RTM_API rtm_status	rtm_send_pdu (rtm_client_t rtm, const char json)
	Send a raw PDU as well-formed JSON string. More...

RTM_API rtm_status	rtm_wait (rtm_client_t *rtm)
	Wait for any PDUs and execute the user's callbacks. More...

RTM_API rtm_status	rtm_wait_timeout (rtm_client_t *rtm, int timeout_in_seconds)
	Wait with timeout for any PDUs and execute the user's callbacks. More...

RTM_API rtm_status	rtm_poll (rtm_client_t *rtm)
	Poll the underlying socket for any PDUs and execute the user's callbacks. More...

RTM_API int	rtm_get_fd (rtm_client_t *rtm)
	Retrieve the underlying file descriptor so that it can be incorporated into a message loop, like libev or libevent. More...

RTM_API void *	rtm_get_user_context (rtm_client_t *rtm)
	Retrieve the user specific pointer from the client. More...

RTM_API const char *	rtm_error_string (rtm_status status)
	Returns a human-readable string representing the status of operation. More...

Variables
RTM_API const size_t	rtm_client_size
	Default size of rtm_client_t in bytes.

Detailed Description

RTM CORE SDK documentation.

This Core SDK is a very low level to the RTM service.

// allocate some memory to store the client
void *memory = malloc(rtm_client_size);
rtm_client_t *rtm = rtm_init(memory, rtm_default_pdu_handler, 0);
// connect to RTM
int rc = rtm_connect(rtm, endpoint, appkey);
if (rc != RTM_OK) {
    printf("rtm_connect failed with status %d\n", rc);
    exit(1);
}
// publish message
rc = rtm_publish_string(rtm, "channel", "Hello, World!", NULL);
if (rc != RTM_OK) {
    printf("rtm_publish_string failed with status %d\n", rc);
    exit(1);
}
rtm_close(rtm);

Macro Definition Documentation

§ RTM_CLIENT_SIZE_WITH_BUFFERS

#define RTM_CLIENT_SIZE_WITH_BUFFERS ( buffer_size ) (sizeof(struct _rtm_client_priv) + _RTM_WS_PRE_BUFFER + 2*buffer_size)

Calculate the size requirements for a RTM client.

Parameters

[in] buffer_size Total number of bytes for buffers

Returns: size of the rtm_client_t structure

Typedef Documentation

§ rtm_free_fn_t

typedef void( rtm_free_fn_t) (rtm_client_t *rtm, void *ptr)

free() like function for use with RTM.

Parameters

[in]	rtm	instance of the client
[in]	ptr	pointer to memory to be released

See also: rtm_set_allocator; rtm_system_free; rtm_null_free

§ rtm_malloc_fn_t

typedef void*( rtm_malloc_fn_t) (rtm_client_t *rtm, size_t size)

malloc() like function for use with RTM.

Parameters

[in]	rtm	instance of the client
[in]	size	amount of memory to be allocated

Returns: A pointer to the newly allocated memory, or NULL if the allocation failed

See also: rtm_set_allocator; rtm_system_malloc; rtm_null_malloc

§ rtm_message_handler_t

typedef void( rtm_message_handler_t) (rtm_client_t *rtm, const char *subscription_id, const char *message)

Type of callback function invoked when client receives messages from RTM.

Note: when rtm_init is called, a pointer to a user defined structure can be set. You can get this value from rtm in the context of this callback by calling rtm_get_user_context:

void my_message_callback(rtm_client_t *rtm, const char *subscription_id,
                         const char *message) {
   my_context *context = (my_context *) rtm_get_user_context(rtm);
   context->message_count++;
   ...
}

See also: rtm_default_message_handler for details.; rtm_get_user_context; rtm_init

§ rtm_pdu_handler_t

typedef void( rtm_pdu_handler_t) (rtm_client_t *rtm, const rtm_pdu_t *pdu)

Type of callback function invoked when client receives PDU from RTM.

Note: when rtm_init is called, a pointer to a user defined structure can be set. You can get this value from rtm in the context of this callback by calling rtm_get_user_context:

void my_pdu_callback(rtm_client_t *rtm, const rtm_pdu_t *pdu) {
   my_context *context = (my_context *) rtm_get_user_context(rtm);
   context->event_count++;
   ...
}

See also: rtm_default_pdu_handler for details.; rtm_init; rtm_get_user_context

§ rtm_pdu_t

typedef struct _rtm_pdu rtm_pdu_t

Structure containing information about the received PDU.

Extra fields availability:

  Action              | Fields
  ------------------- | -------------
  UNKNOWN             | body
  AUTHENTICATE_ERROR  | error, reason
  GENERAL_ERROR       | error, reason
  DELETE_ERROR        | error, reason
  HANDSHAKE_ERROR     | error, reason
  PUBLISH_ERROR       | error, reason
  READ_ERROR          | error, reason
  WRITE_ERROR         | error, reason
  SUBSCRIBE_ERROR     | error, reason
  UNSUBSCRIBE_ERROR   | error, reason
  SUBSCRIPTION_ERROR  | subscription_id, error, reason
  SUBSCRIPTION_INFO   | subscription_id, info, reason
  SUBSCRIPTION_DATA   | subscription_id, message_iterator, position
  SUBSCRIBE_OK        | subscription_id, position
  UNSUBSCRIBE_OK      | subscription_id, position
  AUTHENTICATE_OK     | ---
  HANDSHAKE_OK        | nonce
  PUBLISH_OK          | position
  DELETE_OK           | position
  WRITE_OK            | position
  READ_OK             | message, position

Enumeration Type Documentation

§ rtm_status

enum rtm_status

Type used internally to report errors.

The values can be used to diagnose errors that happen while interacting with c core.

Enumerator
RTM_OK	No error.
RTM_WOULD_BLOCK	The operation would be a blocking IO operation
RTM_ERR_OOM	Insufficient memory for this operation
RTM_ERR_PARAM	One of the parameters passed to the function is incorrect
RTM_ERR_PARAM_INVALID	A parameter of the function is invalid
RTM_ERR_CONNECT	The client could not connect to RTM
RTM_ERR_NETWORK	An unexpected network error occurred
RTM_ERR_CLOSED	The connection is closed
RTM_ERR_READ	An error occurred while receiving data from RTM
RTM_ERR_WRITE	An error occurred while sending data to RTM
RTM_ERR_PROTOCOL	An error occurred in the protocol layer
RTM_ERR_TLS	An unexpected error happened in the TLS layer
RTM_ERR_TIMEOUT	The operation timed out

Function Documentation

§ rtm_authenticate()

RTM_API rtm_status rtm_authenticate	(	rtm_client_t *	rtm,
		const char *	role_secret,
		const char *	nonce,
		unsigned *	ack_id
	)

Send the authenticate request to establish the identity of the client.

RTM reply will have same identifier as value of ack_id.

Parameters

[in]	rtm	instance of the client.
[in]	role_secret	a secret token from Dev Portal.
[in]	nonce	from handshare request.
[out]	ack_id	the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	the operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_close()

RTM_API void rtm_close ( rtm_client_t * rtm )

Close an RTM connection.

This method gracefully terminating connection to RTM. This method doesn't free memory allocated for client.

It is safe to call this function from pdu handlers to terminate the connection on e.g., errors.

Warning: Do not use the object after calling this function.

Parameters

[in] rtm instance of the client

Here is the caller graph for this function:

§ rtm_connect()

RTM_API rtm_status rtm_connect	(	rtm_client_t *	rtm,
		const char *	endpoint,
		const char *	appkey
	)

Connects to RTM.

Parameters

[in]	rtm	instance of the client
[in]	endpoint	endpoint for the RTM Service.
[in]	appkey	application key to the RTM Service.

Note: The endpoint must be a well formed URL "wss://xxx.api.satori.com/"

Returns: the status of the operation

Return values

RTM_OK	if the connection is established
RTM_ERR_*	if the connection failed.

See also: rtm_close; rtm_get_user_context

§ rtm_connect_via_https_proxy()

RTM_API rtm_status rtm_connect_via_https_proxy	(	rtm_client_t *	rtm,
		char const *	endpoint,
		char const *	appkey,
		char const *	proxy_endpoint
	)

Connects to RTM via an https proxy.

Parameters

[in]	rtm	instance of the client
[in]	endpoint	endpoint for the RTM Service.
[in]	appkey	application key to the RTM Service.
[in]	proxy_endpoint

Note: The endpoint must be a well formed URL "wss://xxx.api.satori.com/"

Returns: the status of the operation

Return values

RTM_OK	if the connection is established
RTM_ERR_*	if the connection failed.

See also: rtm_close; rtm_get_user_context

§ rtm_default_error_logger()

RTM_API void rtm_default_error_logger ( const char * message )

Default error handler.

This handler sends all messages to stderr.

Parameters

[in] message to log as a zero terminated string.

§ rtm_default_message_handler()

RTM_API void rtm_default_message_handler	(	rtm_client_t *	rtm,
		const char *	channel,
		const char *	message
	)

Default message handler prints all messages to stdout.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[in]	message	message to output

§ rtm_default_pdu_handler()

RTM_API void rtm_default_pdu_handler	(	rtm_client_t *	rtm,
		const rtm_pdu_t *	pdu
	)

Default PDU handler prints all PDUs to stdout.

Parameters

[in]	rtm	instance of the client
[in]	pdu	the rtm_pdu_t to process

§ rtm_delete()

RTM_API rtm_status rtm_delete	(	rtm_client_t *	rtm,
		const char *	key,
		unsigned *	ack_id
	)

Delete the value of a specific channel.

Note: same as rtm_publish with message null

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	key	name of the channel
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_disable_verbose_logging()

RTM_API void rtm_disable_verbose_logging ( rtm_client_t * rtm )

Disable logging of incoming and outcoming PDUs.

Parameters

[in] rtm instance of the client

§ rtm_enable_verbose_logging()

RTM_API void rtm_enable_verbose_logging ( rtm_client_t * rtm )

Enable logging of incoming and outcoming PDUs.

Parameters

[in] rtm instance of the client

§ rtm_error_string()

RTM_API const char* rtm_error_string ( rtm_status status )

Returns a human-readable string representing the status of operation.

Parameters

[in] status of operation.

Returns: a human-readable description of status.

§ rtm_get_fd()

RTM_API int rtm_get_fd ( rtm_client_t * rtm )

Retrieve the underlying file descriptor so that it can be incorporated into a message loop, like libev or libevent.

Parameters

[in] rtm instance of the client

Returns: the system file descriptor associated with the connection

§ rtm_get_user_context()

RTM_API void* rtm_get_user_context ( rtm_client_t * rtm )

Retrieve the user specific pointer from the client.

Parameters

[in] rtm instance of the client.

Returns: the user context pointer specified when calling rtm_init

§ rtm_get_ws_ping_interval()

RTM_API time_t rtm_get_ws_ping_interval ( rtm_client_t * rtm )

Returns current WS ping interval (sec)

Parameters

[in] rtm instance of the client

Returns: current ping interval

§ rtm_handshake()

RTM_API rtm_status rtm_handshake	(	rtm_client_t *	rtm,
		const char *	role,
		unsigned *	ack_id
	)

Send the handshake request to obtain nonce from the server.

Performs initial negotiation to obtain a nonce from the server before the client can send the final authentication request.

RTM reply will have same identifier as value of ack_id.

Parameters

[in]	rtm	instance of the client
[in]	role	name of role
[out]	ack_id	the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	the operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_init()

RTM_API rtm_client_t* rtm_init	(	void *	memory,
		rtm_pdu_handler_t *	pdu_handler,
		void *	user_context
	)

Initialize an instance of rtm_client_t.

Parameters

[in]	memory	a buffer of size rtm_client_size
[in]	pdu_handler	the callback for all PDUs
[in]	user_context	an opaque user specified data associated with this RTM object

Returns: initialized rtm_client_t object

See also: rtm_init_ex; rtm_close; rtm_get_user_context

Note: If you choose to work with unparsed PDUs, pass null as pdu_handler here and then use rtm_set_raw_pdu_handler.

§ rtm_init_ex()

RTM_API rtm_client_t* rtm_init_ex	(	void *	memory,
		size_t	memory_size,
		rtm_pdu_handler_t *	pdu_handler,
		void *	user_context
	)

Initialize an instance of rtm_client_t with a custom buffer size.

Parameters

[in]	memory	a buffer of at least rtm_client_min_size bytes
[in]	memory_size	The allocation size of memory
[in]	pdu_handler	the callback for all PDUs
[in]	user_context	an opaque user specified data associated with this RTM object

Returns: initialized rtm_client_t object

See also: RTM_CLIENT_SIZE; rtm_init; rtm_close; rtm_get_user_context

§ rtm_null_malloc()

RTM_API void* rtm_null_malloc	(	rtm_client_t *	rtm,
		size_t	size
	)

malloc() implementation that always fails gracefully

This function always returns NULL. Use it if you would like to skip over frames that are too large to handle.

§ rtm_parse_pdu()

RTM_API rtm_status rtm_parse_pdu	(	char *	message,
		rtm_pdu_t *	pdu
	)

Parse string as top-level PDU object.

Warning: method modifies original JSON string.

Parameters

[in]	json	string.
[out]	pdu_out	parsed PDU.

Return values

RTM_ERR_* an error occurred

Here is the caller graph for this function:

§ rtm_poll()

RTM_API rtm_status rtm_poll ( rtm_client_t * rtm )

Poll the underlying socket for any PDUs and execute the user's callbacks.

rtm_poll is the internal IO loop.

Parameters

[in] rtm instance of the client

Returns: the status of the operation

Return values

RTM_OK	the operation succeeded and decoded at least one websocket frame
RTM_WOULD_BLOCK	the operation needs more data to process the buffer (got partial frames or no frames at all)
RTM_ERR_*	when something went wrong

See also: rtm_status for details

Here is the call graph for this function:

Here is the caller graph for this function:

§ rtm_publish_json()

RTM_API rtm_status rtm_publish_json	(	rtm_client_t *	rtm,
		const char *	channel,
		const char *	json,
		unsigned *	ack_id
	)

Publish the well-formed JSON string to RTM.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[in]	json	message
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	the operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_publish_string()

RTM_API rtm_status rtm_publish_string	(	rtm_client_t *	rtm,
		const char *	channel,
		const char *	string,
		unsigned *	ack_id
	)

Publish the string to RTM.

Published string will be escaped before transmission.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[in]	string	the message to send.
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_read()

RTM_API rtm_status rtm_read	(	rtm_client_t *	rtm,
		const char *	channel,
		unsigned *	ack_id
	)

Read the latest published message.

RTM reply will have same identifier as value of ack_id.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[out]	ack_id	the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_read_with_body()

RTM_API rtm_status rtm_read_with_body	(	rtm_client_t *	rtm,
		const char *	body,
		unsigned *	ack_id
	)

Read the latest published message with specifying a full body of read PDU request.

RTM reply will have same identifier as value of ack_id.

Parameters

[in]	rtm	instance of the client
[in]	body	of read request PDU as JSON string.
[out]	ack_id	the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_send_pdu()

RTM_API rtm_status rtm_send_pdu	(	rtm_client_t *	rtm,
		const char *	json
	)

Send a raw PDU as well-formed JSON string.

Parameters

[in]	rtm	instance of the client
[in]	json	PDU as JSON string.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_send_ws_ping()

RTM_API rtm_status rtm_send_ws_ping ( rtm_client_t * rtm )

Send a websocket ping frame.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_set_allocator()

RTM_API void rtm_set_allocator	(	rtm_client_t *	rtm,
		rtm_malloc_fn_t *	malloc_ptr,
		rtm_free_fn_t *	free_ptr
	)

Set the allocator used by the RTM structure.

By default, RTM does not ever allocate any memory and fails hard by closing the connection if it would need to.

When the SDK runs out of memory, it invokes the allocator function. If this function returns non-NULL, it assumes that it was given a pointer to memory of at least the requested size and uses that memory to perform the requested action. Once the action is completed, the free() function is called and the memory is released. If the allocator returns NULL, the SDK tries to gracefully handle the error condition. It will skip over frames that are too large to handle, and over fragmented frames that would become too large after reassembly. To fail hard, close the connection from the malloc() function.

The SDK provides default functions for convenience.

See also: rtm_system_free; rtm_null_free; rtm_system_malloc; rtm_null_malloc

§ rtm_set_connection_timeout()

RTM_API void rtm_set_connection_timeout	(	rtm_client_t *	rtm,
		unsigned	timeout_in_seconds
	)

Sets the given connection timeout in seconds. Default is 5 seconds.

Parameters

[in]	rtm	instance of the client
[in]	timeout_in_seconds	new timeout value

§ rtm_set_raw_pdu_handler()

RTM_API void rtm_set_raw_pdu_handler	(	rtm_client_t *	rtm,
		rtm_raw_pdu_handler_t *	handler
	)

Set the handler for not yet parsed PDUs.

Parameters

[in]	rtm	instance of the client
[in]	handler	pointer to a function of type (rtm_client_t rtm, char const raw_pdu) -> void

Note: After this handler is called, raw_pdu will be parsed by the SDK and the result will be passed to pdu_handler which was provided to rtm_init function. If (non-raw) pdu_handler was null, that parsing doesn't happen and you're free to cast raw_pdu to non-const char* and modify it (for example if your json parser works in-place).

§ rtm_set_ws_ping_interval()

RTM_API void rtm_set_ws_ping_interval	(	rtm_client_t *	rtm,
		time_t	ws_ping_interval
	)

Sets new WS ping interval. A ws ping frame will be perodically sent to server to avoid connection refusing. Default: 45 (sec)

Parameters

[in]	rtm	instance of the client
[in]	ws_ping_interval	new interval value (sec)

§ rtm_subscribe()

RTM_API rtm_status rtm_subscribe	(	rtm_client_t *	rtm,
		const char *	channel,
		unsigned *	ack_id
	)

Subscribe to a specific channel.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_subscribe_with_body()

RTM_API rtm_status rtm_subscribe_with_body	(	rtm_client_t *	rtm,
		const char *	body,
		unsigned *	ack_id
	)

Subscribe with specifying a full body of subscribe PDU request.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client.
[in]	body	of subscribe request PDU as JSON string.
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_unsubscribe()

RTM_API rtm_status rtm_unsubscribe	(	rtm_client_t *	rtm,
		const char *	channel,
		unsigned *	ack_id
	)

Unsubscribe from a channel.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	channel	name of the channel
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

§ rtm_wait()

RTM_API rtm_status rtm_wait ( rtm_client_t * rtm )

Wait for any PDUs and execute the user's callbacks.

This method will return after at least one message is processed or an error occurs. It can be used in a tight loop without consuming CPU resources when there is no data to read.

Parameters

[in] rtm instance of the client

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

Here is the call graph for this function:

§ rtm_wait_timeout()

RTM_API rtm_status rtm_wait_timeout	(	rtm_client_t *	rtm,
		int	timeout_in_seconds
	)

Wait with timeout for any PDUs and execute the user's callbacks.

Parameters

[in]	rtm	instance of the client
[in]	timeout_in_seconds	in seconds

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes

Here is the call graph for this function:

§ rtm_write_json()

RTM_API rtm_status rtm_write_json	(	rtm_client_t *	rtm,
		const char *	key,
		const char *	json,
		unsigned *	ack_id
	)

Write the well-formed JSON value to a specific channel.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	key	name of the channel
[in]	json	message
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes; rtm_publish_json

§ rtm_write_string()

RTM_API rtm_status rtm_write_string	(	rtm_client_t *	rtm,
		const char *	key,
		const char *	string,
		unsigned *	ack_id
	)

Write the string value to a specific channel.

RTM reply will have same identifier as value of ack_id. If ack_id is null then no reply from RTM is sent.

Parameters

[in]	rtm	instance of the client
[in]	key	name of the channel
[in]	string	the message to send.
[out]	ack_id	(optional) the id of the message sent.

Returns: the status of the operation

Return values

RTM_OK	operation succeeded
RTM_ERR_*	an error occurred

See also: rtm_status for detailed error codes; rtm_publish_string

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

§ RTM_CLIENT_SIZE_WITH_BUFFERS

Typedef Documentation

§ rtm_free_fn_t

§ rtm_malloc_fn_t

§ rtm_message_handler_t

§ rtm_pdu_handler_t

§ rtm_pdu_t

Enumeration Type Documentation

§ rtm_status

Function Documentation

§ rtm_authenticate()

§ rtm_close()

§ rtm_connect()

§ rtm_connect_via_https_proxy()

§ rtm_default_error_logger()

§ rtm_default_message_handler()

§ rtm_default_pdu_handler()

§ rtm_delete()

§ rtm_disable_verbose_logging()

§ rtm_enable_verbose_logging()

§ rtm_error_string()

§ rtm_get_fd()

§ rtm_get_user_context()

§ rtm_get_ws_ping_interval()

§ rtm_handshake()

§ rtm_init()

§ rtm_init_ex()

§ rtm_null_malloc()

§ rtm_parse_pdu()

§ rtm_poll()

§ rtm_publish_json()

§ rtm_publish_string()

§ rtm_read()

§ rtm_read_with_body()

§ rtm_send_pdu()

§ rtm_send_ws_ping()

§ rtm_set_allocator()

§ rtm_set_connection_timeout()

§ rtm_set_raw_pdu_handler()

§ rtm_set_ws_ping_interval()

§ rtm_subscribe()

§ rtm_subscribe_with_body()

§ rtm_unsubscribe()

§ rtm_wait()

§ rtm_wait_timeout()

§ rtm_write_json()

§ rtm_write_string()