rvtm.h

基于h323协议的软phone

/***********************************************************************
Filename   : rvtm.h
Description: rvtm header file
************************************************************************
      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: Tm}
	{superpackage: CCore}
	{include: rvtm.h}
	{description:	
		{p: This module provides functions for creating and manipulating calendar times.
			It is basically the same as the ANSI tm structure with the addition of
			nanoseconds, accessor functions, and more natural ranges for some parameters.}
	}
}
$*/
#ifndef RV_TM_H
#define RV_TM_H

#include "rvccore.h"
#include "rvtime.h"
#if (RV_OS_TYPE != RV_OS_TYPE_WINCE)
#include <time.h>
#endif
#include <string.h>

#if !defined(RV_TM_TYPE) || ((RV_TM_TYPE != RV_TM_POSIX) && \
    (RV_TM_TYPE != RV_TM_VXWORKS) && (RV_TM_TYPE != RV_TM_PSOS) && \
    (RV_TM_TYPE != RV_TM_OSE) && (RV_TM_TYPE != RV_TM_NUCLEUS) && \
    (RV_TM_TYPE != RV_TM_WIN32) && (RV_TM_TYPE != RV_TM_WINCE))
#error RV_TM_TYPE not set properly
#endif


#if (RV_OS_TYPE == RV_OS_TYPE_WINCE)
/* No time.h - we need to declare struct tm ourselves */
struct tm {
        int tm_sec;     /* seconds after the minute - [0,59] */
        int tm_min;     /* minutes after the hour - [0,59] */
        int tm_hour;    /* hours since midnight - [0,23] */
        int tm_mday;    /* day of the month - [1,31] */
        int tm_mon;     /* months since January - [0,11] */
        int tm_year;    /* years since 1900 */
        int tm_wday;    /* days since Sunday - [0,6] */
        int tm_yday;    /* days since January 1 - [0,365] */
        int tm_isdst;   /* daylight savings time flag */
        };

/* Clock ticks macro - ANSI version */
#define CLOCKS_PER_SEC  1000

#endif


/*$
{type:
	{name: RvTm}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:	
		{p: A calendar time object.}
	}
}
$*/
typedef struct {
	struct tm tm;    /* just use ANSI tm definition for simplicity */
	RvInt32 nsec;
} RvTm;

/* minimum size of character buffer required by RvTimeAsctime */
#define RV_TM_ASCTIME_BUFSIZE 30

/* Constants for setting the isdst field for daylight savings time */
#define RV_TM_STANDARD 0 /* Standard time */
#define RV_TM_DST 1      /* Daylight Savings time */
#define RV_TM_UNKNOWN (-1) /* unknown (error or let library calculate) */

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

/* Prototypes and macros: See documentation blocks below for details. */
RvStatus RvTmInit(void);
RvStatus RvTmEnd(void);
RvStatus RvTmConvertToTime(RvTm *tm, RvTime *t);
RVCOREAPI RvStatus RVCALLCONV RvTmConstructUtc(RvTm *tm, const RvTime *t);
RvStatus RvTmConstructLocal(RvTm *tm, const RvTime *t);
RvChar *RvTmAsctime(const RvTm *tm, RvChar *buf, RvSize_t bufsize);
RvSize_t RvTmStrftime(const RvTm *tm, const RvChar *format, RvChar *result, RvSize_t maxsize);
#define RvTmConstruct(_t) ((RvTm *)memset((_t), 0, sizeof(RvTm)))
#define RvTmDestruct(_t)
#define RvTmGetNsec(_t) ((_t)->nsec)
#define RvTmSetNsec(_t, _n) ((_t)->nsec = (_n))
#define RvTmGetSec(_t) ((_t)->tm.tm_sec)
#define RvTmSetSec(_t, _s) ((_t)->tm.tm_sec = (_s))
#define RvTmGetMin(_t) ((_t)->tm.tm_min)
#define RvTmSetMin(_t, _m) ((_t)->tm.tm_min = (_m))
#define RvTmGetHour(_t) ((_t)->tm.tm_hour)
#define RvTmSetHour(_t, _h) ((_t)->tm.tm_hour = (_h))
#define RvTmGetMday(_t) ((_t)->tm.tm_mday)
#define RvTmSetMday(_t, _m) ((_t)->tm.tm_mday = (_m))
#define RvTmGetMon(_t) ((_t)->tm.tm_mon + 1)
#define RvTmSetMon(_t, _m) ((_t)->tm.tm_mon = (_m) - 1)
#define RvTmGetYear(_t) ((_t)->tm.tm_year + 1900)
#define RvTmSetYear(_t, _y) ((_t)->tm.tm_year = (_y) - 1900)
#define RvTmGetWday(_t) ((_t)->tm.tm_wday)
#define RvTmSetWday(_t, _w) ((_t)->tm.tm_wday = (_w))
#define RvTmGetYday(_t) ((_t)->tm.tm_yday)
#define RvTmSetYday(_t, _y) ((_t)->tm.tm_yday = (_y))
#define RvTmGetIsdst(t) ((t)->tm.tm_isdst)
#define RvTmSetIsdst(_t, _i) ((_t)->tm.tm_isdst = (_i))

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

#if defined(__cplusplus)
}
#endif 

/* Function Documentation */
/*$
{function scope="protected":
	{name: RvTmInit}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Initializes the Tm module. Must be called once (and
			only once) before any other functions in the module are called.}
	}
	{proto: RvStatus RvTmInit(void);}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
	{name: RvTmEnd}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Shuts down the Tm module. Must be called once (and
			only once) when no further calls to this module will be made.}
	}
	{proto: RvStatus RvTmEnd(void);}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvTmConstruct}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Creates a blank calendar time object.}
	}
	{proto: RvTm *RvTmConstruct(RvTm *_t);}
	{params:
		{param: {n: _t}  {d: Pointer to calendar time object to be constructed.}}
	}
	{returns: A pointer to the calendar time object that was passed in.}
}
$*/
/*$
{function:
	{name: RvTmDestruct}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Destroys a calendar time object.}
	}
	{proto: void RvTmDestruct(RvTm *_t);}
	{params:
		{param: {n: _t}  {d: Pointer to a calendar time object to be destructed.}}
	}
}
$*/
/*$
{function:
	{name: RvTmConvertToTime}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Converts a calendar time into a standard time (seconds and nanoseconds since 1970.}
		{p: This function will also normalize the values of the calendar object (which might even
			be the sole purpose for calling it). For example, if the value of seconds is set to 65,
			it will be normalized to a value of 5 and minutes will be incremented a long with any
			other values that might be affected by it.}
	}
	{proto: RvStatus RvTmConvertToTime(RvTm *tm, RvTime *t);}
	{params:
		{param: {n: tm} {d: pointer to calendar time that is to be converted.}}
		{param: {n: t}  {d: pointer to time structure where the result will be stored.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:	The date range of calendar times is larger than the range that can be
				represented by time. If the calendar time fall outside of this range
				then the time result will not be correct (but the calenter time will
				still be normalized properly).}
	}
}
$*/
/*$
{function:
	{name: RvTmConstructUtc}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Creates a calendar time object representing UTC time based on a standard time.}
	}
	{proto: RvTm *RvTmConstructUtc(RvTm *tm, RvTime *t);}
	{params:
		{param: {n: tm} {d: pointer to a calendar time object to be constructed.}}
		{param: {n: t}  {d: pointer to time structure containing the time.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:	Some systems do not support time zones, thus UTC time may actually
				be local time, depending on how the clock was set.}
	}
}
$*/
/*$
{function:
	{name: RvTmConstructLocal}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Creates a calendar time object representing local time based on a standard time.}
	}
	{proto: RvTm *RvTmConstructLocal(RvTm *tm, RvTime *t);}
	{params:
		{param: {n: tm} {d: pointer to a calendar time object to be constructed.}}
		{param: {n: t}  {d: pointer to time structure containing the time.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:	Some systems do not support time zones and local time will report the
				same time as UTC time.}
		{note:	Some systems do not support daylight savings time properly and will not
				automatically adjust for it.}
	}
}
$*/
/*$
{function:
	{name: RvTmAsctime}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Creates a character string representation of calendar time. Equivalent to
			ANSI asctime function.}
	}
	{proto: RvTm *RvTmAsctime(const RvTm *tm, RvChar *buf, RvInt32 bufsize);}
	{params:
		{param: {n: tm} {d: pointer to a calendar time object to create the string from.}}
		{param: {n: buf}  {d: pointer to buffer where string should be copied.}}
		{param: {n: bufsize}  {d: size of buffer (must be at least size RV_TM_ASCTIME_BUFSIZE.}}
	}
	{returns: A pointer to the string buffer.}
}
$*/
/*$
{function:
	{name: RvTmStrftime}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Creates a custom character string representation of calendar time. Equivalent to
			ANSI strftime function.}
	}
	{proto: RvInt32 RvTmStrftime(const RvTm *tm, const RvChar *format, RvChar *result, RvInt32 maxsize);}
	{params:
		{param: {n: tm} {d: pointer to a calendar time object to create the string from.}}
		{param: {n: format} {d: standard ANSI strftime formatting string.}}
		{param: {n: result} {d: pointer to buffer where the resulting string should be copied.}}
		{param: {n: bufsize} {d: size of result buffer}}
	}
	{returns: The size of the string that was generated (0 if there was a problem).}
	{notes:
		{note:	Use only ANSI standard formats in the format string to insure compatability
				across different systems.}
	}
}
$*/
/*$
{function:
	{name: RvTmGetNsec}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Gets the nanseconds component of a calender time.}
	}
	{proto: RvInt32 RvTmGetNsec(RvTm *_t);}
	{params:
		{param: {n: _t} {d: pointer to a calendar time object.}}
	}
	{returns: The nanoseconds component of the calendar time.}
}
$*/
/*$
{function:
	{name: RvTmSetNsec}
	{superpackage: Tm}
	{include: rvtm.h}
	{description:
		{p: Sets the nanseconds component of a calender time.}
	}