Description

Application should use the APIs declared in this file to access services provided by IARM-Bus. Basically services provided by these APIs include:
1) Library Initialization and termination.
2) Connection to IARM-Bus.
3) Send and Receive Events.
4) Declared and Invoke RPC Methods.

Document: Document reference.

Open Issues (in no particular order)

None

Assumptions

None

Abbreviations

BE: ig-Endian.
cb: allback function (suffix).
DS: Device Settings.
FPD: Front-Panel Display.
HAL: Hardware Abstraction Layer.
LE: Little-Endian.
LS: Least Significant.
MBZ: Must be zero.
MS: Most Significant.
RDK: Reference Design Kit.
_t: Type (suffix).

Implementation Notes

None

Functions
IARM_Result_t	IARM_Bus_Init (const char *name)
	This API is used to initialize the IARM-Bus library. More...

IARM_Result_t	IARM_Bus_Term (void)
	This API is used to terminate the IARM-Bus library. More...

IARM_Result_t	IARM_Bus_Connect (void)
	This API is used to connect application to the IARM bus daemon. After connected, the application can send/receive IARM events and invoke IARM RPC calls. More...

IARM_Result_t	IARM_Bus_Disconnect (void)
	This API disconnect Application from IARM Bus so the application will not receive any IARM event or RPC calls. More...

IARM_Result_t	IARM_Bus_GetContext (void **context)
	Returns group context of the calling member. More...

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 event. Upon returns of this function, all the listeners are notified of the event. More...

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. More...

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. Execution of the handler will not block the process sending the event. More...

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 event handlers. This API is not used to unregister a specific handler.. More...

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. More...

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. More...

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. More...

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 to wait for response. More...

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. More...

void	IARM_Bus_WritePIDFile (const char *path)
	Write PID file. More...

Function Documentation

◆ IARM_Bus_Init()

IARM_Result_t IARM_Bus_Init ( const char * name )

This API is used to initialize the IARM-Bus library.

The registered IARM client is uniquely identified by the given name in the IARM_Bus_Init() function. The application is not yet connected to the bus until IARM_Bus_Connect() is called.

After the library is initialized, the application is ready to access events and RPC methods using the bus.

Parameters

[in] name A well-known name of the IARM client. The registered IARM client should be uniquely identified by (groupName, memberName)

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates the call was unsuccessful because the bus is already initialised and connected.

Definition at line 38 of file iarmMgrMocks.cpp.

◆ IARM_Bus_Term()

IARM_Result_t IARM_Bus_Term ( void )

This API is used to terminate the IARM-Bus library.

This function releases resources allocated by the IARM Bus Library. After it is called, the library returns to the state prior to IARM_Bus_Init function is called.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates the call was unsuccessful because the bus is not initialised.

◆ 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 send/receive IARM events and invoke IARM RPC calls.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_STATE	Indicates the call was unsuccessful.

Definition at line 33 of file iarmMgrMocks.cpp.

◆ 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 RPC calls.

Returns: IARM_Result_t Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_STATE	Indicates the call was unsuccessful.

◆ IARM_Bus_GetContext()

IARM_Result_t IARM_Bus_GetContext ( void ** context )

Returns group context of the calling member.

Returns: IARM_Result_t Error Code.

Return values

IARM_RESULT_SUCCESS on success

◆ 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 event. Upon returns of this function, all the listeners are notified of the event.

Parameters

[in]	ownerName	The IARM client that publishes/owns the broadcast event.
[in]	eventId	The event id to publish.
[in]	data	Data carried by this event.
[in]	len	Length of the data parameter.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_STATE	Indicates the call was unsuccessful because the bus is either not initialised nor connected.
IARM_RESULT_INVALID_PARAM	Indicates invalid parameter.

◆ 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.

Parameters

[in]	memberName	IARMBUS member whose registration status has to be checked.
[out]	isRegistered	True if the specified process is still registered.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid input parameter.
IARM_RESULT_IPCCORE_FAIL	Indicates failure of the underlying IPC.

◆ 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. Execution of the handler will not block the process sending the event.

The API checks for duplicate handlers so a same handler for same event and owner name will not be registered twice NULL handler is not allowed.

Parameters

[in]	ownerName	The well-known name of the IARM client.
[in]	eventId	The event to listen for.
[in]	handler	The hander function to be called for event notification.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid input parameters.
IARM_RESULT_INVALID_STATE	Indicates the IARM_Bus is either not initialised nor connected.
IARM_RESULT_IPCCORE_FAIL	Indicates failure of the underlying IPC.
IARM_RESULT_OOM	Indicates memory allocation failure.

See also: IARM_Bus_BroadcastEvent(); IARM_EventHandler_t

Definition at line 43 of file iarmMgrMocks.cpp.

◆ 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 event handlers. This API is not used to unregister a specific handler..

Parameters

[in]	eventId	The event whose listener to be removed.
[in]	ownerName	The well-known name of the application.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid input parameter was passed.
IARM_RESULT_INVALID_STATE	Indicates the IARM_Bus is either not initialised nor connected.
IARM_RESULT_IPCCORE_FAIL	Indicates underlying IPC failure.
IARM_RESULT_OOM	Indicates memory allocation failure.

◆ 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.

This API remove the specific handlers.

Parameters

[in]	ownerName	The well-known name of the application.
[in]	eventId	The event whose listener to remove.
[in]	handler	The event handler to remove.

Returns: IARM_Result_t Error Code.

Definition at line 50 of file iarmMgrMocks.cpp.

◆ 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.

The parameter methodName is the string name used to invoke the RPC method and the parameter handler is the implementation of the RPC method. When other application invokes the method via its string name, the function pointed to by the handler is executed.

Parameters

[in]	methodName	The name used to invoke the RPC method.
[in]	handler	A pointer to RPC method implementation.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid parameter.
IARM_RESULT_INVALID_STATE	Indicates IARM_Bus is either not initialised nor connected.
IARM_RESULT_OOM	Indicates memory allocation failure.

◆ 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.

Parameters

[in]	ownerName	well-known name of the application that publish the RPC call.
[in]	methodName	well-known name of the RPC method.
[in]	arg	It is the data structure holding input & output parameters of the invocation.
[in]	argLen	The size of the data pointed by arg parameter.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid input parameter.
IARM_RESULT_INVALID_STATE	Indicates the IARM_Bus was either not initialised nor connected.
IARM_RESULT_IPCCORE_FAIL	Indicates failure of the underlying IPC.
IARM_RESULT_OOM	Indicates failure to allocate memory.

Definition at line 57 of file iarm_bus.c.

◆ 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 to wait for response.

Parameters

[in]	ownerName	well-known name of the application that publish the RPC call.
[in]	methodName	well-known name of the RPC method.
[in]	arg	It is the data structure holding input & output parameters of the invocation.
[in]	argLen	The size of the data pointed by arg parameter.
[in]	timeout	in millisecond for the RPC method.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_PARAM	Indicates invalid input parameter.
IARM_RESULT_INVALID_STATE	Indicates the IARM_Bus was either not initialised nor connected.
IARM_RESULT_IPCCORE_FAIL	Indicates failure of the underlying IPC.
IARM_RESULT_OOM	Indicates failure to allocate memory.

◆ 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.

An application can publish multiple events and these events must have an enumeration value defined in the public header file of the HAL. It registers all events whose enum value is less than maxEventId.

Parameters

[in] maxEventId The maximum number of events that can be registered.

Returns: Error Code.

Return values

IARM_RESULT_SUCCESS	Indicates the call was successful.
IARM_RESULT_INVALID_STATE	Indicates the IARM Bus is either not initialised nor connected.

◆ IARM_Bus_WritePIDFile()

void IARM_Bus_WritePIDFile ( const char * path )

Write PID file.

This API allows Daemon to write PID file

Parameters

full	pathname to pidfile to write

Description

Functions

Function Documentation

◆ IARM_Bus_Init()

◆ IARM_Bus_Term()

◆ IARM_Bus_Connect()

◆ IARM_Bus_Disconnect()

◆ IARM_Bus_GetContext()

◆ IARM_Bus_BroadcastEvent()

◆ IARM_Bus_IsConnected()

◆ IARM_Bus_RegisterEventHandler()

◆ IARM_Bus_UnRegisterEventHandler()

◆ IARM_Bus_RemoveEventHandler()

◆ IARM_Bus_RegisterCall()

◆ IARM_Bus_Call()

◆ IARM_Bus_Call_with_IPCTimeout()

◆ IARM_Bus_RegisterEvent()

◆ IARM_Bus_WritePIDFile()