data_service

data_service.h

Sifli Data service interface.

Author: Sifli software development team

Unnamed Group

DATA_CLIENT_INVALID_HANDLE: Invalid data client handle

GET_MSG_ID(msg_id)

IS_RSP_MSG(msg_id)

RSP_MSG_TYPE

DATA_SVC_THREAD_MB: Data service mailbox thread ID

DATA_SVC_THREAD_PROC: Data service internal process thread ID

SHORT_DATA_MSG_BODY_THRESHOLD

enum [anonymous]

Values:

enumerator MSG_SERVICE_SUBSCRIBE_REQ

enumerator MSG_SERVICE_SUBSCRIBE_RSP

enumerator MSG_SERVICE_UNSUBSCRIBE_REQ

enumerator MSG_SERVICE_UNSUBSCRIBE_RSP

enumerator MSG_SERVICE_CONFIG_REQ

enumerator MSG_SERVICE_CONFIG_RSP

enumerator MSG_SERVICE_TX_REQ

enumerator MSG_SERVICE_TX_RSP

enumerator MSG_SERVICE_RX_REQ

enumerator MSG_SERVICE_RX_RSP

enumerator MSG_SERVICE_PROXY_IND

enumerator MSG_SERVICE_START_REQ

enumerator MSG_SERVICE_START_RSP

enumerator MSG_SERVICE_STOP_REQ

enumerator MSG_SERVICE_STOP_RSP

enumerator MSG_SERVICE_DATA_RDY_IND

enumerator MSG_SERVICE_DATA_NTF_IND

enumerator MSG_SERVICE_PING_REQ

enumerator MSG_SERVICE_PING_RSP

enumerator MSG_SERVICE_SLEEP_REQ

enumerator MSG_SERVICE_SLEEP_RSP

enumerator MSG_SERVICE_SYS_ID_END

enumerator MSG_SERVICE_CUSTOM_ID_BEGIN

typedef uint8_t datac_handle_t

typedef struct data_callback_arg_tag data_callback_arg_t

typedef int (*data_callback_t)(data_callback_arg_t *arg)

Functions

int datas_start(data_service_init_param_t *init_param)

Start data service framework.

返回值:: success – 0. failure: other value

uint8_t *data_service_init_msg(data_msg_t *msg, uint16_t msg_id, uint16_t body_len)

Initialize data service message.

参数:

msg – [inout] Message pointer to be initialized
msg_id – [in] Message id
body_len – [in] Size of message body

返回值:

Pointer – to message body.

void data_service_deinit_msg(data_msg_t *msg)

Free data service message.

no need to call it if msg is sent by data service API, such as datac_send_msg and datac_tx

参数:

msg – [in] Message pointer to be freed

返回:

void

uint8_t *data_service_get_msg_body(data_msg_t *msg)

Get message body.

参数:

msg – [in] Message pointer

返回值:

Pointer – to message body.

void data_service_entry(void *queue)

service data process entry

参数:

queue – [in] queue

void *data_service_get_thread(uint8_t ds_id)

Get data service thread object.

参数:

ds_id – [in] service id, see DATA_SVC_THREAD_XXX

返回值:

RTOS – Thread object, currently type of rt_thread_t.

struct data_callback_arg_tag

Public Members

uint16_t msg_id: Message ID, see MSG_SERVICE_XXX

uint16_t data_len: Parameter length

uint8_t *data: Parameter for message, see data_xxx_t

uint32_t user_data: User provided context when subscribing

struct data_subscribe_req_t

#include <data_service.h>

Parameter for MSG_SERVICE_SUBSCRIBE_REQ.

Public Members

char service_name[0]

struct data_subscribe_rsp_t

#include <data_service.h>

MSG_SERVICE_SUBSCRIBE_RSP body structure.

Public Members

int32_t result

datac_handle_t handle

struct data_req_t

#include <data_service.h>

Parameter for other request messages.

Public Members

uint16_t len

uint8_t data[0]

struct data_rsp_t

#include <data_service.h>

Parameter for response messages.

Public Members

int32_t result

struct data_rdy_ind_t

#include <data_service.h>

Parameter for MSG_SERVICE_DATA_RDY_IND.

Public Members

uint32_t len

uint8_t *data

struct data_msg_t

#include <data_service.h>

data service message structure type

Public Members

uint16_t src_cid

uint16_t dst_cid

uint16_t msg_id: Message ID, see MSG_SERVICE_XXX

uint16_t len: Parameter length

uint32_t no_free: 1: no need to free memory of long msg, 0: need to free memory of long msg

uint32_t reserved

uint8_t body[(12)]: Saving whole short msg body, which length <= SHORT_DATA_MSG_BODY_THRESHOLD. For long msg body which length > SHORT_DATA_MSG_BODY_THRESHOLD, we’ll allocate a memroy from heap and save a pointer here.

struct data_service_init_param_t

Public Members

uint16_t mbox_thread_stack_size: mbox thread stack size in byte

void *mbox_thread_stack: mbox thread stack buffer, if not specified, allocated interanlly

uint8_t mbox_thread_priority: mbox thread thread priority

uint16_t proc_thread_stack_size: proc thread stack size in byte

void *proc_thread_stack: proc thread stack buffer, if not specified, allocated interanlly

uint8_t proc_thread_priority: proc thread thread priority

data_service_provider.h

Sifli Data service provider interface.

Author: Sifli software development team

Unnamed Group

DATA_SERVICE_INVALID_ID

datas_push_data_to_client(service, len, data)

datas_ind_size(service, size)

typedef void *datas_handle_t: Data service client

typedef int32_t (*data_service_msg_handler_t)(datas_handle_t service, data_msg_t *msg): service message handler

typedef bool (*data_filter_t)(data_req_t *config, uint16_t msg_id, uint32_t len, uint8_t *data)

typedef struct data_service_config_tag data_service_config_t

int32_t datas_push_msg_to_client(datas_handle_t service, uint16_t msg_id, uint32_t len, uint8_t *data)

Trigger service main thread to send customer message to the subscriber.

参数:

service – [in] Handle of data service
msg_id – [in] Message id
len – [in] Size of data available
data – [in] content of data

返回值:

RT_EOK – if successful, otherwise return error number < 0.

int32_t datas_push_msg_to_client_no_copy(datas_handle_t svc, uint16_t msg_id, uint32_t len, uint8_t *data)

Trigger service main thread to send customer message to the subscriber,.

data is not copied and accessed directly by client if serivce and client are in the same core. Service cannot free data after this function call as it would be used by client. If service and client are in different core, the message is relayed to the client side, i.e. client would use a copy of data. So data can be freed after this function call.

参数:

svc – [in] Handle of data service
msg_id – [in] Message id
len – [in] Size of data available
data – [in] content of data

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datas_data_ready(datas_handle_t service, uint32_t size, uint8_t *data)

Inform service that data is available to.

参数:

service – [in] Handle of data service
size – [in] size of data in bytes available to service.
data – [in] point to data, the pointer is carried by message MSG_SERVICE_DATA_RDY_IND, so the receiver is responsible to free the memory

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datas_send_response(datas_handle_t service, data_msg_t *msg_req, rt_err_t result)

Send response message to req message.

参数:

service – [in] Handle of data service
msg_req – [in] Request message to respond
result – [in] Result of response

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datas_send_response_data(datas_handle_t service, data_msg_t *msg_req, uint32_t len, uint8_t *data)

Send response message to req message.

参数:

service – [in] Handle of data service
msg_req – [in] Request message to respond
len – [in] Size of data available
data – [in] content of data

返回值:

RT_EOK – if successful, otherwise return error number < 0.

datas_handle_t datas_register(const char *name, data_service_config_t *config)

参数:

name – [in] Name of data service
config – [in] Data service config

返回值:

Service – handle.

struct data_service_config_tag

Public Members

uint8_t max_client_num: maximum client number supported by the serivce

rt_mq_t queue

message queue used by the service,

If it’s NULL, the service shares the system queue and thread. If it’s not NULL, the message would be posted to this queue, so service should create its own thread and retrieve message from this queue. For simlicity the user created thread could use data_service_entry as thread entry and pass the queue as thread’s parameter, such as rt_thread_init(&thread_handle, "test", data_service_entry, queue, thread_stack, sizeof(thread_stack), 25, 10);

data_filter_t data_filter: filter which is called to check whether one message needs to be pushed to the client

data_service_msg_handler_t msg_handler: service message handler

data_service_subscriber.h

Sifli Data service subscriber interface.

Author: Sifli software development team

Defines

datac_subscribe(handle, service_name, cbk, user_data)

Subscribe to service.

参数:

handle – [in] Handle of data service
service_name – [in] Service name
cbk – [in] Callbacks to handel data service
user_data – [in] Callbacks context, transparent to service provider.

返回值:

void –

datac_unsubscribe(handle)

Unsubscribe to service.

参数:

handle – [in] Handle of data service

返回值:

RT_EOK – if successful, otherwise return error number < 0.

Typedefs

typedef struct data_service_mq_tag data_service_mq_t: Data service

Functions

datac_handle_t datac_open(void)

Allocate data client handle.

返回:: data client handle

rt_err_t datac_close(datac_handle_t handle)

Close data client handle.

If service is subscribed by the handle, it’s unsubscribed autuomatically

参数:

handle – [in] Handle of data service

返回值:

RT_EOK – if successful, otherwise return error number < 0.

void datac_subscribe_ex(datac_handle_t handle, char *service_name, data_callback_t cbk, uint32_t user_data, rt_mq_t mq)

Subscribe to service.

参数:

handle – [in] Handle of data service
service_name – [in] Service name
cbk – [in] Callbacks to handel data service
user_data – [in] Callbacks context, transparent to service provider.
mq – [in] instead of callback directly, send message to mq to issue callback from different task.

返回值:

void –

rt_err_t datac_unsubscribe_ex(datac_handle_t handle, bool force)

Unsubscribe to service.

参数:

handle – [in] Handle of data service
force – [in] if true, will immediatly stop all callbacks to subscriber, including unsubscribe response.

返回值:

RT_EOK – if successful, otherwise return error number < 0.

void datac_delayed_usr_cbk(data_service_mq_t *arg_msg)

Delayed subscriber call back, this will trigger subscriber callback from user defined task.

参数:

arg_msg – [in] msg

rt_err_t datac_config(datac_handle_t handle, uint16_t len, uint8_t *config)

Configure the specific data provider,.

备注

data provider will decide which config will be used compare to existing configs.

参数:

handle – [in] Handle of data service
len – [in] Length of config
config – [in] Configuration content

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datac_send_msg(datac_handle_t handle, data_msg_t *msg)

Send message to service provider.

参数:

handle – [in] Handle of data service
msg – [in] Message send to service provider

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datac_tx(datac_handle_t handle, uint16_t len, uint8_t *data)

Send data to service provider.

参数:

handle – [in] Handle of data service
len – [in] Length of data
data – [in] service data content

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datac_rx(datac_handle_t handle, uint16_t len, uint8_t *data)

Read data from service provider.

参数:

handle – [in] Handle of data service
len – [in] Length of data
data – [inout] service data content readback

返回值:

RT_EOK – if successful, otherwise return error number < 0.

rt_err_t datac_ping(datac_handle_t handle, uint8_t mode)

ping device from service provider

参数:

handle – [in] Handle of data service
mode – [in] ping mode

返回值:

RT_EOK – if successful, otherwise return error number < 0.

struct data_service_mq_tag

#include <data_service_subscriber.h>

Data service

Public Members

data_callback_t callback

data_callback_arg_t arg

ui_datasrv_subscriber.h

Data service client for GUI application. It helps isolate GUI application thread from data service running.

Author: Sifli software development team

Functions

void ui_datac_init(void): Initialize GUI data service client module.

datac_handle_t ui_datac_subscribe(datac_handle_t handle, char *name, data_callback_t cbk, uint32_t user_data)

Subscribe data service in GUI thread context.

参数:

handle – [in] data client handle
name – [in] Data service name
cbk – [in] Callback functions for data service.
user_data – [in] Callback function parameter. Service provide will call callback with it.

返回值:

Pointer – to message body.