RTI Connext DDS Micro C API  Version 3.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
OSAPI System

Abstract System API. More...

Data Structures

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

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_UINT32 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_TOSAPI_System_get_thread_semaphore (void)
 Get a semaphore to suspend a thread.
OSAPI_Semaphore_TOSAPI_System_get_user_thread_semaphore (void)
 Get a semaphore to suspend a user thread.
void OSAPI_System_return_thread_semaphore (OSAPI_Semaphore_T *sem)
 Return a semaphore acquired with OSAPI_System_get_thread_semaphore.
void OSAPI_System_return_user_thread_semaphore (OSAPI_Semaphore_T *sem)
 Return a user 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]listenerSystem 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]listenerSystem 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_outThe 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]nowTime 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]selfTimer object.
[in]tick_handlerTimer handle.
Precondition:
Initialized system.
RTI_BOOL OSAPI_System_stop_timer ( OSAPI_Timer_T  self)

Stop the timer.

Parameters:
[in]selfTimer
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]intfThe native system interface
RTI_UINT32 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]hostnameThe 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]secThe current ticktime in seconds
[out]nanosecAdditional 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.
OSAPI_Semaphore_T* OSAPI_System_get_user_thread_semaphore ( void  )

Get a semaphore to suspend a user 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]semSemaphore to return
void OSAPI_System_return_user_thread_semaphore ( OSAPI_Semaphore_T sem)

Return a user semaphore acquired with OSAPI_System_get_thread_semaphore.

Parameters:
[in]semSemaphore 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.


RTI Connext DDS Micro C API Version 3.0.0 Copyright © Fri Mar 22 2019 Real-Time Innovations, Inc