Core S2C library functions. More...

Functions

zos_result_t s2c_init (const s2c_config_t config)
 Initialize the S2C library. More...
 
void s2c_deinit (void)
 De-initialize the S2C library. More...
 
const void * s2c_get_setting (s2c_setting_t setting)
 Return the value of a S2C library setting. More...
 
zos_result_t s2c_set_setting (s2c_setting_t setting, const void *value)
 Set the value of a S2C library setting. More...
 
zos_result_t s2c_start_server (zos_interface_t interface)
 Start the local server to which one or more Mobiles connect. More...
 
zos_result_t s2c_stop_server (zos_interface_t interface)
 Stop the local server. More...
 
zos_result_t s2c_open_cloud_connection (const char *url_str, const char *cert_filename)
 Open a connection to the S2C cloud connector. More...
 
zos_result_t s2c_close_cloud_connection (void)
 Close connection to cloud. More...
 
zos_result_t s2c_write_stream (const char *stream, const void *data, uint16_t length, zos_bool_t last_write)
 Write stream data to all listening Mobiles and Cloud. More...
 
zos_result_t s2c_write_stream_str (const char *stream, const char *str)
 Write string data to all listening Mobiles and Cloud. More...
 
zos_result_t s2c_register_listener (const char *stream, s2c_stream_listener_t listener, void *arg)
 Register a listener for incoming stream data. More...
 
zos_result_t s2c_unregister_listener (const char *stream)
 Unregister a listener for incoming stream data. More...
 
zos_result_t s2c_request_stream_data (const char *stream)
 Request a streams current value from the cloud. More...
 
uint8_t s2c_get_connection_count (void)
 Return the number of connected Mobiles. More...
 
zos_bool_t s2c_cloud_connection_is_active (void)
 Return if the connected to the cloud. More...
 
s2c_status_flag_t s2c_get_status_flags (void)
 Get the current status of the S2C device. More...
 
zos_result_t s2c_get_mobile_client_list (s2c_mobile_client_info_t **client_list_ptr)
 Return list of connected Mobile clients. More...
 
zos_result_t s2c_allow_mobile_client_guests (uint32_t timeout)
 Temporarily allow guest connections for timeout seconds. More...
 
zos_result_t s2c_revoke_mobile_client_guest (uint8_t client_number)
 Revoke 'guest' mobile client's permissions. More...
 

Detailed Description

Core S2C library functions.

Function Documentation

zos_result_t s2c_allow_mobile_client_guests ( uint32_t  timeout)

Temporarily allow guest connections for timeout seconds.

When invoked, this API allows 'guest' mobile client connections for timeout seconds. A 'guest' mobile client may connect and securely issue restricted commands/streams/files like the owner of the device.

Note
The s2c_flag_t S2C_FLAG_GUEST_VERIFCAITON_REQUIRED should be set to ensure the mobile is verified by the cloud before connecting as a guest. If this flag is not set then any local mobile clients may connect. In this case not internet connection is required.

If S2C_FLAG_GUESTS_ALWAYS_ALLOWED is used then this API is not needed as guest connections are always allowed.

Parameters
timeoutTime in seconds to allow guest connections
Returns
zos_result_t The result of the API call
zos_result_t s2c_close_cloud_connection ( void  )

Close connection to cloud.

This closed the websocket connection to the cloud.

Returns
zos_result_t The result of the API call
zos_bool_t s2c_cloud_connection_is_active ( void  )

Return if the connected to the cloud.

Returns
ZOS_TRUE if connected to cloud, ZOS_FALSE else
void s2c_deinit ( void  )

De-initialize the S2C library.

This should be called on ZAP shutdown.

uint8_t s2c_get_connection_count ( void  )

Return the number of connected Mobiles.

Returns
The number of locally connected Mobiles
zos_result_t s2c_get_mobile_client_list ( s2c_mobile_client_info_t **  client_list_ptr)

Return list of connected Mobile clients.

This returns a linked-list of s2c_mobile_client_info_t objects. The linked-list should be freed using zn_free_linked_list()

Parameters
client_list_ptrPointer to hold reference to linked-list of s2c_mobile_client_info_t
Returns
zos_result_t The result of the API call
const void* s2c_get_setting ( s2c_setting_t  setting)

Return the value of a S2C library setting.

Parameters
settingThe key of the corresponding setting, see s2c_setting_t
Returns
The value of the setting
s2c_status_flag_t s2c_get_status_flags ( void  )

Get the current status of the S2C device.

Returns
bitmask of status flags, see s2c_status_flag_t
zos_result_t s2c_init ( const s2c_config_t  config)

Initialize the S2C library.

This should be called on ZAP startup. The supplied s2c_config_t should contain pointers/values for the S2C libraries internal settings. If a settings isn't used leave as NULL.

Parameters
configArray of pointers/values for library configuration, see s2c_config_t
Returns
zos_result_t The result of the API call.
zos_result_t s2c_open_cloud_connection ( const char *  url_str,
const char *  cert_filename 
)

Open a connection to the S2C cloud connector.

This opens a websocket connection to the cloud. The device must first have a valid cloud token before issuing this API call. If cloud token must be set either during s2c_init() or s2c_set_setting() using the S2C_SETTING_CLOUD_TOKEN setting.

Upon opening the websocket connection, the cloud validates the token. If the token is invalid then ZOS_INVALID_TOKEN is returned. The device should stop trying to connect and obtain a new token if this result is returned.

Parameters
url_strThe host URL of cloud (e.g. wss://mycloud.com)
cert_filenameOptional TLS certificate filename used to create a secure connection to the cloud
Returns
zos_result_t The result of the API call
zos_result_t s2c_register_listener ( const char *  stream,
s2c_stream_listener_t  listener,
void *  arg 
)

Register a listener for incoming stream data.

This registers a callback which is executed when the corresponding stream receives data from either the cloud or Mobile. Refer to s2c_stream_listener_t for more information on how the callback works.

Use s2c_unregister_listener() to remove the listener.

Note
The registered listener executes in the Zap event thread context.
Parameters
streamName of stream to listen for incoming data
listenerCallback to be executed when stream receives data
argOptional argument to pass to callback
Returns
zos_result_t The result of the API call
zos_result_t s2c_request_stream_data ( const char *  stream)

Request a streams current value from the cloud.

This retrieves the latest value the cloud currently has stored for the corresponding stream. This is typically used after opening a cloud connection to update the device's output components to their correct value.

Note
A cloud connection must be opened before calling this API
Parameters
streamName of the stream for which to retrieve latest value from cloud, leave NULL to request all registered streams
Returns
zos_result_t The result of the API call
zos_result_t s2c_revoke_mobile_client_guest ( uint8_t  client_number)

Revoke 'guest' mobile client's permissions.

This disables a guest mobile client for accessing the device. Once revoked, the guest mobile client will have to redo the guest handshake sequence.

Parameters
client_numberThe guest mobile client's number
Returns
zos_result_t The result of the API call
zos_result_t s2c_set_setting ( s2c_setting_t  setting,
const void *  value 
)

Set the value of a S2C library setting.

Parameters
settingThe key of the corresponding setting, see s2c_setting_t
valueThe next value of the setting
Returns
zos_result_t The result of the API call.
zos_result_t s2c_start_server ( zos_interface_t  interface)

Start the local server to which one or more Mobiles connect.

This starts the local server on the specified network interface. If the network is up, it will bring the network up first before starting the server.

Parameters
interfacezos_interface_t, The network interface on which to run the S2C Mobile server
Returns
zos_result_t The result of the API call.
zos_result_t s2c_stop_server ( zos_interface_t  interface)

Stop the local server.

This stop the local server. All open Mobile clients connections are closed first.

Parameters
interfacezos_interface_t, use ZOS_ANY_INTERFACE to stop regardless of interface
Returns
zos_result_t The result of the API call
zos_result_t s2c_unregister_listener ( const char *  stream)

Unregister a listener for incoming stream data.

This removes a listener registered by s2c_register_listener()

Parameters
streamName of the stream for which to remove the listener
Returns
zos_result_t The result of the API call
zos_result_t s2c_write_stream ( const char *  stream,
const void *  data,
uint16_t  length,
zos_bool_t  last_write 
)

Write stream data to all listening Mobiles and Cloud.

This will write stream data to:

  • The cloud if the connection is opened
  • Mobiles if the Mobile registered a listener (this is a different listener than s2c_register_listener())

This API allows for writing stream data all at once or in chunks. To write stream data all at once, supply:

  • stream - The name of the stream
  • data - Pointer to buffer containing stream data
  • length - The length of the buffer
  • last_write - ZOS_TRUE

To write stream data in chunks, this API must be called two or more times. The first time, supply:

  • stream - The name of the stream
  • data - NULL
  • length - The total length of all the data chunks to write
  • last_write - ZOS_FALSE

Subsequent calls, supply:

  • stream - The name of the stream (optional)
  • data - Pointer to buffer containing stream data chunk
  • length - The length of the data chunk
  • last_write - ZOS_FALSE if more writes to follow, ZOS_TRUE else
Parameters
streamThe name of the data stream to write
dataPointer to data buffer
lengthLength of data buffer
last_writeZOS_TRUE if no more writes to follow, ZOS_FALSE if final write
Returns
zos_result_t The result of the API call
zos_result_t s2c_write_stream_str ( const char *  stream,
const char *  str 
)

Write string data to all listening Mobiles and Cloud.

This will write string data to:

  • The cloud if the connection is opened
  • Mobiles if the Mobile registered a listener (this is a different listener than s2c_register_listener())
Note
The string is written all at once (chunking not supported, s2c_write_stream() )
Parameters
streamThe name of the stream to write
strNull-terminated string to write
Returns
zos_result_t The result of the API call