le_dcs API Reference

Data Structures

struct  le_dcs_ChannelInfo_t
 

Files

file  le_dcs_common.h
 
file  le_dcs_interface.h
 

Macros

#define LE_DCS_INTERFACE_NAME_MAX_LEN   100
 
#define LE_DCS_CHANNEL_NAME_MAX_LEN   32
 
#define LE_DCS_IPADDR_MAX_LEN   46
 
#define LE_DCS_CHANNEL_LIST_QUERY_MAX   36
 
#define LE_DCS_CHANNEL_LIST_ENTRY_MAX   80
 

Typedefs

typedef struct le_dcs_ReqObj * le_dcs_ReqObjRef_t
 
typedef struct le_dcs_Channel * le_dcs_ChannelRef_t
 
typedef struct le_dcs_EventHandler * le_dcs_EventHandlerRef_t
 
typedef void(* le_dcs_EventHandlerFunc_t) (le_dcs_ChannelRef_t channelRef, le_dcs_Event_t event, int32_t code, void *contextPtr)
 
typedef void(* le_dcs_GetChannelsHandlerFunc_t) (le_result_t result, const le_dcs_ChannelInfo_t *channelListPtr, size_t channelListSize, void *contextPtr)
 
typedef void(* le_dcs_DisconnectHandler_t) (void *)
 

Enumerations

enum  le_dcs_Technology_t {
  LE_DCS_TECH_UNKNOWN = 0, LE_DCS_TECH_WIFI = 1, LE_DCS_TECH_CELLULAR = 2, LE_DCS_TECH_ETHERNET = 3,
  LE_DCS_TECH_MAX = 4
}
 
enum  le_dcs_State_t { LE_DCS_STATE_DOWN = 0, LE_DCS_STATE_UP = 1 }
 
enum  le_dcs_Event_t { LE_DCS_EVENT_DOWN = 0, LE_DCS_EVENT_UP = 1, LE_DCS_EVENT_TEMP_DOWN = 2 }
 

Functions

void le_dcs_ConnectService (void)
 
le_result_t le_dcs_TryConnectService (void)
 
LE_FULL_API void le_dcs_SetServerDisconnectHandler (le_dcs_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_dcs_DisconnectService (void)
 
le_dcs_EventHandlerRef_t le_dcs_AddEventHandler (le_dcs_ChannelRef_t channelRef, le_dcs_EventHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_dcs_RemoveEventHandler (le_dcs_EventHandlerRef_t handlerRef)
 
le_dcs_Technology_t le_dcs_GetTechnology (le_dcs_ChannelRef_t channelRef)
 
le_result_t le_dcs_GetState (le_dcs_ChannelRef_t channelRef, le_dcs_State_t *statePtr, char *interfaceName, size_t interfaceNameSize)
 
le_dcs_ReqObjRef_t le_dcs_Start (le_dcs_ChannelRef_t channelRef)
 
le_result_t le_dcs_Stop (le_dcs_ReqObjRef_t reqRef)
 
le_dcs_ChannelRef_t le_dcs_GetReference (const char *LE_NONNULL name, le_dcs_Technology_t technology)
 
void le_dcs_GetChannels (le_dcs_GetChannelsHandlerFunc_t handlerPtr, void *contextPtr)
 

Detailed Description

Macro Definition Documentation

◆ LE_DCS_CHANNEL_LIST_QUERY_MAX

#define LE_DCS_CHANNEL_LIST_QUERY_MAX   36

Max # of channel list entries for a query: CHANNEL_LIST_QUERY_MAX is for per-technology, while CHANNEL_LIST_ENTRY_MAX is for all channels of all supported technologies. Currently, the former one's value is set to the max value supported by cellular. The latter is set to 2 times of that to support wifi. The extra 8 is for ethernet. When more technologies are supported, this value needs to be raised accordingly.

◆ LE_DCS_CHANNEL_NAME_MAX_LEN

#define LE_DCS_CHANNEL_NAME_MAX_LEN   32

Channel name string length.

◆ LE_DCS_INTERFACE_NAME_MAX_LEN

#define LE_DCS_INTERFACE_NAME_MAX_LEN   100

Interface name string length.

◆ LE_DCS_IPADDR_MAX_LEN

#define LE_DCS_IPADDR_MAX_LEN   46

IP addr string's max length

Typedef Documentation

◆ le_dcs_ChannelRef_t

typedef struct le_dcs_Channel* le_dcs_ChannelRef_t

Reference to a data channel

◆ le_dcs_DisconnectHandler_t

typedef void(* le_dcs_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

◆ le_dcs_EventHandlerFunc_t

typedef void(* le_dcs_EventHandlerFunc_t) (le_dcs_ChannelRef_t channelRef, le_dcs_Event_t event, int32_t code, void *contextPtr)

Handler for channel state changes

◆ le_dcs_EventHandlerRef_t

typedef struct le_dcs_EventHandler* le_dcs_EventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_dcs_Event'

◆ le_dcs_GetChannelsHandlerFunc_t

typedef void(* le_dcs_GetChannelsHandlerFunc_t) (le_result_t result, const le_dcs_ChannelInfo_t *channelListPtr, size_t channelListSize, void *contextPtr)

Handler for the receiving the results of a channel list query

◆ le_dcs_ReqObjRef_t

typedef struct le_dcs_ReqObj* le_dcs_ReqObjRef_t

Reference returned by Request function and used by Release function

Enumeration Type Documentation

◆ le_dcs_Event_t

Channel events: These are the data channel events in DCS' northbound towards client apps.

The LE_DCS_EVENT_UP event for a given data channel means that it has been brought up and become usable.

The LE_DCS_EVENT_DOWN event means that the given data channel has gone down, been disassociated from all the client apps which have called le_dcs_Start() to start it, and its technology has stopped to retry reconnecting it back further.

The LE_DCS_EVEN_TEMP_DOWN event means, on the other hand, that the given data channel has temporarily gone down, but remains associated with those client apps which have called le_dcs_Start() to start but not yet le_dcs_Stop() to stop it, and its technology will continue to retry reconnecting it back after some backoff.

◆ le_dcs_State_t

Channel states.

◆ le_dcs_Technology_t

Technologies.

Enumerator
LE_DCS_TECH_WIFI 

Wi-Fi.

LE_DCS_TECH_CELLULAR 

Cellular.

LE_DCS_TECH_ETHERNET 

Ethernet.

LE_DCS_TECH_MAX 

Unknown state.

Function Documentation

◆ le_dcs_AddEventHandler()

le_dcs_EventHandlerRef_t le_dcs_AddEventHandler ( le_dcs_ChannelRef_t  channelRef,
le_dcs_EventHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Reference returned by Request function and used by Release function Reference to a data channel Technologies. Channel states. Channel events: These are the data channel events in DCS' northbound towards client apps.

The LE_DCS_EVENT_UP event for a given data channel means that it has been brought up and become usable.

The LE_DCS_EVENT_DOWN event means that the given data channel has gone down, been disassociated from all the client apps which have called le_dcs_Start() to start it, and its technology has stopped to retry reconnecting it back further.

The LE_DCS_EVEN_TEMP_DOWN event means, on the other hand, that the given data channel has temporarily gone down, but remains associated with those client apps which have called le_dcs_Start() to start but not yet le_dcs_Stop() to stop it, and its technology will continue to retry reconnecting it back after some backoff. Handler for channel state changes Reference type used by Add/Remove functions for EVENT 'le_dcs_Event' This is the structure with info about each available channel Handler for the receiving the results of a channel list query Add handler function for EVENT 'le_dcs_Event'

This event provides information on channel events

Parameters
[in]channelRefThe channel for which the event is
[in]handlerPtr
[in]contextPtr

◆ le_dcs_ConnectService()

void le_dcs_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client Specific Functions.

This function is created automatically.

◆ le_dcs_DisconnectService()

void le_dcs_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client Specific Functions.

This function is created automatically.

◆ le_dcs_GetChannels()

void le_dcs_GetChannels ( le_dcs_GetChannelsHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Trigger a query for the list of all available data channels that will be returned asynchronously via the ChannelQueryHandler callback notification

Parameters
[in]handlerPtrrequester's handler for receiving results
[in]contextPtr

◆ le_dcs_GetReference()

le_dcs_ChannelRef_t le_dcs_GetReference ( const char *LE_NONNULL  name,
le_dcs_Technology_t  technology 
)

Get the object reference of the channel given by the name and its technology type in the first and second arguments as input

Returns
  • The retrieved channel reference is returned in the function's return value upon success.
  • Upon failure, 0 is returned back
Parameters
[in]namename of channel which reference is to be retrieved
[in]technologytechnology of the channel given by its name above

◆ le_dcs_GetState()

le_result_t le_dcs_GetState ( le_dcs_ChannelRef_t  channelRef,
le_dcs_State_t statePtr,
char *  interfaceName,
size_t  interfaceNameSize 
)

Query for a channel's administrative state

Returns
  • The given channel's state in the 2nd argument and associated network interface in 'name'
Parameters
[in]channelRefchannel which status is to be queried
[out]statePtrchannel state returned as output
[out]interfaceNamechannel's network interface name
[in]interfaceNameSize

◆ le_dcs_GetTechnology()

le_dcs_Technology_t le_dcs_GetTechnology ( le_dcs_ChannelRef_t  channelRef)

Query for a channel's technology type

Returns
Parameters
[in]channelRefchannel which technology type is to be queried

◆ le_dcs_RemoveEventHandler()

void le_dcs_RemoveEventHandler ( le_dcs_EventHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_dcs_Event'

Parameters
[in]handlerRef

◆ le_dcs_SetServerDisconnectHandler()

LE_FULL_API void le_dcs_SetServerDisconnectHandler ( le_dcs_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

◆ le_dcs_Start()

le_dcs_ReqObjRef_t le_dcs_Start ( le_dcs_ChannelRef_t  channelRef)

Request by an app to start a data channel

Returns
  • Object reference to the request (to be used later for releasing the channel)
  • NULL if it has failed to process the request
Parameters
[in]channelRefchannel requested to be started

◆ le_dcs_Stop()

le_result_t le_dcs_Stop ( le_dcs_ReqObjRef_t  reqRef)

Stop for an app its previously started data channel

Parameters
[in]reqRefthe start request's reference earlier returned

◆ le_dcs_TryConnectService()

le_result_t le_dcs_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client Specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.