Abstract System API. More...

Data Structures
struct	OSAPI_SystemI
struct	OSAPI_SystemListener
struct	OSAPI_SystemProperty
struct	OSAPI_SystemUUID
	UUID definition. More...

Typedefs
typedef RTI_BOOL(*	OSAPI_System_start_timer_T )(OSAPI_Timer_T self, OSAPI_TimerTickHandlerFunction tick_handler)
typedef RTI_BOOL(*	OSAPI_System_stop_timer_T )(OSAPI_Timer_T self)
typedef RTI_INT32(*	OSAPI_System_get_timer_resolution_T )(void)
typedef RTI_BOOL(*	OSAPI_System_get_time_T )(OSAPI_NtpTime *now)
typedef RTI_BOOL(*	OSAPI_System_initialize_T )(void)
typedef RTI_BOOL(*	OSAPI_System_finalize_T )(void)
typedef RTI_BOOL(*	OSAPI_System_get_hostname_T )(char *const hostname)
typedef RTI_BOOL(*	OSAPI_System_on_system_initialize_T )(void listener_data, struct OSAPI_System system)

Functions
RTI_BOOL	OSAPI_System_set_interface (struct OSAPI_SystemI *intf)
	Set system interface.
RTI_BOOL	OSAPI_System_get_interface (struct OSAPI_SystemI *intf)
	Get the current system interface.
RTI_BOOL	OSAPI_System_set_listener (struct OSAPI_SystemListener *listener)
	Install a system listeners.
RTI_BOOL	OSAPI_System_get_listener (struct OSAPI_SystemListener *listener)
	Get current system listeners.
RTI_BOOL	OSAPI_System_generate_uuid (struct OSAPI_SystemUUID *uuid_out)
	Generate a unique universal identifier (UUID)
RTI_BOOL	OSAPI_System_get_time (OSAPI_NtpTime *now)
	Get the current system time.
RTI_INT32	OSAPI_System_get_timer_resolution (void)
	Get the resolution of the clock driving the timer in nano seconds.
RTI_BOOL	OSAPI_System_start_timer (OSAPI_Timer_T self, OSAPI_TimerTickHandlerFunction tick_handler)
	Start the timer.
RTI_BOOL	OSAPI_System_stop_timer (OSAPI_Timer_T self)
	Stop the timer.
RTI_BOOL	OSAPI_System_initialize (void)
	Initialize the system.
RTI_BOOL	OSAPI_System_finalize (void)
	Finalize the system.
RTI_BOOL	OSAPI_System_get_property (struct OSAPI_SystemProperty *property)
	Get the system properties.
RTI_BOOL	OSAPI_System_set_property (struct OSAPI_SystemProperty *property)
	Set the system properties.
void	OSAPI_System_get_native_interface (struct OSAPI_SystemI *intf)
	Get the native system interface.
RTI_INT32	OSAPI_System_get_next_object_id (void)
	Return next object ID.
RTI_BOOL	OSAPI_System_get_hostname (char *const hostname)
	Get the hostname.
RTI_BOOL	OSAPI_System_get_ticktime (RTI_INT32 sec, RTI_UINT32 nanosec)
	Get current tick time.
OSAPI_Semaphore_T *	OSAPI_System_get_thread_semaphore (void)
	Get a semaphore to suspend a thread.
void	OSAPI_System_return_thread_semaphore (OSAPI_Semaphore_T *sem)
	Return a semaphore acquired with OSAPI_System_get_thread_semaphore.

Variables
OSAPI_System_start_timer_T	OSAPI_SystemI::start_timer
OSAPI_System_stop_timer_T	OSAPI_SystemI::stop_timer
OSAPI_System_get_timer_resolution_T	OSAPI_SystemI::get_timer_resolution
OSAPI_System_get_time_T	OSAPI_SystemI::get_time
OSAPI_System_initialize_T	OSAPI_SystemI::initialize
OSAPI_System_finalize_T	OSAPI_SystemI::finalize
OSAPI_System_generate_uuid_T	OSAPI_SystemI::generate_uuid
OSAPI_System_get_hostname_T	OSAPI_SystemI::get_hostname
OSAPI_System_get_ticktime_T	OSAPI_SystemI::get_ticktime

Detailed Description

Abstract System API.

The System is defined as the physical or virtual execution environment and implements functions that are not necessarily provided by the operating system. For example, a custom embedded board may include a special real-time clock which is synchronized via GPS, but is not available via a regular OS system call.

Typedef Documentation

typedef RTI_BOOL(* OSAPI_System_start_timer_T)(OSAPI_Timer_T self, OSAPI_TimerTickHandlerFunction tick_handler)

start timer definition

typedef RTI_BOOL(* OSAPI_System_stop_timer_T)(OSAPI_Timer_T self)

stop timer definition

typedef RTI_INT32(* OSAPI_System_get_timer_resolution_T)(void)

get timer resolution

typedef RTI_BOOL(* OSAPI_System_get_time_T)(OSAPI_NtpTime *now)

get time

typedef RTI_BOOL(* OSAPI_System_initialize_T)(void)

initialize

typedef RTI_BOOL(* OSAPI_System_finalize_T)(void)

finalize

typedef RTI_BOOL(* OSAPI_System_get_hostname_T)(char *const hostname)

get_hostname

typedef RTI_BOOL(* OSAPI_System_on_system_initialize_T)(void *listener_data, struct OSAPI_System *system)

System listener

Function Documentation

RTI_BOOL OSAPI_System_set_interface ( struct OSAPI_SystemI * intf )

Set system interface.

This function sets the system interface, overriding the current system interface.

Parameters:

[in] intf - The new system interface

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_get_interface ( struct OSAPI_SystemI * intf )

Get the current system interface.

This function returns the current system interface

Parameters:

[out] intf - The current system interface

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_set_listener ( struct OSAPI_SystemListener * listener )

Install a system listeners.

The system listeners are called during the life-time of the system. Only listeners which are non-NULL are called, thus it is ok to install a partially set listener structure. System listeners can be installed until the system has been initialized by calling OSAPI_System_initialize. This function is not considered thread-safe. The listener value should always be initialized with OSAPI_SystemListener_DEFAULT before use.

Parameters:

[in] listener System listeners to call

Returns:: RTI_TRUE on success, RTI_FALSE on failure

RTI_BOOL OSAPI_System_get_listener ( struct OSAPI_SystemListener * listener )

Get current system listeners.

Return the current set of system listeners. This function is not thread-safe.

Parameters:

[in] listener System listener structure to fill in.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_generate_uuid ( struct OSAPI_SystemUUID * uuid_out )

Generate a unique universal identifier (UUID)

Parameters:

[out] uuid_out The generated UUID value

Returns:: RTI_TRUE on success, RTI_FALSE on failure

RTI_BOOL OSAPI_System_get_time ( OSAPI_NtpTime * now )

Get the current system time.

In general, the system time is used by components to correlate both internal and external events, such as data reception and ordering. Thus, it is recommended that this function returns the real time. However, it is not strictly required.

Notes:

It is assumed that the time returned by get_time is monotonically increasing. It is up to the implementation of this function to ensure this holds true.
It is ok to return the same time as the last call.
The clock used to report real-time can be different than the clock used to support start_timer and stop_timer.

Parameters:

[out] now Time in NtpTime format.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

Precondition:: Initialized system.

Exceptions:

None.

RTI_INT32 OSAPI_System_get_timer_resolution ( void )

Get the resolution of the clock driving the timer in nano seconds.

This function must return the frequency of the system timer used to implement OSAPI_SystemI::start_timer and OSAPI_SystemI::stop_timer API.

Returns:: timer resolution in nanoseconds.

RTI_BOOL OSAPI_System_start_timer	(	OSAPI_Timer_T	self,
		OSAPI_TimerTickHandlerFunction	tick_handler
	)

Start the timer.

Parameters:

[in]	self	Timer object.
[in]	tick_handler	Timer handle.

Precondition:: Initialized system.

RTI_BOOL OSAPI_System_stop_timer ( OSAPI_Timer_T self )

Stop the timer.

Parameters:

[in] self Timer

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

Precondition:: Initialized system.

RTI_BOOL OSAPI_System_initialize ( void )

Initialize the system.

This function initializes the system and calls the port specific initialize method first. The port specific initialization method must return RTI_TRUE on success and RTI_FALSE on failure. A system can only be initialized once.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_finalize ( void )

Finalize the system.

This function finalizes the system and calls the port specific finalize method last. The port specific initialization method must return RTI_TRUE on success and RTI_FALSE on failure.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_get_property ( struct OSAPI_SystemProperty * property )

Get the system properties.

Parameters:

[out] property

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

RTI_BOOL OSAPI_System_set_property ( struct OSAPI_SystemProperty * property )

Set the system properties.

The system properties can be set until the system is initialized by calling OSAPI_System_initialize()

Parameters:

[in] property

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

void OSAPI_System_get_native_interface ( struct OSAPI_SystemI * intf )

Get the native system interface.

This function must fill in the interface structure and assign the following methods:

Parameters:

[out] intf The native system interface

RTI_INT32 OSAPI_System_get_next_object_id ( void )

Return next object ID.

This function return the next available object if. Object Id are never reused, thus it is possible to run out of object ids.

Returns:: new object on success, -1 on failure

RTI_BOOL OSAPI_System_get_hostname ( char *const hostname )

Get the hostname.

Get the hostname

Parameters:

[out] hostname The buffer to store the hostname. Must be at least OSAPI_SYSTEM_MAX_HOSTNAME bytes. If the actual hostname is longer than OSAPI_SYSTEM_MAX_HOSTNAME bytes (including \0) the hostname is truncated.

Precondition:: Initialized system.

Exceptions:

None.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

MT Safety:: SAFE

RTI_BOOL OSAPI_System_get_ticktime	(	RTI_INT32 *	sec,
		RTI_UINT32 *	nanosec
	)

Get current tick time.

The ticktime is a time measurement used by Micro to determine how much time has elapsed in a period. It does not have to be an absolute time, but it must be monotonically increasing. For this reason it is important to choose the time source with care. For example, the system time may mbe adjusted backward or forward and this could affect the measure time lapse. The resolution of the tick time is expected to be no less than the system timer, although it is not a requirement.

Parameters:

[out]	sec	The current ticktime in seconds
[out]	nanosec	Additional nanoseconds in the current ticktime

Precondition:: Initialized system.

Returns:: RTI_TRUE on success, RTI_FALSE on failure.

OSAPI_Semaphore_T* OSAPI_System_get_thread_semaphore ( void )

Get a semaphore to suspend a thread.

Returns:: A semaphore on success, NULL on failure.

void OSAPI_System_return_thread_semaphore ( OSAPI_Semaphore_T * sem )

Return a semaphore acquired with OSAPI_System_get_thread_semaphore.

Parameters:

[in] sem Semaphore to return

Variable Documentation

OSAPI_System_start_timer_T OSAPI_SystemI::start_timer

Refer to OSAPI_System_start_timer for signature and semantics.

OSAPI_System_stop_timer_T OSAPI_SystemI::stop_timer

Refer to OSAPI_System_stop_timer for signature and semantics.

OSAPI_System_get_timer_resolution_T OSAPI_SystemI::get_timer_resolution

Refer to OSAPI_System_get_timer_resolution for signature and semantics.

OSAPI_System_get_time_T OSAPI_SystemI::get_time

Refer to OSAPI_System_get_time for signature and semantics.

OSAPI_System_initialize_T OSAPI_SystemI::initialize

Refer to OSAPI_System_initialize for signature and semantics.

OSAPI_System_finalize_T OSAPI_SystemI::finalize

Refer to OSAPI_System_finalize for signature and semantics.

OSAPI_System_generate_uuid_T OSAPI_SystemI::generate_uuid

Refer to OSAPI_System_generate_uuid for signature and semantics.

OSAPI_System_get_hostname_T OSAPI_SystemI::get_hostname

Refer to OSAPI_System_get_hostname for signature and semantics.

OSAPI_System_get_ticktime_T OSAPI_SystemI::get_ticktime

Refer to OSAPI_System_get_ticktime for signature and semantics.

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation