libnx  v4.2.0
notif.h
Go to the documentation of this file.
1 /**
2  * @file notif.h
3  * @brief Alarm notification (notif:*) service IPC wrapper.
4  * @author yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../kernel/event.h"
10 #include "../services/applet.h"
11 #include "../services/acc.h"
12 #include "../sf/service.h"
13 
14 /// ServiceType for \ref notifInitialize.
15 typedef enum {
16  NotifServiceType_Application = 0, ///< Initializes notif:a, for Application.
17  NotifServiceType_System = 1, ///< Initializes notif:s, for System.
19 
20 /// Data extracted from NotifWeeklyScheduleAlarmSetting::settings. This uses local-time.
21 typedef struct {
22  s32 hour; ///< Hour.
23  s32 minute; ///< Minute.
25 
26 /// WeeklyScheduleAlarmSetting
27 typedef struct {
28  u8 unk_x0[0xa]; ///< Unknown.
29  s16 settings[7]; ///< Schedule settings for each day of the week, Sun-Sat. High byte is the hour, low byte is the minute. This uses local-time.
31 
32 /// AlarmSetting
33 typedef struct {
34  u16 alarm_setting_id; ///< AlarmSettingId
35  u8 kind; ///< Kind: 0 = WeeklySchedule.
36  u8 muted; ///< u8 bool flag for whether this AlarmSetting is muted (non-zero = AlarmSetting turned off, zero = on).
37  u8 pad[4]; ///< Padding.
38  AccountUid uid; ///< \ref AccountUid. User account associated with this AlarmSetting. Used for the preselected_user (\ref accountGetPreselectedUser) when launching the Application when the system was previously in sleep-mode, instead of launching the applet for selecting the user.
39  u64 application_id; ///< ApplicationId
40  u64 unk_x20; ///< Unknown.
41  NotifWeeklyScheduleAlarmSetting schedule; ///< \ref NotifWeeklyScheduleAlarmSetting
43 
44 /// Maximum alarms that can be registered at the same time by the host Application.
45 #define NOTIF_MAX_ALARMS 8
46 
47 /// Initialize notif. Only available on [9.0.0+].
49 
50 /// Exit notif.
51 void notifExit(void);
52 
53 /// Gets the Service object for the actual notif:* service session.
55 
56 /**
57  * @brief Creates a \ref NotifAlarmSetting.
58  * @note This clears the struct, with all schedule settings set the same as \ref notifAlarmSettingDisable.
59  * @param[out] alarm_setting \ref NotifAlarmSetting
60  */
61 void notifAlarmSettingCreate(NotifAlarmSetting *alarm_setting);
62 
63 /**
64  * @brief Sets whether the \ref NotifAlarmSetting is muted.
65  * @note By default (\ref notifAlarmSettingCreate) this is false.
66  * @param alarm_setting \ref NotifAlarmSetting
67  * @param[in] flag Whether the alarm is muted (true = Alarm turned off, false = on).
68  */
69 NX_INLINE void notifAlarmSettingSetIsMuted(NotifAlarmSetting *alarm_setting, bool flag) {
70  alarm_setting->muted = flag!=0;
71 }
72 
73 /**
74  * @brief Sets the \ref AccountUid for the \ref NotifAlarmSetting, see NotifAlarmSetting::uid.
75  * @param alarm_setting \ref NotifAlarmSetting
76  * @param[in] uid \ref AccountUid. If want to clear the uid after it was previously set, you can use an all-zero uid to reset to the default (\ref notifAlarmSettingCreate).
77  */
79  alarm_setting->uid = uid;
80 }
81 
82 /**
83  * @brief Gets whether the schedule setting for the specified day_of_week is enabled, for the \ref NotifAlarmSetting.
84  * @param alarm_setting \ref NotifAlarmSetting
85  * @param[in] day_of_week Day-of-week, must be 0-6 (Sun-Sat).
86  * @param[out] out Whether the setting is enabled.
87  */
88 Result notifAlarmSettingIsEnabled(NotifAlarmSetting *alarm_setting, u32 day_of_week, bool *out);
89 
90 /**
91  * @brief Gets the schedule setting for the specified day_of_week, for the \ref NotifAlarmSetting.
92  * @note Should not be used if the output from \ref notifAlarmSettingIsEnabled is false.
93  * @param alarm_setting \ref NotifAlarmSetting
94  * @param[in] day_of_week Day-of-week, must be 0-6 (Sun-Sat).
95  * @param[out] out \ref NotifAlarmTime
96  */
97 Result notifAlarmSettingGet(NotifAlarmSetting *alarm_setting, u32 day_of_week, NotifAlarmTime *out);
98 
99 /**
100  * @brief Enables the schedule setting for the specified day_of_week, for the \ref NotifAlarmSetting. This uses local-time.
101  * @param alarm_setting \ref NotifAlarmSetting
102  * @param[in] day_of_week Day-of-week, must be 0-6 (Sun-Sat).
103  * @param[in] hour Hour.
104  * @param[in] minute Minute.
105  */
106 Result notifAlarmSettingEnable(NotifAlarmSetting *alarm_setting, u32 day_of_week, s32 hour, s32 minute);
107 
108 /**
109  * @brief Disables the schedule setting for the specified day_of_week, for the \ref NotifAlarmSetting.
110  * @note Schedule settings are disabled by default (\ref notifAlarmSettingCreate).
111  * @param alarm_setting \ref NotifAlarmSetting
112  * @param[in] day_of_week Day-of-week, must be 0-6 (Sun-Sat).
113  */
114 Result notifAlarmSettingDisable(NotifAlarmSetting *alarm_setting, u32 day_of_week);
115 
116 /**
117  * @brief Registers the specified AlarmSetting.
118  * @note See \ref NOTIF_MAX_ALARMS for the maximum alarms.
119  * @note When indicated by the output from \ref hidIsFirmwareUpdateNeededForNotification, this will use \ref hidLaShowControllerFirmwareUpdate.
120  * @param[out] alarm_setting_id AlarmSettingId
121  * @param[in] alarm_setting \ref NotifAlarmSetting
122  * @param[in] buffer Input buffer containing the ApplicationParameter. Optional, can be NULL.
123  * @param[in] size Input buffer size, must be <=0x400. Optional, can be 0.
124  */
125 Result notifRegisterAlarmSetting(u16 *alarm_setting_id, const NotifAlarmSetting *alarm_setting, const void* buffer, size_t size);
126 
127 /**
128  * @brief Updates the specified AlarmSetting.
129  * @param[in] alarm_setting \ref NotifAlarmSetting
130  * @param[in] buffer Input buffer containing the ApplicationParameter. Optional, can be NULL.
131  * @param[in] size Input buffer size, must be <=0x400. Optional, can be 0.
132  */
133 Result notifUpdateAlarmSetting(const NotifAlarmSetting *alarm_setting, const void* buffer, size_t size);
134 
135 /**
136  * @brief Gets a listing of AlarmSettings.
137  * @param[out] alarm_settings Output \ref NotifAlarmSetting array.
138  * @param[in] count Total entries in the alarm_settings array.
139  * @param[out] total_out Total output entries.
140  */
141 Result notifListAlarmSettings(NotifAlarmSetting *alarm_settings, s32 count, s32 *total_out);
142 
143 /**
144  * @brief Loads the ApplicationParameter for the specified AlarmSetting.
145  * @param[in] alarm_setting_id AlarmSettingId
146  * @param[out] buffer Output buffer containing the ApplicationParameter.
147  * @param[in] size Output buffer size.
148  * @param[out] actual_size Actual output size.
149  */
150 Result notifLoadApplicationParameter(u16 alarm_setting_id, void* buffer, size_t size, u32 *actual_size);
151 
152 /**
153  * @brief Deletes the specified AlarmSetting.
154  * @param[in] alarm_setting_id AlarmSettingId
155  */
156 Result notifDeleteAlarmSetting(u16 alarm_setting_id);
157 
158 /**
159  * @brief Gets an Event which is signaled when data is available with \ref notifTryPopNotifiedApplicationParameter.
160  * @note This is a wrapper for \ref appletGetNotificationStorageChannelEvent, see that for the usage requirements.
161  * @note Some official apps don't use this.
162  * @note The Event must be closed by the user once finished with it.
163  * @param[out] out_event Output Event with autoclear=false.
164  */
167 }
168 
169 /**
170  * @brief Uses \ref appletTryPopFromNotificationStorageChannel then reads the data from there into the output params.
171  * @note This is a wrapper for \ref appletTryPopFromNotificationStorageChannel, see that for the usage requirements.
172  * @note The system will only push data for this when launching the Application when the Alarm was triggered, where the system was previously in sleep-mode.
173  * @note Some official apps don't use this.
174  * @param[out] buffer Output buffer.
175  * @param[out] size Output buffer size.
176  * @param[out] out_size Size of the data which was written into the output buffer. Optional, can be NULL.
177  */
178 Result notifTryPopNotifiedApplicationParameter(void* buffer, u64 size, u64 *out_size);
179 
notifLoadApplicationParameter
Result notifLoadApplicationParameter(u16 alarm_setting_id, void *buffer, size_t size, u32 *actual_size)
Loads the ApplicationParameter for the specified AlarmSetting.
NotifServiceType_Application
@ NotifServiceType_Application
Initializes notif:a, for Application.
Definition: notif.h:16
NotifAlarmTime
Data extracted from NotifWeeklyScheduleAlarmSetting::settings. This uses local-time.
Definition: notif.h:21
NotifAlarmSetting::alarm_setting_id
u16 alarm_setting_id
AlarmSettingId.
Definition: notif.h:34
notifUpdateAlarmSetting
Result notifUpdateAlarmSetting(const NotifAlarmSetting *alarm_setting, const void *buffer, size_t size)
Updates the specified AlarmSetting.
notifGetServiceSession
Service * notifGetServiceSession(void)
Gets the Service object for the actual notif:* service session.
NotifServiceType_System
@ NotifServiceType_System
Initializes notif:s, for System.
Definition: notif.h:17
notifAlarmSettingSetIsMuted
static void notifAlarmSettingSetIsMuted(NotifAlarmSetting *alarm_setting, bool flag)
Sets whether the NotifAlarmSetting is muted.
Definition: notif.h:69
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
s16
int16_t s16
16-bit signed integer.
Definition: types.h:26
Event
Kernel-mode event structure.
Definition: event.h:13
NotifAlarmSetting::application_id
u64 application_id
ApplicationId.
Definition: notif.h:39
AccountUid
Account UserId.
Definition: acc.h:25
notifAlarmSettingIsEnabled
Result notifAlarmSettingIsEnabled(NotifAlarmSetting *alarm_setting, u32 day_of_week, bool *out)
Gets whether the schedule setting for the specified day_of_week is enabled, for the NotifAlarmSetting...
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
NotifWeeklyScheduleAlarmSetting
WeeklyScheduleAlarmSetting.
Definition: notif.h:27
notifAlarmSettingDisable
Result notifAlarmSettingDisable(NotifAlarmSetting *alarm_setting, u32 day_of_week)
Disables the schedule setting for the specified day_of_week, for the NotifAlarmSetting.
NotifAlarmSetting::unk_x20
u64 unk_x20
Unknown.
Definition: notif.h:40
NotifAlarmTime::minute
s32 minute
Minute.
Definition: notif.h:23
notifAlarmSettingCreate
void notifAlarmSettingCreate(NotifAlarmSetting *alarm_setting)
Creates a NotifAlarmSetting.
NotifAlarmSetting::schedule
NotifWeeklyScheduleAlarmSetting schedule
NotifWeeklyScheduleAlarmSetting
Definition: notif.h:41
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
appletGetNotificationStorageChannelEvent
Result appletGetNotificationStorageChannelEvent(Event *out_event)
Gets an Event which is signaled when a new storage is available with appletTryPopFromNotificationStor...
notifDeleteAlarmSetting
Result notifDeleteAlarmSetting(u16 alarm_setting_id)
Deletes the specified AlarmSetting.
NotifServiceType
NotifServiceType
ServiceType for notifInitialize.
Definition: notif.h:15
notifAlarmSettingEnable
Result notifAlarmSettingEnable(NotifAlarmSetting *alarm_setting, u32 day_of_week, s32 hour, s32 minute)
Enables the schedule setting for the specified day_of_week, for the NotifAlarmSetting.
notifRegisterAlarmSetting
Result notifRegisterAlarmSetting(u16 *alarm_setting_id, const NotifAlarmSetting *alarm_setting, const void *buffer, size_t size)
Registers the specified AlarmSetting.
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
notifInitialize
Result notifInitialize(NotifServiceType service_type)
Initialize notif. Only available on [9.0.0+].
Result
u32 Result
Function error code result type.
Definition: types.h:44
notifGetNotificationSystemEvent
static Result notifGetNotificationSystemEvent(Event *out_event)
Gets an Event which is signaled when data is available with notifTryPopNotifiedApplicationParameter.
Definition: notif.h:165
NotifAlarmSetting::muted
u8 muted
u8 bool flag for whether this AlarmSetting is muted (non-zero = AlarmSetting turned off,...
Definition: notif.h:36
NotifAlarmSetting::uid
AccountUid uid
AccountUid. User account associated with this AlarmSetting. Used for the preselected_user (accountGet...
Definition: notif.h:38
NotifAlarmSetting
AlarmSetting.
Definition: notif.h:33
Service
Service object structure.
Definition: service.h:13
NotifAlarmTime::hour
s32 hour
Hour.
Definition: notif.h:22
notifListAlarmSettings
Result notifListAlarmSettings(NotifAlarmSetting *alarm_settings, s32 count, s32 *total_out)
Gets a listing of AlarmSettings.
notifTryPopNotifiedApplicationParameter
Result notifTryPopNotifiedApplicationParameter(void *buffer, u64 size, u64 *out_size)
Uses appletTryPopFromNotificationStorageChannel then reads the data from there into the output params...
notifAlarmSettingGet
Result notifAlarmSettingGet(NotifAlarmSetting *alarm_setting, u32 day_of_week, NotifAlarmTime *out)
Gets the schedule setting for the specified day_of_week, for the NotifAlarmSetting.
NX_INLINE
#define NX_INLINE
Flags a function as (always) inline.
Definition: types.h:82
NotifAlarmSetting::kind
u8 kind
Kind: 0 = WeeklySchedule.
Definition: notif.h:35
notifAlarmSettingSetUid
static void notifAlarmSettingSetUid(NotifAlarmSetting *alarm_setting, AccountUid uid)
Sets the AccountUid for the NotifAlarmSetting, see NotifAlarmSetting::uid.
Definition: notif.h:78
u16
uint16_t u16
16-bit unsigned integer.
Definition: types.h:20
notifExit
void notifExit(void)
Exit notif.