/***********************************************************************
Filename   : rvntptime.h
Description: NTP time module header
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
	{name: NtpTime}
	{superpackage: CUtils}
	{include: rvntptime.h}
	{description:	
		{p: This module provides functions for creating and manipulating
			NTP time values. Each time value is stored in two parts, seconds
			and fraction of a second. Refer to the NTP time specification
			for details on this format.}
	}
	{notes:
		{note:  This module does no locking at all. Any locking of
				an NTP time object is the responsibility of the user.}
	}
}
$*/
#ifndef RV_NTPTIME_H
#define RV_NTPTIME_H

#include "rvtypes.h"
#include "rvtime.h"

/*$
{type:
	{name: RvNtpTime}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:	
		{p: A time value in seconds and fraction of a second.}
	}
}
$*/
typedef struct {
	RvUint32  secs; 
	RvUint32  fraction;
} RvNtpTime;

/* constants for telling conversion functions how to work */
#define RV_NTPTIME_ABSOLUTE RV_TRUE
#define RV_NTPTIME_RELATIVE RV_FALSE

#if defined(__cplusplus)
extern "C" {
#endif 

/* Prototypes and macros: See documentation blocks below for details. */
RvNtpTime *RvNtpTimeConstruct(RvNtpTime *ntime, RvUint32 secs, RvUint32 fraction);
RVCOREAPI RvNtpTime * RVCALLCONV RvNtpTimeConstructFromTime(RvNtpTime *ntime, const RvTime *t, RvBool timetype);
RvNtpTime *RvNtpTimeConstructFrom64(RvNtpTime *result, RvUint64 ntime, RvUint8 decimal);
RvNtpTime *RvNtpTimeChop(RvNtpTime *result, const RvNtpTime *ntime, RvUint8 secbits, RvUint8 fracbits);
RvNtpTime *RvNtpTimeSubtract(RvNtpTime *result, const RvNtpTime *newtime, const RvNtpTime *oldtime);
RvNtpTime *RvNtpTimeAdd(RvNtpTime *result, const RvNtpTime *newtime, const RvNtpTime *oldtime);
RvTime *RvNtpTimeToTime(const RvNtpTime *ntime, RvTime *t, RvBool timetype);
RVCOREAPI RvUint64 RVCALLCONV RvNtpTimeTo64(const RvNtpTime *ntime, RvUint8 secbits, RvUint8 fracbits);
RvUint32 RvNtpTimeNsecsToFraction(RvInt32 nsecs);
RvInt32 RvNtpTimeFractionToNsecs(RvUint32 fraction);
#define RvNtpTimeGetSecs(_n) ((_n)->secs)
#define RvNtpTimeSetSecs(_n, _s) ((_n)->secs = (_s))
#define RvNtpTimeGetFraction(_n) ((_n)->fraction)
#define RvNtpTimeSetFraction(_n, _s) ((_n)->fraction = (_s))
#define RvNtpTimeDestruct(_n)
#define RvNtpTimeCopy(_n, _s) ((_n)->secs = (_s)->secs,(_n)->fraction = (_s)->fraction)

#if defined(RV_TEST_CODE)
void RvNtpTimeTest(void);
#endif

#if defined(__cplusplus)
}
#endif 

/*$
{function:
	{name: RvNtpTimeConstruct}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Constructs an NTP time.}
	}
	{proto: RvNtpTime *RvNtpTimeConstruct(RvTime *ntime, RvUint32 secs, RvIint32 fraction);}
	{params:
		{param: {n: ntime} {d: Pointer to NTP time structure to construct.}}
		{param: {n: secs} {d: Initial value for seconds.}}
		{param: {n: fraction} {d: Initial fraaction value.}}
	}
	{returns: A pointer to the NTP time structure or, if there is an error, NULL.}
}
$*/
/*$
{function:
	{name: RvNtpTimeConstructFromTime}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Constructs an NTP time from a standard time value. It handles both
			relative time and absolute (actual clock) times. If timetype is set
			to RV_NTPTIME_RELATIVE then the time will simply be converted from
			seconds and nanoseconds to seconds and fraction of a second. If the
			timetype is set to RV_NTPTIME_ABSOLUTE, then the time will be
			considered to be seconds and nanoseconds since January 1, 1970 and
			will be convert to an NTP time of seconds and fraction of a second
			since January 1, 1900.}
	}
	{proto: RvNtpTime *RvNtpTimeConstructFromTime(RvNtpTime *ntime, const RvTime *t, RvBool timetype);}
	{params:
		{param: {n: ntime} {d: Pointer to NTP time structure to construct.}}
		{param: {n: t} {d: Time to convert from.}}
		{param: {n: timetype} {d: Type of time to convert: RV_NTPTIME_RELATIVE or RV_NTPTIME_ABSOLUTE.}}
	}
	{returns: A pointer to the NTP time structure or, if there is an error, NULL.}
	{notes:
		{note:  For ABSOLUTE times, not all valid values of time can be represented
				in the the NTP time format. Dates in 2036 and later can not be
				converted.}
		{note:  The conversion between nanoseconds and fraction of a second may
				incur a small amount of round off error.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeConstructFrom64}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Constructs an NTP time from a 64 bit NTP time representation.}
	}
	{proto: RvNtpTime *RvNtpTimeConstructFrom64(RvNtpTime *result, RvUint64 ntime, RvUint8 decimal);}
	{params:
		{param: {n: result} {d: Pointer to NTP time structure to construct.}}
		{param: {n: ntime} {d: 64 bit representation of an NTP time.}}
		{param: {n: decimal} {d: Number of bits in ntime which is the fraction part of the number (0 = no fraction, 64 = no seconds).}}
	}
	{returns: A pointer to the NTP time structure or, if there is an error, NULL.}
}
$*/
/*$
{function:
	{name: RvNtpTimeChop}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Chops bits off of Ntp times. Some application require smaller NTP numbers
			that 32 bits of seconds and a 32 bit fraction. This fucntion will chop
			off unneeded bits by zeroing them out.}
	}
	{proto: RvNtpTime *RvNtpTimeChop(RvNtpTime *result, const RvNtpTime *ntime, RvUint8 secbits, RvUint8 fracbits);}
	{params:
		{param: {n: result} {d: Pointer to NTP time structure where result will be stored.}}
		{param: {n: ntime} {d: Pointer to NTP time structure to chop.}}
		{param: {n: secbits} {d: Number of bits of the seconds value to keep (0 - 32).}}
		{param: {n: fracbits} {d: Number of bits of the fraction to keep (0 - 32).}}
	}
	{returns: A pointer to the resulting NTP time structure or, if there is an error, NULL.}
}
$*/
/*$
{function:
	{name: RvNtpTimeSubtract}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Subracts two NTP time values (result = newtime - oldtime).}
	}
	{proto: RvNtpTime *RvntpTimeSubract(RvNtpTime *result, const RvNtpTime *newtime, const RvNtpTime *oldtime);}
	{params:
		{param: {n: result} {d: Pointer to time structure where result will be stored.}}
		{param: {n: newtime} {d: Pointer to NTP time structure to subract from. }}
		{param: {n: oldtime} {d: Pointer to NTP time structure with value to subract.}}
	}
	{returns: A pointer to result or, if there is an error, NULL.}
	{notes:
		{note:  Since NTP time values are unsigned, newtime must be larger than oldtime and
				the earliest real time that can be represented is January 1, 1900.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeAdd}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Adds two NTP time values (result = time1 + time2).}
	}
	{proto: RvNtpTime *RvNtpTimeAdd(RvNtpTime *result, const RvNtpTime *time1, const RvNtpTime *time2);}
	{params:
		{param: {n: result} {d: Pointer to time structure where result will be stored.}}
		{param: {n: time1} {d: Pointer to first NTP time.}}
		{param: {n: time2} {d: Pointer to second NTP time structure.}}
	}
	{returns: A pointer to result or, if there is an error, NULL.}
	{notes:
		{note:  Absolute NTP time values wrap in the year 2036.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeToTime}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Converts NTP time to a standard time value. It handles both
			relative time and absolute (actual clock) times. If timetype is set
			to RV_NTPTIME_RELATIVE then the NTP time will simply be converted
			from seconds and fraction of a second to seconds and nanoseconds. If
			the timetype is set to RV_NTPTIME_ABSOLUTE, then the NTP time will be
			considered to be seconds fraction of a second since January 1, 1900
			and will be coverted to seconds and nanoseconds since January 1, 1970.}
	}
	{proto: RvTime *RvNtpTimeToTime(const RvNtpTime *ntime, RvTime *t, RvBool timetype);}
	{params:
		{param: {n: ntime} {d: Pointer to NTP time structure to convert from.}}
		{param: {n: t} {d: Pointer to time to store the result.}}
		{param: {n: timetype} {d: Type of time to convert: RV_NTPTIME_RELATIVE or RV_NTPTIME_ABSOLUTE.}}
	}
	{returns: A pointer to the time structure (t) or, if there is an error, NULL.}
	{notes:
		{note:  For ABSOLUTE times, not all valid values of NTP can be represented
				in the standard time format. Dates in 1902 and earlier can not be
				converted.}
		{note:  The conversion between fraction of a seconds and nanoseconds may
				incur a small amount of round off error.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeTo64}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Converts an NTP time to a 64 bit representation. The number of bits to use for
			seconds and the fraction may be set. For example, setting secbits to 32 and
			fracbits to 32 will return a full 64 bit representation of the NTP time. Or,
			setting secbits to 4 and fracbits to 12 will return a 64 bit number where
			the low order 12 bits are the fraction, followed by 4 bits of the seconds,
			and the high order 32 bits simply set to 0.}
	}
	{proto: RvUint64 RvNtpTimeTo64(const RvNtpTime *ntime, RvUint8 secbits, RvUint8 fracbits);}
	{params:
		{param: {n: ntime} {d: Pointer to NTP time structure to convert.}}
		{param: {n: secbits} {d: Number of bits of the seconds value to include (0 to 64).}}
		{param: {n: frac} {d: Number of bits of the fraction to include (0 to 64).}}
	}
	{returns: The 64 bit represention of the NTP value.}
}
$*/
/*$
{function:
	{name: RvNtpTimeNsecsToFraction}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Converts a value in nanoseconds to an NTP fraction. The nanoseconds value
			must be less than one second.}
	}
	{proto: Rvuint32 RvNtpTimeNsecsToFraction(RvInt32 nsecs);}
	{params:
		{param: {n: nsecs} {d: Nanoseconds (0 to 999999999.}}
	}
	{returns: 32 bit NTP fraction.}
	{notes:
		{note:  The conversion between nanoseconds and fraction of a second may
				incur a small amount of round off error.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeFractionToNsecs}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Converts an NTP fraction to nanoseconds.}
	}
	{proto: Rvuint32 RvNtpTimeFractionToNsecs(RvUint32 fraction);}
	{params:
		{param: {n: fraction} {d: NTP fraction.}}
	}
	{returns: Nanoseconds (0 to 999999999).}
	{notes:
		{note:  The conversion between the NTP fraction of a second and
				nanoseconds may incur a small amount of round off error.}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeGetSecs}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Get the seconds value from a NTP time structure.}
	}
	{proto: RvUint32 RvNtpTimeGetSecs(RvNtpTime *_n);}
	{params:
		{param: {n: _n} {d: Pointer to NTP time structure to get information from.}}
	}
	{returns: Seconds.}
}
$*/
/*$
{function:
	{name: RvNtpTimeSetSecs}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Sets the seconds value of an NTP time structure.}
	}
	{proto: RvUint32 RvNtpTimeSetSecs(RvNtpTime *_n, RvUint32 _s);}
	{params:
		{param: {n: _n} {d: Pointer to NTP time structure to set information in.}}
		{param: {n: _s} {d: Seconds.}}
	}
	{returns: Seconds value that was set.}
}
$*/
/*$
{function:
	{name: RvNtpTimeGetFraction}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Get the fraction of a second value from an NTP time structure.}
	}
	{proto: RvUint32 RvTimeGetFraction(RvNtpTime *_n);}
	{params:
		{param: {n: _n} {d: Pointer to NTP time structure to get information from.}}
	}
	{returns: NTP fraction of a second.}
}
$*/
/*$
{function:
	{name: RvTimeSetFraction}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Sets the fraction of a second value of an NTP time structure.}
	}
	{proto: RvUint32 RvNtpTimeSetFraction(RvNtpTime *_n, RvUint32 _s);}
	{params:
		{param: {n: _n} {d: Pointer to NTP time structure to set information in.}}
		{param: {n: _s} {d: NTP fraction of a second.}}
	}
	{returns: NTP fraction of a second value that was set.}
}
$*/
/*$
{function:
	{name: RvNtpTimeDestruct}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Destructs an NTP time object.}
	}
	{proto: void RvNtpTimeDestruct(RvNtpTime *_n);}
	{params:
		{param: {n: _t} {d: Pointer to NTP time object to be destructed.}}
	}
}
$*/
/*$
{function:
	{name: RvNtpTimeCopy}
	{superpackage: NtpTime}
	{include: rvntptime.h}
	{description:
		{p: Copies the value of one NTP time structure to another.}
	}
	{proto: RvUint32 RvNtpTimeCopy(RvNtpTime *_n, RvTime *_s);}
	{params:
		{param: {n: _n} {d: Pointer to NTP time structure to copy information to.}}
		{param: {n: _s} {d: Pointer to NTP time structure to copy information from.}}
	}
	{returns: Fraction of a second value that was copied.}
}
$*/

#endif /* RV_NTPTIME_H */