OSAPI Time

Data Structures
struct	OSAPI_NtpTime
	NtpTime API. More...

Macros
#define	OSAPI_NTP_TIME_SEC_MAX   ((RTI_INT32)0x7fffffff)
#define	OSAPI_NTP_TIME_FRAC_MAX   ((RTI_UINT32)0xffffffff)
#define	OSAPI_NtpTime_increment(answer, time)
	answer += time.
#define	OSAPI_NtpTime_decrement(answer, time)
	Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.
#define	OSAPI_NTP_TIME_ZERO   {0,0}
	Zero time.
#define	OSAPI_NTP_TIME_MAX   {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}
#define	OSAPI_NTP_TIME_NSEC_PER_SEC   (1000000000)
#define	OSAPI_NTP_TIME_USEC_PER_SEC   (1000000)
#define	OSAPI_NTP_TIME_MSEC_PER_SEC   (1000)
#define	OSAPI_NTP_TIME_NSEC_PER_USEC   (1000)
#define	OSAPI_NTP_TIME_USEC_PER_MSEC   (1000)
#define	OSAPI_NTP_TIME_SEC_PER_SEC   (1)
#define	OSAPI_NTP_TIME_NSEC_PER_MSEC   (1000000)

Typedefs
typedef struct OSAPI_NtpTime	OSAPI_NtpTime
	NtpTime API.

Functions
void	OSAPI_NtpTime_from_millisec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 msec)
	Macro to convert from seconds and milliseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_millisec (RTI_INT32 *const s, RTI_UINT32 *const msec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.
void	OSAPI_NtpTime_from_microsec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 usec)
	Macro to convert from seconds and microseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_microsec (RTI_INT32 *const s, RTI_UINT32 *const usec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.
void	OSAPI_NtpTime_from_nanosec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 nsec)
	Macro to convert from seconds and nanoseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_nanosec (RTI_INT32 *const s, RTI_UINT32 *const nsec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.
RTI_BOOL	OSAPI_NtpTime_is_infinite (const struct OSAPI_NtpTime *const time)
void	OSAPI_NtpTime_subtract (struct OSAPI_NtpTime *const answer, const struct OSAPI_NtpTime *const t1, const struct OSAPI_NtpTime *const t2)
	answer = t1 - t2.
RTI_INT32	OSAPI_NtpTime_compare (const struct OSAPI_NtpTime *time1, const struct OSAPI_NtpTime *time2)
	Compare two NTP structures.

---

Detailed Description

---

Macro Definition Documentation

#define OSAPI_NTP_TIME_SEC_MAX   ((RTI_INT32)0x7fffffff)

The maximum number of seconds that can be represented using NTP time.

#define OSAPI_NTP_TIME_FRAC_MAX   ((RTI_UINT32)0xffffffff)

The largest possible value of the fraction field in NTP time.

#define OSAPI_NtpTime_increment	(		answer,
			time
	)

Value:

{ \
    RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  += (time)->sec; \
    (answer)->frac += (time)->frac; \
    if (((answer)->frac < (time)->frac) || ((answer)->frac < currentFrac)) { \
        (answer)->sec++; \
    } \
}

answer += time.

This macro does not check for overflow.

Parameters:

answer	struct OSAPI_NtpTime
time	struct OSAPI_NtpTime

#define OSAPI_NtpTime_decrement	(		answer,
			time
	)

Value:

{ \
    RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  -= (time)->sec; \
    (answer)->frac -= (time)->frac; \
    if (((answer)->frac > currentFrac)) { (answer)->sec--; } \
}

Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.

Precondition: Postcondition: answer -= time.

Parameters:

answer	struct OSAPI_NtpTime
time	struct OSAPI_NtpTime

#define OSAPI_NTP_TIME_ZERO   {0,0}

Zero time.

This global variable is for convenience. It allows you to see if a RTITime variable is negative or positive by comparing against this.

See also:

RtiTimeCompare

#define OSAPI_NTP_TIME_MAX   {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}

Represents the maximum timevalue that can be represented using the NTP time format. For all practical purposes, it can be considered equivalent to infinity.

#define OSAPI_NTP_TIME_NSEC_PER_SEC   (1000000000)

The number of nanoseconds per second. 1e9.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_USEC_PER_SEC   (1000000)

The number of microseconds per second. 1e6.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_MSEC_PER_SEC   (1000)

The number of milliseconds per second. 1e3.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_NSEC_PER_USEC   (1000)

The number of microseconds per milliseconds. 1e3.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_USEC_PER_MSEC   (1000)

The number of microseconds per milliseconds. 1e3.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_SEC_PER_SEC   (1)

The number of seconds per second. 1.

See also:

RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_NSEC_PER_MSEC   (1000000)

The number of nano seconds per milli second. 1e6.

See also:

RtiTimePack RtiTimeUnpack

---

Typedef Documentation

typedef struct OSAPI_NtpTime OSAPI_NtpTime

NtpTime API.

NTP Time representation.

Expresses time in NTP format. The second field is simply an integer expressing seconds. The fraction field expresses 1/2^32 of a second. We strongly urge customers to use our provided macros to convert this format to and from human readable form.

Example:

The following is a simple example on how to prepare a struct OSAPI_NtpTime structure to be 1.5 seconds.

 *   struct OSAPI_NtpTime ntpTime;
 *
 *   OSAPI_NtpTime_from_millisec(ntpTime, 1, 500);
 * 

---

Function Documentation

void OSAPI_NtpTime_from_millisec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	msec
	)

Macro to convert from seconds and milliseconds to struct OSAPI_NtpTime format.

This macro assumes that msec < 1000. It is the caller's responsibility to ensure this.

Parameters:

time	Contains the answer.
s	Seconds to convert.
msec	Milliseconds to convert.

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_to_millisec

void OSAPI_NtpTime_to_millisec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	msec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.

This macro does not check for overflow, so for a near-infinite time value, the conversion result may end up being negative. It is the responsibility of the user to avoid passing these large time values.

Parameters:

s	Holds the seconds answer.
msec	Holds the millisecond answer.
time	The time to convert to second(s) and millisecond(s).

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_from_millisec

void OSAPI_NtpTime_from_microsec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	usec
	)

Macro to convert from seconds and microseconds to struct OSAPI_NtpTime format.

This macro does not check for overflow, so for a near-infinite time value, the conversion result may end up being negative. It is the caller's responsibility to avoid passing these large time values.

Parameters:

time	Contains the answer.
s	Seconds to covert.
usec	Microseconds to convert.

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_to_millisec

void OSAPI_NtpTime_to_microsec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	usec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.

Parameters:

s	Holds the second portion.
usec	Holds the microsecond fraction.
time	The time to convert to second(s) and microsecond(s)

This macro does not check for overflow, so for a near-infinite time value, the conversion result may end up being negative. It is the caller's responsibility to avoid passing these large time values.

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_from_millisec

void OSAPI_NtpTime_from_nanosec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	nsec
	)

Macro to convert from seconds and nanoseconds to struct OSAPI_NtpTime format.

This macro assumes that nsec < 1000000000. It is the caller's responsibility to ensure this. The accuracy of this conversion over the whole range of nanosecond values is at least 1 nanosecond.

Parameters:

time	Holds the answer.
s	Seconds to convert.
nsec	Nanoseconds to convert.

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_to_nanosec

void OSAPI_NtpTime_to_nanosec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	nsec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.

The accuracy of this conversion over the whole range of struct OSAPI_NtpTime values is at least 1 nanosecond.

Parameters:

s	Holds the second portion.
nsec	Holds the nanosecond portion.
time	Time to convert to second(s) and nanosecond(s).

See also:

struct OSAPI_NtpTime OSAPI_NtpTime_from_nanosec

RTI_BOOL OSAPI_NtpTime_is_infinite

(

const struct OSAPI_NtpTime *const

time

)

A NULL struct OSAPI_NtpTime pointer is considered infinity. This is consistent with the concept of infinite time on UNIX systems.

In addition, if the seconds field equals OSAPI_NTP_TIME_SEC_MAX, the time value is also considered infinite.

Parameters:

time	Pointer to RTITime.

Returns:

RTI_TRUE if time is infinite, RTI_FALSE otherwise.

void OSAPI_NtpTime_subtract	(	struct OSAPI_NtpTime *const	answer,
		const struct OSAPI_NtpTime *const	t1,
		const struct OSAPI_NtpTime *const	t2
	)

answer = t1 - t2.

Parameters:

answer	struct OSAPI_NtpTime
t1	struct OSAPI_NtpTime`
t2	struct OSAPI_NtpTime

RTI_INT32 OSAPI_NtpTime_compare	(	const struct OSAPI_NtpTime *	time1,
		const struct OSAPI_NtpTime *	time2
	)

Compare two NTP structures.

Parameters:

time1	struct OSAPI_NtpTime
time2	struct OSAPI_NtpTime

Returns:

0 if time1 = time2 a positive integer if time1 > time2 a negative integer if time1 < time2