libtime.h File Reference

Interface to time functionality (libtime and clockd). More...

Defines

#define CLOCKD_SERVICE   "com.nokia.clockd"

#define CLOCKD_PATH   "/com/nokia/clockd"

#define CLOCKD_INTERFACE   "com.nokia.clockd"

#define CLOCKD_TIME_CHANGED   "time_changed"

Functions

int time_get_synced (void)

time_t time_get_time (void)

int time_set_time (time_t tick)

int time_get_net_time (time_t *tick, char *s, size_t max)

int time_is_net_time_changed (time_t *tick, char *s, size_t max)

int time_activate_net_time (void)

time_t time_mktime (struct tm *tm, const char *tz)

int time_get_timezone (char *s, size_t max)

int time_get_tzname (char *s, size_t max)

int time_set_timezone (const char *tz)

int time_get_utc (struct tm *tm)

int time_get_utc_ex (time_t tick, struct tm *tm)

int time_get_local (struct tm *tm)

int time_get_local_ex (time_t tick, struct tm *tm)

int time_get_remote (time_t tick, const char *tz, struct tm *tm)

int time_get_default_timezone (char *s, size_t max)

int time_get_time_format (char *s, size_t max)

int time_set_time_format (const char *fmt)

int time_format_time (const struct tm *tm, const char *fmt, char *s, size_t max)

int time_get_utc_offset (const char *tz)

int time_get_dst_usage (time_t tick, const char *tz)

double time_diff (time_t t1, time_t t2)

int time_get_time_diff (time_t tick, const char *tz1, const char *tz2)

int time_set_autosync (int enable)

int time_get_autosync (void)

int time_is_operator_time_accessible (void)

Detailed Description

This is the interface to time functions.
Include also file <time.h>

Link your application with -lrt

Define Documentation

#define CLOCKD_SERVICE "com.nokia.clockd"

CLOCKD_SERVICE: The name of the clockd D-Bus service.

Referenced by client_new_req(), and server_init().

#define CLOCKD_PATH "/com/nokia/clockd"

CLOCKD_PATH: The D-Bus object path for the clockd daemon.

Referenced by client_new_req(), send_time_change_indication(), and server_filter().

#define CLOCKD_INTERFACE "com.nokia.clockd"

CLOCKD_INTERFACE: The D-Bus interface the commands/signal use.

Referenced by client_new_req(), send_time_change_indication(), and server_filter().

#define CLOCKD_TIME_CHANGED "time_changed"

D-Bus signal sent when time settings has been changed. Argument is int32 time. 0 means that time itself has not been changed (i.e timezone, for example, has changed).

Referenced by send_time_change_indication().

Function Documentation

int time_get_synced ( void )

Function to call when "time changed" indication (see osso_time_set_notification_cb) has been received by the application.
If the application does not wish to link with libosso, then it can listen to the CLOCKD_TIME_CHANGED D-Bus signal, that clockd sends also.

The time changed indication is broadcasted to all libtime users when:

time is changed (time_set_time or by automatic network time change)
time zone is changed (time_set_timezone or by automatic network time change)
time formatter is changed (time_set_time_format)
automatic network time setting is changed (time_set_autosync)

Returns:: 0 if OK, -1 if fails

time_t time_get_time ( void )

Get current time - see time()

int time_set_time ( time_t tick )

Set current system and RTC time

Parameters:

tick

Time since Epoch

Returns:: 0 if OK, -1 if fails

int time_get_net_time	(	time_t *	tick,
		char *	s,
		size_t	max
	)

Get the network time (in case that autosync is not enabled and a network time change indication has received)

Parameters:

	tick	Supplied buffer to store network time (ticks since Epock)
	s	Supplied buffer to store network timezone
	max	Size of 's', including terminating NUL

Returns:: Number of characters wrote to 's'. -1 if network time has not been changed. Does not write more than size bytes (including the trailing ). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated.

Referenced by time_is_net_time_changed().

int time_is_net_time_changed	(	time_t *	tick,
		char *	s,
		size_t	max
	)

Deprecated, see time_get_net_time

int time_activate_net_time ( void )

Set current system and RTC time according to operator network time in case time_is_net_time_changed() indicates change

Returns:: 0 if OK, -1 if fails (for example if the network time has not changed)

time_t time_mktime	(	struct tm *	tm,
		const char *	tz
	)

Make time_t from struct tm. Like mktime() but timezone can be given.

Parameters:

	tm	See mktime
	tz	Time zone variable. All formats that glibc supports can be given. NULL if current zone is used. See http://www.gnu.org/software/libtool/manual/libc/TZ-Variable.html

Returns:: Time since Epoch (0) if error

int time_get_timezone	(	char *	s,
		size_t	max
	)

Get current time zone. May return empty string if time zone has not been set.
Example output:
:US/Central
GMT+5:00GMT+4:00,0,365
The latter format is returned when network has indicated time zone change (the actual location is not known)

Parameters:

	s	Supplied buffer to store timezone
	max	Size of 's', including terminating NUL

Returns:: Number of characters wrote to 's'. Does not write more than size bytes (including the trailing ). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. If an output error is encountered, a negative value is returned.

int time_get_tzname	(	char *	s,
		size_t	max
	)

Get current time zone name (like "EET")

Parameters:

	s	Supplied buffer to store tzname
	max	Size of 's', including terminating NUL

Returns:: Number of characters wrote to 's'. Does not write more than size bytes (including the trailing ). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. If an output error is encountered, a negative value is returned.

int time_set_timezone ( const char * tz )

Set current time zone ("TZ")

Parameters:

tz

Time zone variable. All formats that glibc supports can be given.
See http://www.gnu.org/software/libtool/manual/libc/TZ-Variable.html
It is, however recommended to use /usr/share/zoneinfo -method, for example:
:Europe/Rome and not like this: EST+5EDT,M4.1.0/2,M10.5.0/2

Returns:: 0 if OK, -1 if fails

int time_get_utc ( struct tm * tm )

Get current time in UTC. Inspired by time() and gmtime_r()

Parameters:

tm

Supplied buffer to store result

Returns:: 0 if OK, -1 if error

int time_get_utc_ex	(	time_t	tick,
		struct tm *	tm
	)

Get time in UTC.

Parameters:

	tick	Time
	tm	Supplied buffer to store result

Returns:: 0 if OK, -1 if error

int time_get_local ( struct tm * tm )

Get current local time. Inspired by time() and localtime_r().

Parameters:

tm

Supplied buffer to store tm

Returns:: 0 if OK, -1 if error

int time_get_local_ex	(	time_t	tick,
		struct tm *	tm
	)

Get local time.

Parameters:

	tick	Time
	tm	Supplied buffer to store tm

Returns:: 0 if OK, -1 if error

int time_get_remote	(	time_t	tick,
		const char *	tz,
		struct tm *	tm
	)

Get local time in given zone. Inspired by setting TZ temporarily and localtime_r().

Parameters:

	tick	Time since Epoch
	tz	Time zone variable. All formats that glibc supports can be given. See http://www.gnu.org/software/libtool/manual/libc/TZ-Variable.html
	tm	Supplied buffer to store tm

Returns:: 0 if OK, -1 if error

int time_get_default_timezone	(	char *	s,
		size_t	max
	)

Get the default time zone. Empty string is returned if no default zone has been defined.

Parameters:

	s	Supplied buffer to store the zone
	max	Size of 's', including terminating NUL

Returns:: Number of characters wrote to 's'. Does not write more than size bytes (including the trailing ). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. If an output error is encountered, a negative value is returned.

int time_get_time_format	(	char *	s,
		size_t	max
	)

Get current time string formatter. Inspired by strftime().

Parameters:

	s	Supplied buffer to store formatter
	max	Size of 's', including terminating NUL

Returns:: Number of characters wrote to 's'. Does not write more than size bytes (including the trailing ). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. If an output error is encountered, a negative value is returned.

int time_set_time_format ( const char * fmt )

Set current time string formatter. Inspired by strftime().

Parameters:

fmt

Formatter string

Returns:: 0 if OK, -1 if fails

int time_format_time	(	const struct tm *	tm,
		const char *	fmt,
		char *	s,
		size_t	max
	)

Format given time to string. Inspired by strftime() and localtime_r().

Parameters:

	tm	Time
	fmt	Formatter, see strftime and time_set_time_format and time_get_time_format, NULL if active formatter is used.
	s	Supplied buffer to store result
	max	Size of 's', including terminating NUL

Returns:: See strftime()

int time_get_utc_offset ( const char * tz )

Get utc offset (secs west of GMT) in the named TZ. The current daylight saving time offset is included.

Parameters:

tz

Time zone, all formats that glibc supports can be given. NULL to use current tz.
See http://www.gnu.org/software/libtool/manual/libc/TZ-Variable.html

Returns:: Secs west of GMT.

int time_get_dst_usage	(	time_t	tick,
		const char *	tz
	)

Return if daylight-saving-time is in use in given time.

Parameters:

	tick	Time since Epoch
	tz	Time zone, all formats that glibc supports can be given. NULL to use current tz. See http://www.gnu.org/software/libtool/manual/libc/TZ-Variable.html

Returns:: Nonzero if daylight savings time is in effect, zero if not, -1 if error

double time_diff	(	time_t	t1,
		time_t	t2
	)

See difftime()

int time_get_time_diff	(	time_t	tick,
		const char *	tz1,
		const char *	tz2
	)

Get time difference between two timezones

Parameters:

	tick	Time since Epoch
	tz1	Timezone 1
	tz2	Timezone 2

Returns:: Local time in tz1 - local time in tz2

int time_set_autosync ( int enable )

Enable or disable automatic time settings based on cellular network time.

Parameters:

enable

Nonzero to enable, zero to disable

Returns:: 0 if OK, -1 if error

int time_get_autosync ( void )

Get the state of automatic time settings based on cellular network time.

Returns:: Nonzero if enabled, zero if disabled, -1 if error

int time_is_operator_time_accessible ( void )

Get info if the device supports network time updates (i.e. has CellMo).

Returns:: Nonzero if accessible, 0 if not, -1 if error


Defines
#define	CLOCKD_SERVICE "com.nokia.clockd"
#define	CLOCKD_PATH "/com/nokia/clockd"
#define	CLOCKD_INTERFACE "com.nokia.clockd"
#define	CLOCKD_TIME_CHANGED "time_changed"
Functions
int	time_get_synced (void)
time_t	time_get_time (void)
int	time_set_time (time_t tick)
int	time_get_net_time (time_t tick, char s, size_t max)
int	time_is_net_time_changed (time_t tick, char s, size_t max)
int	time_activate_net_time (void)
time_t	time_mktime (struct tm tm, const char tz)
int	time_get_timezone (char *s, size_t max)
int	time_get_tzname (char *s, size_t max)
int	time_set_timezone (const char *tz)
int	time_get_utc (struct tm *tm)
int	time_get_utc_ex (time_t tick, struct tm *tm)
int	time_get_local (struct tm *tm)
int	time_get_local_ex (time_t tick, struct tm *tm)
int	time_get_remote (time_t tick, const char tz, struct tm tm)
int	time_get_default_timezone (char *s, size_t max)
int	time_get_time_format (char *s, size_t max)
int	time_set_time_format (const char *fmt)
int	time_format_time (const struct tm tm, const char fmt, char *s, size_t max)
int	time_get_utc_offset (const char *tz)
int	time_get_dst_usage (time_t tick, const char *tz)
double	time_diff (time_t t1, time_t t2)
int	time_get_time_diff (time_t tick, const char tz1, const char tz2)
int	time_set_autosync (int enable)
int	time_get_autosync (void)
int	time_is_operator_time_accessible (void)