calendar
Calendar 提供日历时间管理功能，支持通过日期时间结构体与时间戳进行时间的设置和获取。
头文件清单
接口清单
| 接口名称 | 功能简述 |
|---|---|
| uapi_calendar_init | 初始化Calendar模块，注册HAL回调函数并将时间戳设置为0 |
| uapi_calendar_deinit | 去初始化Calendar模块，重置时间戳并注销HAL回调函数 |
| uapi_calendar_set_datetime | 通过日期时间结构体设置日历基础时间 |
| uapi_calendar_get_datetime | 通过日期时间结构体获取日历当前时间 |
| uapi_calendar_set_timestamp | 设置日历时间戳 |
| uapi_calendar_get_timestamp | 获取当前日历时间戳 |
Functions
uapi_calendar_init
头文件清单
功能说明
- 初始化Calendar模块，注册HAL层回调函数
- 将时间戳设置为0
- 需在使用其他Calendar接口前最先调用
前置条件
- 调用时序约束：当前接口应在使用其他Calendar接口前最先调用
- 依赖关系：HAL层适配函数已实现并可供注册
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 初始化成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
uapi_calendar_deinit
头文件清单
功能说明
- 去初始化Calendar模块，注销HAL层回调函数
- 将时间戳重置为0
- 调用后Calendar模块不可使用，需重新初始化
前置条件
- 调用时序约束：Calendar模块已通过uapi_calendar_init()初始化完成
- 依赖关系：HAL层回调函数已注册且有效
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 去初始化成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
uapi_calendar_set_datetime
头文件清单
功能说明
- 通过calendar_t结构体设置日历日期时间
- 将日期时间转换为时间戳后调用HAL层设置接口
- 设置时会对日期时间进行合法性校验（年、月、日、时、分、秒范围）
前置条件
- 调用时序约束：Calendar模块已通过uapi_calendar_init()初始化完成
- 依赖关系：HAL层回调函数已注册且有效
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| date | const calendar_t * | 指向待设置的日历日期时间结构体 | 非NULL；year: 1970~2099；mon: 1~12；day: 1~当月最大天数；hour: 0~23；min: 0~59；sec: 0~59 |
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 日期时间设置成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
uapi_calendar_get_datetime
头文件清单
功能说明
- 通过calendar_t结构体获取当前日历日期时间
- 从HAL层获取时间戳后转换为日期时间
- 获取后会对日期时间进行合法性校验，不合法则重置为0并返回错误
前置条件
- 调用时序约束：Calendar模块已通过uapi_calendar_init()初始化完成
- 依赖关系：HAL层回调函数已注册且有效
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| date | calendar_t | 当前日历日期时间，校验失败时重置为0 |
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 日期时间获取成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
uapi_calendar_set_timestamp
头文件清单
功能说明
- 设置日历时间戳，时间戳单位为毫秒
- 设置前会对时间戳进行日期合法性校验
- 时间戳为0时触发内部初始化流程
前置条件
- 调用时序约束：Calendar模块已通过uapi_calendar_init()初始化完成
- 依赖关系：HAL层回调函数已注册且有效
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| timestamp | const uint64_t | 待设置的日历时间戳值，单位毫秒 | 转换为日期后year: 1970~2099；mon: 1~12；day: 1~当月最大天数；hour: 0~23；min: 0~59；sec: 0~59 |
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 时间戳设置成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
uapi_calendar_get_timestamp
头文件清单
功能说明
- 获取当前日历时间戳，时间戳单位为毫秒
- 获取后会对时间戳进行日期合法性校验，不合法则置0并返回错误
- HAL层函数未注册时直接返回失败
前置条件
- 调用时序约束：Calendar模块已通过uapi_calendar_init()初始化完成
- 依赖关系：HAL层回调函数已注册且有效
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| timestamp | uint64_t | 当前日历时间戳值，单位毫秒；校验失败时置0 |
返回值
- 返回类型：errcode_t
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| ERRCODE_SUCC(0x00) | 执行成功 | 时间戳获取成功 |
| Other | 其他错误码，参考errcode_t | 执行失败 |
Type definitions
errcode_t [SDK公共基础类型]
使用说明
作为本模块所有对外接口的返回值类型
Structures
calendar_t
typedef struct calendar {
uint32_t sec; /*!< 秒 0 ~ 59 */
uint32_t min; /*!< 分钟 0 ~ 59 */
uint32_t hour; /*!< 小时，0 ~ 23。 */
uint32_t day; /*!< 日，月的最大天数。 */
uint32_t mon; /*!< 月，1 ~ 12。 */
uint32_t year; /*!< 年，1970 ~ 2099。 */
} calendar_t;
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| sec | uint32_t | 秒，取值范围 0~59 |
| min | uint32_t | 分钟，取值范围 0~59 |
| hour | uint32_t | 小时，取值范围 0~23 |
| day | uint32_t | 日，取值范围 1~当月最大天数（受闰年影响） |
| mon | uint32_t | 月，取值范围 1~12 |
| year | uint32_t | 年，取值范围 1970~2099 |