|
RTI Connext DDS Micro C API
Version 4.1.0
|
|
RTI Connext DDS Micro C API
Version 4.1.0
|
Abstract System API. More...
Data Structures | |
| struct | OSAPI_SystemI |
| <<cert>> System API. More... | |
| struct | OSAPI_SystemProperty |
| <<cert>> The System Properties. More... | |
Macros | |
| #define | OSAPI_SYSTEM_MAX_HOSTNAME (64) |
| Maximum hostname length. | |
| #define | OSAPI_SystemI_INITIALIZER |
| <<cert>> Initializer for OSAPI_SystemI. | |
Typedefs | |
| typedef RTI_BOOL(* | OSAPI_System_start_timer_T )(OSAPI_Timer_T self, OSAPI_TimerTickHandlerFunction tick_handler) |
| Start a OSAPI timer. | |
| typedef RTI_INT32(* | OSAPI_System_get_timer_resolution_T )(void) |
| Get the resolution of the clock driving the timer in nano seconds. | |
| typedef RTI_BOOL(* | OSAPI_System_get_time_T )(OSAPI_NtpTime *now) |
| Get the current system time. | |
| typedef RTI_BOOL(* | OSAPI_System_initialize_T )(void) |
| Initialize the system. | |
| typedef RTI_BOOL(* | OSAPI_System_get_hostname_T )(char *const hostname) |
| Get the hostname. | |
| typedef RTI_BOOL(* | OSAPI_System_generate_uuid_T )(struct OSAPI_SystemUUID *uuid_out) |
| Generate a unique universal identifier (UUID). | |
| typedef RTI_BOOL(* | OSAPI_System_get_ticktime_T )(RTI_INT32 *sec, RTI_UINT32 *nanosec) |
| Get current tick time. | |
| typedef struct OSAPI_SystemI | OSAPI_SystemI |
| <<cert>> System API. | |
Functions | |
| RTI_BOOL | OSAPI_System_set_interface (struct OSAPI_SystemI *intf) |
| Set the system interface. | |
| 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_BOOL | OSAPI_System_clock_tick (RTI_UINT32 ticks) |
| Advance the internal RTI Connext DDS Micro timers with the number specified clock ticks. | |
| RTI_BOOL | OSAPI_System_clock_tick_from_time (void) |
| Advance the internal RTI Connext DDS Micro timers using the OSAPI_SystemI::get_time API. | |
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.
The following functions are not thread-safe:
| #define OSAPI_SYSTEM_MAX_HOSTNAME (64) |
Maximum hostname length.
| #define OSAPI_SystemI_INITIALIZER |
<<cert>> Initializer for OSAPI_SystemI.
| typedef RTI_BOOL(* OSAPI_System_start_timer_T)(OSAPI_Timer_T self, OSAPI_TimerTickHandlerFunction tick_handler) |
Start a OSAPI timer.
| [in] | self | Timer object. |
| [in] | tick_handler | Timer handle. |
| typedef RTI_INT32(* OSAPI_System_get_timer_resolution_T)(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.
| typedef RTI_BOOL(* OSAPI_System_get_time_T)(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.
| [out] | now | Time in NtpTime format. |
| typedef RTI_BOOL(* OSAPI_System_initialize_T)(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.
| typedef RTI_BOOL(* OSAPI_System_get_hostname_T)(char *const hostname) |
Get the hostname.
| [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 the NUL termination) the hostname is truncated. |
| typedef RTI_BOOL(* OSAPI_System_generate_uuid_T)(struct OSAPI_SystemUUID *uuid_out) |
Generate a unique universal identifier (UUID).
| [out] | uuid_out | The generated UUID value |
| typedef RTI_BOOL(* OSAPI_System_get_ticktime_T)(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.
| [out] | sec | The current ticktime in seconds |
| [out] | nanosec | Additional nanoseconds in the current ticktime |
| typedef struct OSAPI_SystemI OSAPI_SystemI |
<<cert>> System API.
The methods in this interface are called by the corresponding OSAPI_System function. For example, OSAPI_System_get_time() calls system->get_time().
| RTI_BOOL OSAPI_System_set_interface | ( | struct OSAPI_SystemI * | intf | ) |
Set the system interface.
This function sets the system interface, overriding the current system interface.
| [in] | intf | If intf is NULL, all interfaces are set to NULL. |
| RTI_BOOL OSAPI_System_get_property | ( | struct OSAPI_SystemProperty * | property | ) |
Get the system properties.
Copy the current system properties to the argument.
| [out] | property | The current system properties on success. |
| RTI_BOOL OSAPI_System_set_property | ( | struct OSAPI_SystemProperty * | property | ) |
Set the system properties.
The system properties can be set until the system has been initialized by calling OSAPI_System_initialize(). Note that OSAPI_System_initialize() is called by DDS_DomainParticipantFactory_get_instance().
| [in] | property | The system properties to set. |
| void OSAPI_System_get_native_interface | ( | struct OSAPI_SystemI * | intf | ) |
Get the native system interface.
This function returns the native system interface.
| [out] | intf | Cannot be NULL. |
| RTI_BOOL OSAPI_System_clock_tick | ( | RTI_UINT32 | ticks | ) |
Advance the internal RTI Connext DDS Micro timers with the number specified clock ticks.
RTI Connext DDS Micro uses internal timers to maintain and detect DDS events, such as sending participant announcements and detecting missed deadlines. These timers are updated at fixed intervals called ticks where each tick is equal to the time specified by the timer resolution from OSAPI_System_get_timer_resolution. However, because RTI Connext DDS Micro does not maintain its own timer reference it is up to the platform integration to inform RTI Connext DDS Micro when ticks have elapsed by calling the clock_tick function. The clock_tick function advances the internal timers with tick ticks. It is up to the caller to determine how many ticks have elapsed when calling the clock_tick function.
| [out] | ticks | The number of ticks that have passed. |
| RTI_BOOL OSAPI_System_clock_tick_from_time | ( | void | ) |
Advance the internal RTI Connext DDS Micro timers using the OSAPI_SystemI::get_time API.
RTI Connext DDS Micro uses internal timers to maintain and detect DDS events, such as sending participant announcements and detecting missed deadlines. These timers are updated at fixed intervals called ticks where each tick is equal to the time specified by the timer resolution from OSAPI_SystemI.get_timer_resolution. However, because RTI Connext DDS Micro does not maintain its own timer reference it is up to the platform integration to inform RTI Connext DDS Micro when ticks have elapsed by calling the clock_tick or 'clock_tick_from_time' function.
The clock_tick_from_time function advances the internal timers with tick ticks calculated from the amount of time that has elapsed between calls to OSAPI_SystemI.get_time. Each time clock_tick_from_time is called, OSAPI_SystemI.get_time is called to determine how much time since the previous call to clock_tick_from_time. The difference is converted to ticks using the resolution from OSAPI_SystemI.get_timer_resolution and all internal timers are advanced using the calculated number of ticks. Any residual time left, that is any time less than the OSAPI_SystemI.get_timer_resolution, is carried over and used on the next call to clock_tick_from_time.
Important: The first call to clock_tick_from_time establishes the baseline for calculating the difference in time.
RTI Connext DDS Micro C API Version 4.1.0
Copyright © Sun Dec 8 2024
Real-Time Innovations, Inc
