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_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_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

Copyright (C) 2008 Nokia. All rights reserved.


Define Documentation

#define CLOCKD_SERVICE   "com.nokia.clockd"

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

#define CLOCKD_PATH   "/com/nokia/clockd"

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

#define CLOCKD_INTERFACE   "com.nokia.clockd"

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

#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).


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:

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_is_net_time_changed ( time_t *  tick,
char *  s,
size_t  max 
)

Get the status of network time change (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.

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_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


Generated on Tue Feb 24 16:21:35 2009 for libtime/clockd by  doxygen 1.5.1