1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/**
* \file
*
* \brief Calendar.
*
* Copyright (c) 2011-2015 Atmel Corporation. All rights reserved.
*
* \asf_license_start
*
* \page License
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. The name of Atmel may not be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* 4. This software may only be redistributed and used in connection with an
* Atmel microcontroller product.
*
* THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
* EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* \asf_license_stop
*
*/
/*
* Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
*/
#ifndef _CALENDAR_H_INCLUDED_
#define _CALENDAR_H_INCLUDED_
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include <stdbool.h>
/**
*
* \defgroup calendar_group Calendar service
*
* See \ref calendar_quickstart.
*
* This is the common API for a calendar service.
* It provides functionality to convert UNIX timestamps to dates and back. It
* also provides functionality for calculating the difference between dates and
* converting timestamps to dates with different time zones and back.
* \note
* This module is a pure software module, and does not interface
* hardware calendar peripherals (e.g. the AST on UC3L)
*
* @{
*/
//! Calendar structure to hold a date
struct calendar_date {
uint8_t second; //!< 0-59
uint8_t minute; //!< 0-59
uint8_t hour; //!< 0-23
uint8_t date; //!< 0-30 \note First day of month is 0, not 1.
uint8_t month; //!< 0 January - 11 December
uint16_t year; //!< 1970-2105
uint8_t dayofweek; //!< 0 Sunday - 6 Saturday
};
bool calendar_is_date_valid(struct calendar_date *date);
void calendar_timestamp_to_date(uint32_t timestamp, struct calendar_date
*date_out);
void calendar_timestamp_to_date_tz(uint32_t timestamp, int8_t hour,
uint8_t min, struct calendar_date *date_out);
uint32_t calendar_date_to_timestamp(struct calendar_date *date);
uint32_t calendar_date_to_timestamp_tz(struct calendar_date *date, int8_t hour,
uint8_t min);
void calendar_time_between_dates(struct calendar_date *date_end,
struct calendar_date *date_start, struct calendar_date *date_out);
void calendar_add_second_to_date(struct calendar_date *date);
/** @} */
#ifdef __cplusplus
}
#endif
/**
* \page calendar_quickstart Quick start guide for Calendar service
*
* This is the quick start guide for the \ref calendar_group, with
* step-by-step instructions on how to configure and use the driver in a
* selection of use cases.
*
* The use cases contain several code fragments. The code fragments in the
* steps for setup can be copied into a custom initialization function, while
* the steps for usage can be copied into, e.g., the main application function.
*
* \section calendar_basic_use_case Basic use case
* \section calendar_use_cases Calendar use cases
* - \ref calendar_basic_use_case
* - \subpage calendar_use_case_1
*
* \section calendar_basic_use_case Basic use case - Calculate timestamp
*
* The use case will let the user calculate the corresponding timestamp to a
* date
*
* \section calendar_basic_use_case_setup Setup steps
*
* \subsection calendar_basic_use_case_setup_prereq Prerequisites
* For the code of this use case to work, the following must
* be added to the project:
* -# A date struct with a date:
* \code
struct calendar_date date = {
.second = 12,
.minute = 1,
.hour = 22,
.date = 8,
.month = 2,
.year = 1985
};
\endcode
*
* \subsection calendar_basic_use_case_setup_code Example code
* No setup code is needed, the service is ready for use as-is.
*
* \section calendar_basic_use_case_usage Usage steps
*
* \subsection calendar_basic_use_case_usage_code Example code
* Add to, e.g. the main loop in the application C-file:
* \code uint32_t timestamp = calendar_date_to_timestamp(&date); \endcode
*
* \subsection calendar_basic_use_case_usage_flow Workflow
* -# Convert date to timestamp:
* - \code uint32_t timestamp = calendar_date_to_timestamp(&date); \endcode
*/
/**
* \page calendar_use_case_1 Calculate time between dates
*
* The use case will let the user calculate the time between two dates, by
* first calculating the dates from two timestamps.
*
* \section calendar_use_case_1_setup Setup steps
*
* \subsection calendar_use_case_1_setup_prereq Prerequisites
* For the code of this use case to work, the following must
* be added to the project:
* -# Three date structs:
* \code
struct calendar_date result;
struct calendar_date end_date;
struct calendar_date start_date;
\endcode
* -# Two timestamps:
* \code
uint32_t end_timestamp = 1309174659;
uint32_t start_timestamp = 123456789;
\endcode
*
* \subsection calendar_use_case_1_setup_code Example code
* No setup code is needed, the service is ready for use as-is.
*
* \section calendar_use_case_1_usage Usage steps
*
* \subsection calendar_use_case_1_usage_code Example code
* Add to, e.g. the main loop in the application C-file:
* \code
calendar_timestamp_to_date(end_timestamp, &end_date);
calendar_timestamp_to_date(start_timestamp, &start_date);
calendar_time_between_dates(&end_date, &start_date, &result);
\endcode
*
* \subsection calendar_use_case_1_usage_flow Workflow
* -# Convert the end timestamp to date:
* - \code calendar_timestamp_to_date(end_timestamp, &end_date); \endcode
* -# Convert the start timestamp to date:
* - \code calendar_timestamp_to_date(start_timestamp, &start_date); \endcode
* -# Calculate the time between the two dates:
* - \code calendar_time_between_dates(&end_date, &start_date, &result);
\endcode
*/
#endif /* _CALENDAR_H_INCLUDED_ */
|
