RDK Documentation (Open Sourced RDK Components)
libIBus.h
Go to the documentation of this file.
1 /*
2  * If not stated otherwise in this file or this component's Licenses.txt file the
3  * following copyright and licenses apply:
4  *
5  * Copyright 2016 RDK Management
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18 */
19 
20 /**
21 * @file libIBus.h
22 *
23 * @brief RDK IARM-Bus API Declarations.
24 *
25 * @defgroup IARMBUS_API IARM Bus API
26 * @ingroup IARMBUS
27 * Application should use the APIs declared in this file to access
28 * services provided by IARM-Bus. Basically services provided by
29 * these APIs include:
30 * <br> 1) Library Initialization and termination.
31 * <br> 2) Connection to IARM-Bus.
32 * <br> 3) Send and Receive Events.
33 * <br> 4) Declared and Invoke RPC Methods.
34 *
35 * @par Document
36 * Document reference.
37 *
38 * @par Open Issues (in no particular order)
39 * -# None
40 *
41 * @par Assumptions
42 * -# None
43 *
44 * @par Abbreviations
45 * - BE: ig-Endian.
46 * - cb: allback function (suffix).
47 * - DS: Device Settings.
48 * - FPD: Front-Panel Display.
49 * - HAL: Hardware Abstraction Layer.
50 * - LE: Little-Endian.
51 * - LS: Least Significant.
52 * - MBZ: Must be zero.
53 * - MS: Most Significant.
54 * - RDK: Reference Design Kit.
55 * - _t: Type (suffix).
56 *
57 * @par Implementation Notes
58 * -# None
59 *
60 */
61 
62 /** @defgroup IARMBUS IARM Bus
63 *
64 * IARM-Bus is a platform agnostic Inter-process communication (IPC) interface. It allows
65 * applications to communicate with each other by sending Events or invoking Remote
66 * Procedure Calls. The common programming APIs offered by the RDK IARM-Bus interface is
67 * independent of the operating system or the underlying IPC mechanism.
68 *
69 * Two applications connected to the same instance of IARM-Bus are able to exchange events
70 * or RPC calls. On a typical system, only one instance of IARM-Bus instance is needed. If
71 * desired, it is possible to have multiple IARM-Bus instances. However, applications
72 * connected to different buses will not be able to communicate with each other.
73 *
74 * @par Capabilities
75 * <ol>
76 * <li> Invoke methods in other processes via Remote Procedure Call (RPC).
77 * <li> Send interprocess messages.
78 * <li> Manage shared memory and exclusive access to resources.
79 * <li> Register for event notification.
80 * <li> Publish event notification to registered listeners.
81 * </ol>
82 */
83 
84 #ifndef _LIB_IARM_BUS_H
85 #define _LIB_IARM_BUS_H
86 
87 
88 
89 #ifdef __cplusplus
90 extern "C"
91 {
92 #endif
93 
94 #include "libIARM.h"
95 
96 /**
97  * @brief Function signature for RPC Methods.
98  *
99  * All IARM RPC Methods must use <tt>IARM_BusCall_t</tt> as their function signature.
100  * Important Note: The argument structure cannot have pointers. The sizeof() operator applied
101  * on the @p arg must equal to the actual memory allocated. Internally an equivalent of
102  * memcpy() is used to dispatch parameters its target. If a pointer is used in the parameters,
103  * the pointer, not the content it points to, is sent to the destination.
104  *
105  * @param arg is the composite carrying all input and output parameters of the RPC Method.
106  *
107  */
108 typedef IARM_Result_t (*IARM_BusCall_t) (void *arg);
109 /**
110  * @brief Function signature for event handlers.
111  *
112  * All IARM Event handlers must use <tt>IARM_EventHandler_t</tt> as their function signature.
113  * Important Note: The event data structure cannot have pointers. The sizeof() operator applied
114  * on the @p data must equal to the actual memory allocated. Internally an equivalent of
115  * memcpy() is used to dispatch event data to its target. If a pointer is used in the event data,
116  * the pointer, not the content it points to, is sent to the destination.
117  *
118  * @param owner is well-known name of the application sending the event.
119  * @param eventID is the integer uniquely identifying the event within the sending application.
120  * @param data is the composite carrying all input and output parameters of event.
121  * @param len is the result of sizeof() applied on the event data data structure.
122  *
123  * @return None
124  */
125 typedef void (*IARM_EventHandler_t)(const char *owner, IARM_EventId_t eventId, void *data, size_t len);
126 
127 /**
128  * @addtogroup IARMBUS_API
129  * @{
130  */
131 
132 /**
133  * @brief This API is used to initialize the IARM-Bus library.
134  *
135  * The registered IARM client is uniquely identified by the given name in the IARM_Bus_Init() function.
136  * The application is not yet connected to the bus until IARM_Bus_Connect() is called.
137  *
138  * After the library is initialized, the application is ready to access events and RPC methods
139  * using the bus.
140  *
141  * @param[in] name A well-known name of the IARM client. The registered IARM client
142  * should be uniquely identified by (groupName, memberName)
143  *
144  * @return Error Code.
145  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
146  * @retval IARM_RESULT_INVALID_PARAM Indicates the call was unsuccessful because the bus is
147  * already initialised and connected.
148  */
149 IARM_Result_t IARM_Bus_Init(const char *name);
150 
151 /**
152  * @brief This API is used to terminate the IARM-Bus library.
153  *
154  * This function releases resources allocated by the IARM Bus Library. After it is called,
155  * the library returns to the state prior to IARM_Bus_Init function is called.
156  *
157  * @return Error Code.
158  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
159  * @retval IARM_RESULT_INVALID_PARAM Indicates the call was unsuccessful because the bus is
160  * not initialised.
161  */
162 IARM_Result_t IARM_Bus_Term(void);
163 
164 /**
165  * @brief This API is used to connect application to the IARM bus daemon.
166  * After connected, the application can send/receive IARM events and invoke IARM RPC calls.
167  *
168  * @return Error Code.
169  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
170  * @retval IARM_RESULT_INVALID_STATE Indicates the call was unsuccessful.
171  */
172 IARM_Result_t IARM_Bus_Connect(void);
173 
174 /**
175  * @brief This API disconnect Application from IARM Bus so the application will not receive
176  * any IARM event or RPC calls.
177  *
178  * @return IARM_Result_t Error Code.
179  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
180  * @retval IARM_RESULT_INVALID_STATE Indicates the call was unsuccessful.
181  */
182 IARM_Result_t IARM_Bus_Disconnect(void);
183 
184 /**
185  * @brief Returns group context of the calling member
186  *
187  * @return IARM_Result_t Error Code.
188  * @retval IARM_RESULT_SUCCESS on success
189  */
190 IARM_Result_t IARM_Bus_GetContext(void **context);
191 
192 /**
193  * @brief This API is used to publish an Asynchronous event to all IARM client registered for this
194  * perticular event. Upon returns of this function, all the listeners are notified of the event.
195  *
196  * @param[in] ownerName The IARM client that publishes/owns the broadcast event.
197  * @param[in] eventId The event id to publish.
198  * @param[in] data Data carried by this event.
199  * @param[in] len Length of the data parameter.
200  *
201  * @return Error Code.
202  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
203  * @retval IARM_RESULT_INVALID_STATE Indicates the call was unsuccessful because the bus is either
204  * not initialised nor connected.
205  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid parameter.
206  */
207 IARM_Result_t IARM_Bus_BroadcastEvent(const char *ownerName, IARM_EventId_t eventId, void *data, size_t len);
208 
209 /**
210  * @brief This API is used to check if the current process is registered with IARM.
211  *
212  * @param[in] memberName IARMBUS member whose registration status has to be checked.
213  * @param[out] isRegistered True if the specified process is still registered.
214  *
215  * @return Error Code.
216  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
217  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid input parameter.
218  * @retval IARM_RESULT_IPCCORE_FAIL Indicates failure of the underlying IPC.
219  */
220 IARM_Result_t IARM_Bus_IsConnected(const char *memberName, int *isRegistered);
221 
222 /**
223  * @brief This API register to listen to event and provide the callback function for event notification.
224  * Execution of the handler will not block the process sending the event.
225  *
226  * The API checks for duplicate handlers so a same handler for same event and owner name will not be registered twice
227  * NULL handler is not allowed.
228  *
229  * @param[in] ownerName The well-known name of the IARM client.
230  * @param[in] eventId The event to listen for.
231  * @param[in] handler The hander function to be called for event notification.
232  *
233  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
234  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid input parameters.
235  * @retval IARM_RESULT_INVALID_STATE Indicates the IARM_Bus is either not initialised nor connected.
236  * @retval IARM_RESULT_IPCCORE_FAIL Indicates failure of the underlying IPC.
237  * @retval IARM_RESULT_OOM Indicates memory allocation failure.
238  * @see IARM_Bus_BroadcastEvent()
239  * @see IARM_EventHandler_t
240  */
241 IARM_Result_t IARM_Bus_RegisterEventHandler(const char *ownerName, IARM_EventId_t eventId, IARM_EventHandler_t handler);
242 
243 /**
244  * @brief This API is used to Remove ALL handlers registered for the given event.
245  * This API remove the all the event handlers. This API is not used to unregister a specific handler..
246 
247  * @param[in] eventId The event whose listener to be removed.
248  * @param[in] ownerName The well-known name of the application.
249  *
250  * @return Error Code.
251  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
252  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid input parameter was passed.
253  * @retval IARM_RESULT_INVALID_STATE Indicates the IARM_Bus is either not initialised nor connected.
254  * @retval IARM_RESULT_IPCCORE_FAIL Indicates underlying IPC failure.
255  * @retval IARM_RESULT_OOM Indicates memory allocation failure.
256  */
257 IARM_Result_t IARM_Bus_UnRegisterEventHandler(const char *ownerName, IARM_EventId_t eventId);
258 
259 /**
260  * @brief Remove specific handler registered for the given event.
261  *
262  * This API remove the specific handlers.
263  * @param[in] ownerName The well-known name of the application.
264  * @param [in] eventId The event whose listener to remove.
265  * @param [in] handler The event handler to remove.
266  *
267  * @return IARM_Result_t Error Code.
268  */
269 IARM_Result_t IARM_Bus_RemoveEventHandler(const char *ownerName, IARM_EventId_t eventId, IARM_EventHandler_t handler);
270 
271 
272 
273 /**
274  * @brief This API is used to register an RPC method that can be invoked by other applications.
275  *
276  * The parameter methodName is the string name used to invoke the RPC method and the parameter handler
277  * is the implementation of the RPC method. When other application invokes the method via its string name,
278  * the function pointed to by the handler is executed.
279  *
280  * @param[in] methodName The name used to invoke the RPC method.
281  * @param[in] handler A pointer to RPC method implementation.
282  *
283  * @return Error Code.
284  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
285  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid parameter.
286  * @retval IARM_RESULT_INVALID_STATE Indicates IARM_Bus is either not initialised nor connected.
287  * @retval IARM_RESULT_OOM Indicates memory allocation failure.
288  */
289 IARM_Result_t IARM_Bus_RegisterCall(const char *methodName, IARM_BusCall_t handler);
290 
291 /**
292  * @brief This API is used to Invoke RPC method by its application name and method name.
293  *
294  * @param[in] ownerName well-known name of the application that publish the RPC call.
295  * @param[in] methodName well-known name of the RPC method.
296  * @param[in] arg It is the data structure holding input & output parameters of the invocation.
297  * @param[in] argLen The size of the data pointed by arg parameter.
298  *
299  * @return Error Code.
300  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
301  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid input parameter.
302  * @retval IARM_RESULT_INVALID_STATE Indicates the IARM_Bus was either not initialised nor connected.
303  * @retval IARM_RESULT_IPCCORE_FAIL Indicates failure of the underlying IPC.
304  * @retval IARM_RESULT_OOM Indicates failure to allocate memory.
305  */
306 IARM_Result_t IARM_Bus_Call(const char *ownerName, const char *methodName, void *arg, size_t argLen);
307 
308 /**
309  * @brief This API is used to Invoke RPC method by its application name and method
310  * name with specified timeout to wait for response.
311  *
312  * @param[in] ownerName well-known name of the application that publish the RPC call.
313  * @param[in] methodName well-known name of the RPC method.
314  * @param[in] arg It is the data structure holding input & output parameters of the invocation.
315  * @param[in] argLen The size of the data pointed by arg parameter.
316  * @param[in] timeout in millisecond for the RPC method.
317  *
318  * @return Error Code.
319  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
320  * @retval IARM_RESULT_INVALID_PARAM Indicates invalid input parameter.
321  * @retval IARM_RESULT_INVALID_STATE Indicates the IARM_Bus was either not initialised nor connected.
322  * @retval IARM_RESULT_IPCCORE_FAIL Indicates failure of the underlying IPC.
323  * @retval IARM_RESULT_OOM Indicates failure to allocate memory.
324  */
325 IARM_Result_t IARM_Bus_Call_with_IPCTimeout(const char *ownerName, const char *methodName, void *arg, size_t argLen, int timeout);
326 
327 /**
328  * @brief This API is used to register all the events that are published by the application.
329  *
330  * An application can publish multiple events and these events must have an enumeration value
331  * defined in the public header file of the HAL.
332  * It registers all events whose enum value is less than maxEventId.
333  *
334  * @param[in] maxEventId The maximum number of events that can be registered.
335  *
336  * @return Error Code.
337  * @retval IARM_RESULT_SUCCESS Indicates the call was successful.
338  * @retval IARM_RESULT_INVALID_STATE Indicates the IARM Bus is either not initialised nor connected.
339  */
340 IARM_Result_t IARM_Bus_RegisterEvent(IARM_EventId_t maxEventId);
341 
342 /**
343  * @brief Write PID file
344  *
345  * This API allows Daemon to write PID file
346  *
347  * @param full pathname to pidfile to write
348  */
349 void IARM_Bus_WritePIDFile(const char *path);
350 
351 
352 /* End of IARM_BUS_IARM_CORE_API doxygen group */
353 /**
354  * @}
355  */
356 
357 #ifdef __cplusplus
358 }
359 #endif
360 #endif
361 
IARM_Bus_GetContext
IARM_Result_t IARM_Bus_GetContext(void **context)
Returns group context of the calling member.
IARM_Bus_Term
IARM_Result_t IARM_Bus_Term(void)
This API is used to terminate the IARM-Bus library.
IARM_Bus_WritePIDFile
void IARM_Bus_WritePIDFile(const char *path)
Write PID file.
IARM_Bus_Call
IARM_Result_t IARM_Bus_Call(const char *ownerName, const char *methodName, void *arg, size_t argLen)
This API is used to Invoke RPC method by its application name and method name.
Definition: iarm_bus.c:57
IARM_BusCall_t
IARM_Result_t(* IARM_BusCall_t)(void *arg)
Function signature for RPC Methods.
Definition: libIBus.h:108
IARM_Bus_Call_with_IPCTimeout
IARM_Result_t IARM_Bus_Call_with_IPCTimeout(const char *ownerName, const char *methodName, void *arg, size_t argLen, int timeout)
This API is used to Invoke RPC method by its application name and method name with specified timeout ...
IARM_Bus_RegisterEvent
IARM_Result_t IARM_Bus_RegisterEvent(IARM_EventId_t maxEventId)
This API is used to register all the events that are published by the application.
IARM_Bus_RegisterEventHandler
IARM_Result_t IARM_Bus_RegisterEventHandler(const char *ownerName, IARM_EventId_t eventId, IARM_EventHandler_t handler)
This API register to listen to event and provide the callback function for event notification....
Definition: iarmMgrMocks.cpp:43
IARM_Bus_RegisterCall
IARM_Result_t IARM_Bus_RegisterCall(const char *methodName, IARM_BusCall_t handler)
This API is used to register an RPC method that can be invoked by other applications.
IARM_Bus_RemoveEventHandler
IARM_Result_t IARM_Bus_RemoveEventHandler(const char *ownerName, IARM_EventId_t eventId, IARM_EventHandler_t handler)
Remove specific handler registered for the given event.
Definition: iarmMgrMocks.cpp:50
IARM_Bus_Disconnect
IARM_Result_t IARM_Bus_Disconnect(void)
This API disconnect Application from IARM Bus so the application will not receive any IARM event or R...
IARM_Bus_IsConnected
IARM_Result_t IARM_Bus_IsConnected(const char *memberName, int *isRegistered)
This API is used to check if the current process is registered with IARM.
IARM_Bus_BroadcastEvent
IARM_Result_t IARM_Bus_BroadcastEvent(const char *ownerName, IARM_EventId_t eventId, void *data, size_t len)
This API is used to publish an Asynchronous event to all IARM client registered for this perticular e...
IARM_EventHandler_t
void(* IARM_EventHandler_t)(const char *owner, IARM_EventId_t eventId, void *data, size_t len)
Function signature for event handlers.
Definition: libIBus.h:125
IARM_Bus_Connect
IARM_Result_t IARM_Bus_Connect(void)
This API is used to connect application to the IARM bus daemon. After connected, the application can ...
Definition: iarmMgrMocks.cpp:33
IARM_Bus_UnRegisterEventHandler
IARM_Result_t IARM_Bus_UnRegisterEventHandler(const char *ownerName, IARM_EventId_t eventId)
This API is used to Remove ALL handlers registered for the given event. This API remove the all the e...
IARM_Bus_Init
IARM_Result_t IARM_Bus_Init(const char *name)
This API is used to initialize the IARM-Bus library.
Definition: iarmMgrMocks.cpp:38