Unify External Event Demultiplexer

Modules
	Internal Interfaces of the Unify External Event Demultiplexer

Classes
struct	uic_main_ext_fd_registration_t

Macros
#define	UIC_MAIN_EXT_MAX_FDS   5

Typedefs
typedef bool(*	uic_ext_event_handler_t) (int)
typedef void(*	fd_handler_t) (const uic_main_ext_fd_registration_t *reg)

Functions
sl_status_t	uic_main_ext_register_rfd (int fdr, uic_ext_event_handler_t ev_hndl_func, struct process *ev_hndl_process)
sl_status_t	uic_main_ext_unregister_rfd (int fdr)
void	uic_main_ext_select (clock_time_t delay)
void	uic_main_ext_call_handler (const uic_main_ext_fd_registration_t *reg)
void	uic_main_ext_registration_iter (fd_handler_t iter_function)
	MEMB (fd_registration_slots, uic_main_ext_fd_registration_t, UIC_MAIN_EXT_MAX_FDS)
	LIST (fd_registrations)

Detailed Description

This sub-component distributes incoming events from the external interfaces to the interface-handler components.

The sub-component is invoked when the central loop detects an incoming external event (e.g., when a file descriptor has data ready to read).

Note

All components that handle events must be implemented as Contiki processes.

There are two ways this sub-component can pass on an event to the handler:

• In the simplest scenario, one Contiki process handles all events on the interface directly. In this case, the process should register its file descriptor of the interface with the Unify External Event Demultiplexer. The process will then be polled when an event happens on the file descriptor.
• In other cases, e.g., the Contiki standard input handler, incoming data is "pre-screened" by a reader function and dropped if it is irrelevant. So, the process is only polled if the data is relevant. In this case, the component should only register an event handler function with the Unify External Event Demultiplexer.

Note

An event handler function must only execute the minimal handling to import the data into the Unify Main process. The only Contiki process feature it is allowed to use is one process_poll.

If a component registers both a function and a process, the process will be polled if the function returns true.

Macro Definition Documentation

UIC_MAIN_EXT_MAX_FDS

#define UIC_MAIN_EXT_MAX_FDS   5

Maximum number of file descriptors we can select on.

Note

This is not the same as fd_max.

Typedef Documentation

fd_handler_t

typedef void(* fd_handler_t) (const uic_main_ext_fd_registration_t *reg)

Function type for the registration handler functions.

Used in the interface to the platform-specific code.

uic_ext_event_handler_t

typedef bool(* uic_ext_event_handler_t) (int)

Type of an event handler function.

Function Documentation

LIST()

LIST

(

fd_registrations

)

Currently registered readable file descriptors.

MEMB()

MEMB	(	fd_registration_slots	,
		uic_main_ext_fd_registration_t	,
		UIC_MAIN_EXT_MAX_FDS
	)

Memory for readable file descriptors.

uic_main_ext_call_handler()

void uic_main_ext_call_handler

(

const uic_main_ext_fd_registration_t *

reg

)

Invoke the handlers in reg.

Should be called from the platform-specific code in uic_main_ext_platform.c when something happened on the registered external interface.

Parameters

reg	The external event registration whose handlers should be called.

uic_main_ext_register_rfd()

sl_status_t uic_main_ext_register_rfd	(	int	fdr,
		uic_ext_event_handler_t	ev_hndl_func,
		struct process *	ev_hndl_process
	)

Register an event handler for file descriptor readable events.

If ev_hndl_func is set, the function will be called when an event is detected on the file descriptor fdr. The function should only read the event from the file descriptor to an internal storage. If any processing is required, a process should be polled.

If ev_hndl_process is set, the process will be polled when an event is detected on the file descriptor fdr. If the process should not always be polled, the ev_hndl_func can poll the process, and the ev_hndl_process argument should be NULL.

Parameters

fdr	A readable file descriptor.
ev_hndl_func	The function to call if there is an event on fdr.
ev_hndl_process	The process to poll if there is an event on fdr.

Returns

true if the registration succeeded, false otherwise.

uic_main_ext_registration_iter()

void uic_main_ext_registration_iter

(

fd_handler_t

iter_function

)

Iterator function for the registrations.

Run iter_function on all registrations in LIST(fd_registrations).

Parameters

iter_function

The function to map over the registrations.

uic_main_ext_select()

void uic_main_ext_select

(

clock_time_t

delay

)

Synchronous I/O multiplexing similar to posix select().

Monitors all the external interfaces registered in this component.

If an event happens on one of the interfaces, the registered handler will be called. Then the function returns.

If no events happen within delay clock_time_t units, the function times out and returns.

Parameters

delay

Maximum time the call will block, in clock_time_t units.

Here we will set the timer to trigger after 'delay' time in ms. Contiki is not preemptive, so there will be no reason to alter the delay once it is set for the timer.

uic_main_ext_unregister_rfd()

sl_status_t uic_main_ext_unregister_rfd

(

int

fdr

)

Remove a file descriptor from file descriptor readable events.

Parameters

fdr	The file descriptor that should be unregistered.

Returns

true if the removal succeeded, false otherwise.