libnx  v4.2.2
libapplet.h
Go to the documentation of this file.
1 /**
2  * @file libapplet.h
3  * @brief LibraryApplet wrapper.
4  * @author yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../services/applet.h"
10 #include "../services/acc.h"
11 
12 /// CommonArguments
13 typedef struct {
14  u32 CommonArgs_version; ///< \ref libappletArgsCreate sets this to 1, and \ref libappletArgsPop requires value 1. v0 is not supported.
15  u32 CommonArgs_size; ///< Size of this struct.
16 
17  u32 LaVersion; ///< LibraryApplet API version.
18  s32 ExpectedThemeColor; ///< Set to the output from \ref appletGetThemeColorType by \ref libappletArgsCreate.
19  u8 PlayStartupSound; ///< bool flag, default is false.
20  u8 pad[7]; ///< Padding.
21  u64 tick; ///< System tick. Set to the output from \ref armGetSystemTick during \ref libappletArgsPush.
23 
24 /**
25  * @brief Creates a LibAppletArgs struct.
26  * @param a LibAppletArgs struct.
27  * @param version LaVersion for \ref LibAppletArgs.
28  */
29 void libappletArgsCreate(LibAppletArgs* a, u32 version);
30 
31 /**
32  * @brief Sets the PlayStartupSound field in \ref LibAppletArgs.
33  * @param a LibAppletArgs struct.
34  * @param flag Value for \ref LibAppletArgs PlayStartupSound.
35  */
37 
38 /**
39  * @brief Creates an AppletStorage with the specified size and writes the buffer contents to that storage at offset 0.
40  * @param[out] s Storage object.
41  * @param buffer Input buffer.
42  * @param size Size to write.
43  */
44 Result libappletCreateWriteStorage(AppletStorage* s, const void* buffer, size_t size);
45 
46 /**
47  * @brief Reads data from offset 0 from the specified storage into the buffer. If the storage-size is smaller than the size param, the storage-size is used instead.
48  * @param s Storage object.
49  * @param buffer Output buffer.
50  * @param size Size to read.
51  * @param transfer_size Optional output size field for the actual size used for the read, can be NULL.
52  */
53 Result libappletReadStorage(AppletStorage* s, void* buffer, size_t size, size_t *transfer_size);
54 
55 /**
56  * @brief Sets the tick field in LibAppletArgs, then creates a storage with it which is pushed to the AppletHolder via \ref appletHolderPushInData.
57  * @param a LibAppletArgs struct.
58  * @param h AppletHolder object.
59  */
61 
62 /**
63  * @brief Uses \ref appletPopInData and reads it to the specified LibAppletArgs. The LibAppletArgs is validated, an error is thrown when invalid.
64  * @param[out] a LibAppletArgs struct.
65  */
67 
68 /**
69  * @brief Creates a storage using the input buffer which is pushed to the AppletHolder via \ref appletHolderPushInData.
70  * @param h AppletHolder object.
71  * @param buffer Input data buffer.
72  * @param size Input data size.
73  */
74 Result libappletPushInData(AppletHolder *h, const void* buffer, size_t size);
75 
76 /**
77  * @brief Pops a storage via \ref appletHolderPopOutData, uses \ref libappletReadStorage, then closes the storage.
78  * @param h AppletHolder object.
79  * @param buffer Output buffer.
80  * @param size Size to read.
81  * @param transfer_size Optional output size field for the actual size used for the read, can be NULL.
82  */
83 Result libappletPopOutData(AppletHolder *h, void* buffer, size_t size, size_t *transfer_size);
84 
85 /**
86  * @brief Sets whether \ref libappletStart uses \ref appletHolderJump.
87  * @param flag Flag. Value true should not be used unless running as AppletType_LibraryApplet.
88  */
89 void libappletSetJumpFlag(bool flag);
90 
91 /**
92  * @brief If the flag from \ref libappletSetJumpFlag is set, this just uses \ref appletHolderJump. Otherwise, starts the applet and waits for it to finish, then checks the \ref LibAppletExitReason.
93  * @note Uses \ref appletHolderStart and \ref appletHolderJoin.
94  * @param h AppletHolder object.
95  */
97 
98 /**
99  * @brief Creates a LibraryApplet with the specified input storage data, uses \ref libappletStart, and reads the output storage reply data via \ref libappletPopOutData.
100  * @param id \ref AppletId
101  * @param commonargs \ref LibAppletArgs struct.
102  * @param arg Input storage data buffer. Optional, can be NULL.
103  * @param arg_size Size of the arg buffer.
104  * @param reply Output storage data buffer. Optional, can be NULL.
105  * @param reply_size Size to read for the reply buffer.
106  * @param out_reply_size Actual read reply data size, see \ref libappletPopOutData.
107  */
108 Result libappletLaunch(AppletId id, LibAppletArgs *commonargs, const void* arg, size_t arg_size, void* reply, size_t reply_size, size_t *out_reply_size);
109 
110 /// Wrapper for \ref appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for using this.
111 /// Returns to the main Home Menu, equivalent to pressing the HOME button.
113 
114 /// Wrapper for \ref appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for using this.
115 /// Equivalent to entering "System Update" under System Settings. When leaving this, it returns to the main Home Menu.
117 
118 /**
119  * @brief Wrapper for \ref appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for using this.
120  * @note Only available on [11.0.0+].
121  * @param[in] application_id ApplicationId
122  * @param[in] uid \ref AccountUid
123  * @param[in] buffer Input buffer.
124  * @param[in] size Input buffer size.
125  * @param[in] sender LaunchApplicationRequestSender
126  */
127 Result libappletRequestToLaunchApplication(u64 application_id, AccountUid uid, const void* buffer, size_t size, u32 sender);
128 
129 /**
130  * @brief Wrapper for \ref appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for using this.
131  * @note Only available on [11.0.0+].
132  * @param[in] uid \ref AccountUid
133  * @param[in] application_id Optional ApplicationId, can be 0.
134  */
135 Result libappletRequestJumpToStory(AccountUid uid, u64 application_id);
136 
LibAppletArgs::PlayStartupSound
u8 PlayStartupSound
bool flag, default is false.
Definition: libapplet.h:19
libappletPushInData
Result libappletPushInData(AppletHolder *h, const void *buffer, size_t size)
Creates a storage using the input buffer which is pushed to the AppletHolder via appletHolderPushInDa...
LibAppletArgs::CommonArgs_size
u32 CommonArgs_size
Size of this struct.
Definition: libapplet.h:15
LibAppletArgs::CommonArgs_version
u32 CommonArgs_version
libappletArgsCreate sets this to 1, and libappletArgsPop requires value 1. v0 is not supported.
Definition: libapplet.h:14
LibAppletArgs
CommonArguments.
Definition: libapplet.h:13
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
libappletRequestHomeMenu
Result libappletRequestHomeMenu(void)
Wrapper for appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for...
LibAppletArgs::tick
u64 tick
System tick. Set to the output from armGetSystemTick during libappletArgsPush.
Definition: libapplet.h:21
AppletHolder
LibraryApplet state.
Definition: applet.h:241
AccountUid
Account UserId.
Definition: acc.h:25
libappletRequestJumpToStory
Result libappletRequestJumpToStory(AccountUid uid, u64 application_id)
Wrapper for appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for...
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
LibAppletArgs::LaVersion
u32 LaVersion
LibraryApplet API version.
Definition: libapplet.h:17
libappletLaunch
Result libappletLaunch(AppletId id, LibAppletArgs *commonargs, const void *arg, size_t arg_size, void *reply, size_t reply_size, size_t *out_reply_size)
Creates a LibraryApplet with the specified input storage data, uses libappletStart,...
libappletPopOutData
Result libappletPopOutData(AppletHolder *h, void *buffer, size_t size, size_t *transfer_size)
Pops a storage via appletHolderPopOutData, uses libappletReadStorage, then closes the storage.
LibAppletArgs::ExpectedThemeColor
s32 ExpectedThemeColor
Set to the output from appletGetThemeColorType by libappletArgsCreate.
Definition: libapplet.h:18
libappletStart
Result libappletStart(AppletHolder *h)
If the flag from libappletSetJumpFlag is set, this just uses appletHolderJump.
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
libappletCreateWriteStorage
Result libappletCreateWriteStorage(AppletStorage *s, const void *buffer, size_t size)
Creates an AppletStorage with the specified size and writes the buffer contents to that storage at of...
libappletSetJumpFlag
void libappletSetJumpFlag(bool flag)
Sets whether libappletStart uses appletHolderJump.
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
Result
u32 Result
Function error code result type.
Definition: types.h:44
libappletRequestJumpToSystemUpdate
Result libappletRequestJumpToSystemUpdate(void)
Wrapper for appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for...
libappletArgsCreate
void libappletArgsCreate(LibAppletArgs *a, u32 version)
Creates a LibAppletArgs struct.
AppletStorage
applet IStorage
Definition: applet.h:235
libappletRequestToLaunchApplication
Result libappletRequestToLaunchApplication(u64 application_id, AccountUid uid, const void *buffer, size_t size, u32 sender)
Wrapper for appletPushToGeneralChannel, see appletPushToGeneralChannel regarding the requirements for...
libappletArgsPop
Result libappletArgsPop(LibAppletArgs *a)
Uses appletPopInData and reads it to the specified LibAppletArgs.
libappletArgsSetPlayStartupSound
void libappletArgsSetPlayStartupSound(LibAppletArgs *a, bool flag)
Sets the PlayStartupSound field in LibAppletArgs.
libappletReadStorage
Result libappletReadStorage(AppletStorage *s, void *buffer, size_t size, size_t *transfer_size)
Reads data from offset 0 from the specified storage into the buffer.
libappletArgsPush
Result libappletArgsPush(LibAppletArgs *a, AppletHolder *h)
Sets the tick field in LibAppletArgs, then creates a storage with it which is pushed to the AppletHol...
AppletId
AppletId
AppletId.
Definition: applet.h:91