Merge "chan_sip: Always process updated SDP on media source change"
[asterisk/asterisk.git] / include / asterisk / localtime.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2010, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  * Tilghman Lesher <tlesher AT digium DOT com>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19
20 /*! \file
21  * \brief Custom localtime functions for multiple timezones
22  */
23
24 #ifndef _ASTERISK_LOCALTIME_H
25 #define _ASTERISK_LOCALTIME_H
26
27 #ifdef HAVE_LOCALE_T_IN_LOCALE_H
28 #include <locale.h>
29 #elif defined(HAVE_LOCALE_T_IN_XLOCALE_H)
30 #include <xlocale.h>
31 #else
32 typedef void * locale_t;
33 #endif
34
35 struct ast_tm {
36         int tm_sec;             /*!< Seconds. [0-60] (1 leap second) */
37         int tm_min;             /*!< Minutes. [0-59] */
38         int tm_hour;            /*!< Hours.   [0-23] */
39         int tm_mday;            /*!< Day.     [1-31] */
40         int tm_mon;             /*!< Month.   [0-11] */
41         int tm_year;            /*!< Year - 1900.  */
42         int tm_wday;            /*!< Day of week. [0-6] */
43         int tm_yday;            /*!< Days in year.[0-365]       */
44         int tm_isdst;           /*!< DST.               [-1/0/1]*/
45         long int tm_gmtoff;     /*!< Seconds east of UTC.  */
46         char *tm_zone;          /*!< Timezone abbreviation.  */
47         /* NOTE: do NOT reorder this final item.  The order needs to remain compatible with struct tm */
48         int tm_usec;        /*!< microseconds */
49 };
50
51 /*!\brief Timezone-independent version of localtime_r(3).
52  * \param timep Current time, including microseconds
53  * \param p_tm Pointer to memory where the broken-out time will be stored
54  * \param zone Text string of a standard system zoneinfo file.  If NULL, the system localtime will be used.
55  * \retval p_tm is returned for convenience
56  */
57 struct ast_tm *ast_localtime(const struct timeval *timep, struct ast_tm *p_tm, const char *zone);
58
59 void ast_get_dst_info(const time_t * const timep, int *dst_enabled, time_t *dst_start, time_t *dst_end, int *gmt_off, const char * const zone);
60
61 /*!\brief Timezone-independent version of mktime(3).
62  * \param tmp Current broken-out time, including microseconds
63  * \param zone Text string of a standard system zoneinfo file.  If NULL, the system localtime will be used.
64  * \retval A structure containing both seconds and fractional thereof since January 1st, 1970 UTC
65  */
66 struct timeval ast_mktime(struct ast_tm * const tmp, const char *zone);
67
68 /*!\brief Set the thread-local representation of the current locale. */
69 const char *ast_setlocale(const char *locale);
70
71 /*!\brief Special version of strftime(3) that handles fractions of a second.
72  * Takes the same arguments as strftime(3), with the addition of %q, which
73  * specifies microseconds.
74  * \param buf Address in memory where the resulting string will be stored.
75  * \param len Size of the chunk of memory buf.
76  * \param format A string specifying the format of time to be placed into buf.
77  * \param tm Pointer to the broken out time to be used for the format.
78  * \retval An integer value specifying the number of bytes placed into buf or -1 on error.
79  */
80 int ast_strftime(char *buf, size_t len, const char *format, const struct ast_tm *tm);
81 int ast_strftime_locale(char *buf, size_t len, const char *format, const struct ast_tm *tm, const char *locale);
82
83 /*!\brief Special version of strptime(3) which places the answer in the common
84  * structure ast_tm.  Also, unlike strptime(3), ast_strptime() initializes its
85  * memory prior to use.
86  * \param s A string specifying some portion of a date and time.
87  * \param format The format in which the string, s, is expected.
88  * \param tm The broken-out time structure into which the parsed data is expected.
89  * \retval A pointer to the first character within s not used to parse the date and time.
90  */
91 char *ast_strptime(const char *s, const char *format, struct ast_tm *tm);
92 char *ast_strptime_locale(const char *s, const char *format, struct ast_tm *tm, const char *locale);
93
94 /*!\brief Wakeup localtime monitor thread
95  * For use in testing.  Normally, the failsafe monitor thread waits 60 seconds
96  * between checks to verify whether a timezone file has changed.  This routine
97  * forces the monitor thread to wakeup immediately and check the timezone files.
98  */
99 struct ast_test;
100 void ast_localtime_wakeup_monitor(struct ast_test *info);
101
102 /*! \brief ast_strftime for ISO8601 formatting timestamps. */
103 #define AST_ISO8601_FORMAT "%FT%T.%q%z"
104 /*! \brief Max length of an null terminated, millisecond resolution, ISO8601 timestamp string. */
105 #define AST_ISO8601_LEN 29
106
107 #endif /* _ASTERISK_LOCALTIME_H */