Wirepas SDK
shared_data.h File Reference

Detailed Description

Helper library to share send and receive functions/callback between multiple modules in the application.

This library replaces the following functions and callbacks of the data library:

SHARED_DATA_MAX_TRACKED_PACKET defines the maximum number of sent packets that can be tracked at the same time. It defaults to 16. It can be redefined in the application makefile with the drawback of using more RAM.

Definition in file shared_data.h.

Go to the source code of this file.

Typedefs

typedef app_lib_data_receive_res_e(* shared_data_received_cb_f) (const shared_data_item_t *item, const app_lib_data_received_t *data)
 The data reception callback. More...
 

Functions

app_res_e Shared_Data_init (void)
 Initialize the shared data library. More...
 
app_res_e Shared_Data_addDataReceivedCb (shared_data_item_t *item)
 Add a new packet received item to the list. If the item is already in the list it is only updated. More...
 
app_res_e Shared_Data_readyToReceive (shared_data_item_t *item)
 Enable back the reception for an item. Reception is automatically paused when an item returns APP_LIB_DATA_RECEIVE_RES_NO_SPACE from its registered callback shared_data_received_cb_f Only way to allow the reception is to call this function. More...
 
void Shared_Data_removeDataReceivedCb (shared_data_item_t *item)
 Remove a received packet item from the list. Removed item fields are all set to 0. More...
 
app_lib_data_send_res_e Shared_Data_sendData (app_lib_data_to_send_t *data, app_lib_data_data_sent_cb_f sent_cb)
 Send data. The packet to send is represented as a app_lib_data_to_send_t struct. More...
 

Data Structures

struct  shared_data_filter_t
 Structure holding all parameters for packet filtering. More...
 
struct  shared_data_item_t
 Item containing filters and callback to call. This structure describe a callback to call when a packet is received if it is allowed by the associated filter. More...
 

Enumerations

enum  shared_data_net_mode_e { SHARED_DATA_NET_MODE_UNICAST = 0, SHARED_DATA_NET_MODE_BROADCAST = 1, SHARED_DATA_NET_MODE_MULTICAST = 2, SHARED_DATA_NET_MODE_ALL = 3 }
 Select what type of packet to receive. More...
 

Macros

#define SHARED_DATA_UNUSED_ENDPOINT   -1
 
#define SHARED_DATA_UNUSED_MULTISCAST   0xFFFFFFFF
 

Typedef Documentation

◆ shared_data_received_cb_f

typedef app_lib_data_receive_res_e(* shared_data_received_cb_f) (const shared_data_item_t *item, const app_lib_data_received_t *data)

The data reception callback.

This is the callback called when a packet is received (and allowed). The received packet is represented as a pointer to app_lib_data_received_t struct.

Parameters
itemPointer to the filter item that initiated the callback.
dataPointer to the received data.
Returns
Result code, app_lib_data_receive_res_e.
Note
If APP_LIB_DATA_RECEIVE_RES_NO_SPACE is returned, the whole data is blocked for all the app. App will start receiving data once this filter has called Shared_Data_readyToReceive

Definition at line 96 of file shared_data.h.

Function Documentation

◆ Shared_Data_addDataReceivedCb()

app_res_e Shared_Data_addDataReceivedCb ( shared_data_item_t *  item)

Add a new packet received item to the list. If the item is already in the list it is only updated.

Parameters
itemNew item (callback + filter)
Returns
APP_RES_OK if ok. See app_res_e for other result codes.
Examples
custom_app/app.c, and shared_data/app.c.

◆ Shared_Data_init()

app_res_e Shared_Data_init ( void  )

Initialize the shared data library.

Note
This function is automatically called if library is enabled.
If Shared data module is used in application, the lib_data->setDataReceivedCb(), lib_data->setDataSentCb() and lib_data->sendData() functions offered by data library MUST NOT be used outside of this module.
Returns
APP_RES_OK.

◆ Shared_Data_readyToReceive()

app_res_e Shared_Data_readyToReceive ( shared_data_item_t *  item)

Enable back the reception for an item. Reception is automatically paused when an item returns APP_LIB_DATA_RECEIVE_RES_NO_SPACE from its registered callback shared_data_received_cb_f Only way to allow the reception is to call this function.

Note
Reception is paused for all items at the same time. All the items that pause the reception must explicitly reanable it. Otherwise reception will stay in pause mode. In fact, in pause mode messages are buffered on stack side and cannot be accepted individually based on filter set.
Parameters
itemItem that is now ready
Returns
APP_RES_OK if ok. See app_res_e for other result codes.
Examples
shared_data/app.c.

◆ Shared_Data_removeDataReceivedCb()

void Shared_Data_removeDataReceivedCb ( shared_data_item_t *  item)

Remove a received packet item from the list. Removed item fields are all set to 0.

Parameters
itemitem to remove.

◆ Shared_Data_sendData()

app_lib_data_send_res_e Shared_Data_sendData ( app_lib_data_to_send_t data,
app_lib_data_data_sent_cb_f  sent_cb 
)

Send data. The packet to send is represented as a app_lib_data_to_send_t struct.

Parameters
dataData to send
sent_cbCallback function to be called when a packet has gone through local processing and has finally been sent or discarded. If NULL is passed, the callback is disabled. This callback replaces APP_LIB_DATA_SEND_FLAG_TRACK flag of data structure.
Returns
Result code, APP_LIB_DATA_SEND_RES_SUCCESS means that data was accepted for sending. See app_res_e for other result codes.
Examples
appconfig/app.c, custom_app/app.c, and shared_data/app.c.

Data Structure Documentation

◆ shared_data_filter_t

struct shared_data_filter_t

Structure holding all parameters for packet filtering.

Definition at line 52 of file shared_data.h.

Data Fields
int16_t dest_endpoint

Expected destination endpoint. valid range [0;255], -1: No filtering by destination endpoint.

shared_data_net_mode_e mode

Types of packet received (only for received packets).

app_lib_settings_is_group_cb_f multicast_cb

Will be called when multicast packet is received. Return true to accept packet. If NULL, all multicast packets are accepted. Only used with mode SHARED_DATA_NET_MODE_MULTICAST or SHARED_DATA_NET_MODE_ALL. Otherwise Shared_Data_addDataReceivedCb return APP_RES_INVALID_VALUE. This callback can be called two times for each received multicastpacket so its execution time must be kept short.

int16_t src_endpoint

Expected source endpoint. valid range [0;255], -1: No filtering by source endpoint.

◆ shared_data_item_s

struct shared_data_item_s

Item containing filters and callback to call. This structure describe a callback to call when a packet is received if it is allowed by the associated filter.

Forward declaration of shared_data_item_t.

Definition at line 104 of file shared_data.h.

Data Fields
shared_data_received_cb_f cb

Function to call if the received packet is allowed.

shared_data_filter_t filter

Packet filter parameters.

void * reserved

Reserved for sl_list use (DO NOT MODIFY).

bool reserved2

Reserved for shared_data use (DO NOT MODIFY).

bool reserved3

Reserved for built-in pause mechanism (DO NOT MODIFY).

Enumeration Type Documentation

◆ shared_data_net_mode_e

Select what type of packet to receive.

Enumerator
SHARED_DATA_NET_MODE_UNICAST 

Only receive Unicast packets.

SHARED_DATA_NET_MODE_BROADCAST 

Only receive Broadcast packets.

SHARED_DATA_NET_MODE_MULTICAST 

Only receive Multicast packets.

SHARED_DATA_NET_MODE_ALL 

Accept all type of packets (ignore filtering packet by type).

Definition at line 39 of file shared_data.h.

Macro Definition Documentation

◆ SHARED_DATA_UNUSED_ENDPOINT

#define SHARED_DATA_UNUSED_ENDPOINT   -1

Value if Endpoint filtering is not used.

Examples
shared_data/app.c.

Definition at line 33 of file shared_data.h.

◆ SHARED_DATA_UNUSED_MULTISCAST

#define SHARED_DATA_UNUSED_MULTISCAST   0xFFFFFFFF

Value if multicast group filtering is not used.

Definition at line 36 of file shared_data.h.

shared_data_net_mode_e
shared_data_net_mode_e
Select what type of packet to receive.
Definition: shared_data.h:39
SHARED_DATA_NET_MODE_ALL
@ SHARED_DATA_NET_MODE_ALL
Definition: shared_data.h:48
SHARED_DATA_NET_MODE_MULTICAST
@ SHARED_DATA_NET_MODE_MULTICAST
Definition: shared_data.h:46
SHARED_DATA_NET_MODE_UNICAST
@ SHARED_DATA_NET_MODE_UNICAST
Definition: shared_data.h:42
SHARED_DATA_NET_MODE_BROADCAST
@ SHARED_DATA_NET_MODE_BROADCAST
Definition: shared_data.h:44