libnx  v4.2.0
hid_la.h
Go to the documentation of this file.
1 /**
2  * @file hid_la.h
3  * @brief Wrapper for using the controller LibraryApplet.
4  * @author yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../services/hid.h"
10 
11 /// Mode values for HidLaControllerSupportArgPrivate::mode.
12 typedef enum {
13  HidLaControllerSupportMode_ShowControllerSupport = 0, ///< ShowControllerSupport
14  HidLaControllerSupportMode_ShowControllerStrapGuide = 1, ///< [3.0.0+] ShowControllerStrapGuide
15  HidLaControllerSupportMode_ShowControllerFirmwareUpdate = 2, ///< [3.0.0+] ShowControllerFirmwareUpdate
16  HidLaControllerSupportMode_ShowControllerKeyRemappingForSystem = 4, ///< [11.0.0+] ShowControllerKeyRemappingForSystem
18 
19 /// ControllerSupportCaller
20 typedef enum {
21  HidLaControllerSupportCaller_Application = 0, ///< Application, this is the default.
22  HidLaControllerSupportCaller_System = 1, ///< System. Skips the firmware-update confirmation dialog. This has the same affect as using the controller-update option from qlaunch System Settings.
24 
25 /// ControllerSupportArgPrivate
26 typedef struct {
27  u32 private_size; ///< Size of this ControllerSupportArgPrivate struct.
28  u32 arg_size; ///< Size of the storage following this one (\ref HidLaControllerSupportArg or \ref HidLaControllerFirmwareUpdateArg).
29  u8 flag0; ///< Flag0
30  u8 flag1; ///< Flag1
31  u8 mode; ///< \ref HidLaControllerSupportMode
32  u8 controller_support_caller; ///< \ref HidLaControllerSupportCaller. Always zero except with \ref hidLaShowControllerFirmwareUpdateForSystem, which sets this to the input param.
33  u32 npad_style_set; ///< Output from \ref hidGetSupportedNpadStyleSet. With ShowControllerSupportForSystem on pre-3.0.0 this is value 0.
34  u32 npad_joy_hold_type; ///< Output from \ref hidGetNpadJoyHoldType. With ShowControllerSupportForSystem on pre-3.0.0 this is value 1.
36 
37 /// Common header used by HidLaControllerSupportArg*.
38 /// max_supported_players is 4 on pre-8.0.0, 8 on [8.0.0+]. player_count_min and player_count_max are overriden with value 4 when larger than value 4, during conversion handling for \ref HidLaControllerSupportArg on pre-8.0.0.
39 typedef struct {
40  s8 player_count_min; ///< playerCountMin. Must be >=0 and <=max_supported_players.
41  s8 player_count_max; ///< playerCountMax. Must be >=1 and <=max_supported_players.
42  u8 enable_take_over_connection; ///< enableTakeOverConnection, non-zero to enable. Disconnects the controllers when not enabled.
43  u8 enable_left_justify; ///< enableLeftJustify, non-zero to enable.
44  u8 enable_permit_joy_dual; ///< enablePermitJoyDual, non-zero to enable.
45  u8 enable_single_mode; ///< enableSingleMode, non-zero to enable. Enables using a single player in handheld-mode, dual-mode, or single-mode (player_count_* are overridden). Using handheld-mode is not allowed if this is not enabled.
46  u8 enable_identification_color; ///< When non-zero enables using identification_color.
48 
49 /// Identification color used by HidLaControllerSupportArg*. When HidLaControllerSupportArgHeader::enable_identification_color is set this controls the color of the UI player box outline.
50 typedef struct {
51  u8 r; ///< Red color component.
52  u8 g; ///< Green color component.
53  u8 b; ///< Blue color component.
54  u8 a; ///< Alpha color component.
56 
57 /// ControllerSupportArg for [1.0.0+].
58 typedef struct {
59  HidLaControllerSupportArgHeader hdr; ///< \ref HidLaControllerSupportArgHeader
60  HidLaControllerSupportArgColor identification_color[4]; ///< \ref HidLaControllerSupportArgColor for each player, see HidLaControllerSupportArgHeader::enable_identification_color.
61  u8 enable_explain_text; ///< Enables using the ExplainText data when non-zero.
62  char explain_text[4][0x81]; ///< ExplainText for each player, NUL-terminated UTF-8 strings.
64 
65 /// ControllerSupportArg for [8.0.0+], converted to \ref HidLaControllerSupportArgV3 on pre-8.0.0.
66 typedef struct {
67  HidLaControllerSupportArgHeader hdr; ///< \ref HidLaControllerSupportArgHeader
68  HidLaControllerSupportArgColor identification_color[8]; ///< \ref HidLaControllerSupportArgColor for each player, see HidLaControllerSupportArgHeader::enable_identification_color.
69  u8 enable_explain_text; ///< Enables using the ExplainText data when non-zero.
70  char explain_text[8][0x81]; ///< ExplainText for each player, NUL-terminated UTF-8 strings.
72 
73 /// ControllerFirmwareUpdateArg
74 typedef struct {
75  u8 enable_force_update; ///< enableForceUpdate, non-zero to enable. Default is 0. Forces a firmware update when enabled, without an UI option to skip it.
76  u8 pad[3]; ///< Padding.
78 
79 /// ControllerKeyRemappingArg
80 typedef struct {
81  u64 unk_x0; ///< Unknown
82  u32 unk_x8; ///< Unknown
83  u8 pad[0x4]; ///< Padding
85 
86 /// ControllerSupportResultInfo. First 8-bytes from the applet output storage.
87 typedef struct {
88  s8 player_count; ///< playerCount.
89  u8 pad[3]; ///< Padding.
90  u32 selected_id; ///< \ref HidNpadIdType, selectedId.
92 
93 /// Struct for the applet output storage.
94 typedef struct {
95  HidLaControllerSupportResultInfo info; ///< \ref HidLaControllerSupportResultInfo
96  u32 res; ///< Output res value.
98 
99 /**
100  * @brief Initializes a \ref HidLaControllerSupportArg with the defaults.
101  * @note This clears the arg, then does: HidLaControllerSupportArgHeader::player_count_min = 0, HidLaControllerSupportArgHeader::player_count_max = 4, HidLaControllerSupportArgHeader::enable_take_over_connection = 1, HidLaControllerSupportArgHeader::enable_left_justify = 1, and HidLaControllerSupportArgHeader::enable_permit_joy_dual = 1.
102  * @note If preferred, you can also memset \ref HidLaControllerSupportArg manually and initialize it yourself.
103  * @param[out] arg \ref HidLaControllerSupportArg
104  */
106 
107 /**
108  * @brief Initializes a \ref HidLaControllerFirmwareUpdateArg with the defaults.
109  * @note This just uses memset() with the arg.
110  * @param[out] arg \ref HidLaControllerFirmwareUpdateArg
111  */
113 
114 /**
115  * @brief Initializes a \ref HidLaControllerKeyRemappingArg with the defaults.
116  * @note This just uses memset() with the arg.
117  * @param[out] arg \ref HidLaControllerKeyRemappingArg
118  */
120 
121 /**
122  * @brief Sets the ExplainText for the specified player and \ref HidLaControllerSupportArg.
123  * @note This string is displayed in the UI box for the player.
124  * @note HidLaControllerSupportArg::enable_explain_text must be set, otherwise this ExplainText is ignored.
125  * @param arg \ref HidLaControllerSupportArg
126  * @param[in] str Input ExplainText UTF-8 string, max length is 0x80 excluding NUL-terminator.
127  + @oaram[in] id Player controller, must be <8.
128  */
130 
131 /**
132  * @brief Launches the applet for ControllerSupport.
133  * @note This seems to only display the applet UI when doing so is actually needed? This doesn't apply to \ref hidLaShowControllerSupportForSystem.
134  * @param[out] result_info \ref HidLaControllerSupportResultInfo. Optional, can be NULL.
135  * @param[in] arg \ref HidLaControllerSupportArg
136  */
138 
139 /**
140  * @brief Launches the applet for ControllerStrapGuide.
141  * @note Only available on [3.0.0+].
142  */
144 
145 /**
146  * @brief Launches the applet for ControllerFirmwareUpdate.
147  * @note Only available on [3.0.0+].
148  * @param[in] arg \ref HidLaControllerFirmwareUpdateArg
149  */
151 
152 /**
153  * @brief This is the system version of \ref hidLaShowControllerSupport.
154  * @param[out] result_info \ref HidLaControllerSupportResultInfo. Optional, can be NULL.
155  * @param[in] arg \ref HidLaControllerSupportArg
156  * @param[in] flag Input flag. When true, the applet displays the menu as if launched by qlaunch.
157  */
159 
160 /**
161  * @brief This is the system version of \ref hidLaShowControllerFirmwareUpdate.
162  * @note Only available on [3.0.0+].
163  * @param[in] arg \ref HidLaControllerFirmwareUpdateArg
164  * @param[in] caller \ref HidLaControllerSupportCaller
165  */
167 
168 /**
169  * @brief Launches the applet for ControllerKeyRemappingForSystem.
170  * @note Only available on [11.0.0+].
171  * @param[in] arg \ref HidLaControllerKeyRemappingArg
172  * @param[in] caller \ref HidLaControllerSupportCaller
173  */
175 
HidLaControllerSupportArgPrivate::private_size
u32 private_size
Size of this ControllerSupportArgPrivate struct.
Definition: hid_la.h:27
hidLaCreateControllerKeyRemappingArg
void hidLaCreateControllerKeyRemappingArg(HidLaControllerKeyRemappingArg *arg)
Initializes a HidLaControllerKeyRemappingArg with the defaults.
HidLaControllerSupportResultInfoInternal
Struct for the applet output storage.
Definition: hid_la.h:94
HidLaControllerSupportArgPrivate::flag0
u8 flag0
Flag0.
Definition: hid_la.h:29
HidLaControllerSupportArgColor::b
u8 b
Blue color component.
Definition: hid_la.h:53
hidLaShowControllerStrapGuide
Result hidLaShowControllerStrapGuide(void)
Launches the applet for ControllerStrapGuide.
hidLaShowControllerFirmwareUpdateForSystem
Result hidLaShowControllerFirmwareUpdateForSystem(const HidLaControllerFirmwareUpdateArg *arg, HidLaControllerSupportCaller caller)
This is the system version of hidLaShowControllerFirmwareUpdate.
HidLaControllerSupportResultInfo::player_count
s8 player_count
playerCount.
Definition: hid_la.h:88
HidLaControllerSupportArgHeader::player_count_max
s8 player_count_max
playerCountMax. Must be >=1 and <=max_supported_players.
Definition: hid_la.h:41
HidLaControllerSupportArgV3::hdr
HidLaControllerSupportArgHeader hdr
HidLaControllerSupportArgHeader
Definition: hid_la.h:59
HidLaControllerSupportArgPrivate
ControllerSupportArgPrivate.
Definition: hid_la.h:26
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
HidLaControllerSupportResultInfo
ControllerSupportResultInfo. First 8-bytes from the applet output storage.
Definition: hid_la.h:87
HidLaControllerKeyRemappingArg
ControllerKeyRemappingArg.
Definition: hid_la.h:80
HidLaControllerSupportArgV3
ControllerSupportArg for [1.0.0+].
Definition: hid_la.h:58
hidLaShowControllerSupport
Result hidLaShowControllerSupport(HidLaControllerSupportResultInfo *result_info, const HidLaControllerSupportArg *arg)
Launches the applet for ControllerSupport.
HidLaControllerSupportResultInfoInternal::info
HidLaControllerSupportResultInfo info
HidLaControllerSupportResultInfo
Definition: hid_la.h:95
HidLaControllerSupportResultInfo::selected_id
u32 selected_id
HidNpadIdType, selectedId.
Definition: hid_la.h:90
HidLaControllerSupportArgColor::g
u8 g
Green color component.
Definition: hid_la.h:52
HidLaControllerSupportMode_ShowControllerStrapGuide
@ HidLaControllerSupportMode_ShowControllerStrapGuide
[3.0.0+] ShowControllerStrapGuide
Definition: hid_la.h:14
HidLaControllerSupportArgColor::r
u8 r
Red color component.
Definition: hid_la.h:51
HidLaControllerSupportMode_ShowControllerKeyRemappingForSystem
@ HidLaControllerSupportMode_ShowControllerKeyRemappingForSystem
[11.0.0+] ShowControllerKeyRemappingForSystem
Definition: hid_la.h:16
HidLaControllerSupportCaller_Application
@ HidLaControllerSupportCaller_Application
Application, this is the default.
Definition: hid_la.h:21
HidLaControllerSupportArgHeader::enable_left_justify
u8 enable_left_justify
enableLeftJustify, non-zero to enable.
Definition: hid_la.h:43
HidNpadIdType
HidNpadIdType
HID controller IDs.
Definition: hid.h:214
HidLaControllerSupportArgPrivate::npad_joy_hold_type
u32 npad_joy_hold_type
Output from hidGetNpadJoyHoldType. With ShowControllerSupportForSystem on pre-3.0....
Definition: hid_la.h:34
HidLaControllerSupportMode
HidLaControllerSupportMode
Mode values for HidLaControllerSupportArgPrivate::mode.
Definition: hid_la.h:12
HidLaControllerSupportArgHeader::player_count_min
s8 player_count_min
playerCountMin. Must be >=0 and <=max_supported_players.
Definition: hid_la.h:40
HidLaControllerSupportArg::enable_explain_text
u8 enable_explain_text
Enables using the ExplainText data when non-zero.
Definition: hid_la.h:69
hidLaShowControllerSupportForSystem
Result hidLaShowControllerSupportForSystem(HidLaControllerSupportResultInfo *result_info, const HidLaControllerSupportArg *arg, bool flag)
This is the system version of hidLaShowControllerSupport.
HidLaControllerFirmwareUpdateArg
ControllerFirmwareUpdateArg.
Definition: hid_la.h:74
HidLaControllerKeyRemappingArg::unk_x0
u64 unk_x0
Unknown.
Definition: hid_la.h:81
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
HidLaControllerSupportArgPrivate::controller_support_caller
u8 controller_support_caller
HidLaControllerSupportCaller. Always zero except with hidLaShowControllerFirmwareUpdateForSystem,...
Definition: hid_la.h:32
HidLaControllerSupportResultInfoInternal::res
u32 res
Output res value.
Definition: hid_la.h:96
HidLaControllerSupportArgHeader
Common header used by HidLaControllerSupportArg*.
Definition: hid_la.h:39
s8
int8_t s8
8-bit signed integer.
Definition: types.h:25
hidLaShowControllerFirmwareUpdate
Result hidLaShowControllerFirmwareUpdate(const HidLaControllerFirmwareUpdateArg *arg)
Launches the applet for ControllerFirmwareUpdate.
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
HidLaControllerSupportCaller
HidLaControllerSupportCaller
ControllerSupportCaller.
Definition: hid_la.h:20
HidLaControllerSupportArgColor::a
u8 a
Alpha color component.
Definition: hid_la.h:54
hidLaCreateControllerFirmwareUpdateArg
void hidLaCreateControllerFirmwareUpdateArg(HidLaControllerFirmwareUpdateArg *arg)
Initializes a HidLaControllerFirmwareUpdateArg with the defaults.
HidLaControllerSupportArgHeader::enable_identification_color
u8 enable_identification_color
When non-zero enables using identification_color.
Definition: hid_la.h:46
HidLaControllerSupportMode_ShowControllerFirmwareUpdate
@ HidLaControllerSupportMode_ShowControllerFirmwareUpdate
[3.0.0+] ShowControllerFirmwareUpdate
Definition: hid_la.h:15
Result
u32 Result
Function error code result type.
Definition: types.h:44
HidLaControllerSupportArgPrivate::npad_style_set
u32 npad_style_set
Output from hidGetSupportedNpadStyleSet. With ShowControllerSupportForSystem on pre-3....
Definition: hid_la.h:33
HidLaControllerSupportArgPrivate::mode
u8 mode
HidLaControllerSupportMode
Definition: hid_la.h:31
hidLaSetExplainText
Result hidLaSetExplainText(HidLaControllerSupportArg *arg, const char *str, HidNpadIdType id)
Sets the ExplainText for the specified player and HidLaControllerSupportArg.
HidLaControllerFirmwareUpdateArg::enable_force_update
u8 enable_force_update
enableForceUpdate, non-zero to enable. Default is 0. Forces a firmware update when enabled,...
Definition: hid_la.h:75
HidLaControllerSupportArgPrivate::flag1
u8 flag1
Flag1.
Definition: hid_la.h:30
HidLaControllerSupportArgV3::enable_explain_text
u8 enable_explain_text
Enables using the ExplainText data when non-zero.
Definition: hid_la.h:61
hidLaShowControllerKeyRemappingForSystem
Result hidLaShowControllerKeyRemappingForSystem(const HidLaControllerKeyRemappingArg *arg, HidLaControllerSupportCaller caller)
Launches the applet for ControllerKeyRemappingForSystem.
HidLaControllerSupportArg::hdr
HidLaControllerSupportArgHeader hdr
HidLaControllerSupportArgHeader
Definition: hid_la.h:67
HidLaControllerSupportArgHeader::enable_permit_joy_dual
u8 enable_permit_joy_dual
enablePermitJoyDual, non-zero to enable.
Definition: hid_la.h:44
HidLaControllerSupportArgHeader::enable_single_mode
u8 enable_single_mode
enableSingleMode, non-zero to enable. Enables using a single player in handheld-mode,...
Definition: hid_la.h:45
HidLaControllerSupportArgColor
Identification color used by HidLaControllerSupportArg*. When HidLaControllerSupportArgHeader::enable...
Definition: hid_la.h:50
HidLaControllerSupportCaller_System
@ HidLaControllerSupportCaller_System
System. Skips the firmware-update confirmation dialog. This has the same affect as using the controll...
Definition: hid_la.h:22
HidLaControllerSupportArgPrivate::arg_size
u32 arg_size
Size of the storage following this one (HidLaControllerSupportArg or HidLaControllerFirmwareUpdateArg...
Definition: hid_la.h:28
HidLaControllerSupportArg
ControllerSupportArg for [8.0.0+], converted to HidLaControllerSupportArgV3 on pre-8....
Definition: hid_la.h:66
hidLaCreateControllerSupportArg
void hidLaCreateControllerSupportArg(HidLaControllerSupportArg *arg)
Initializes a HidLaControllerSupportArg with the defaults.
HidLaControllerKeyRemappingArg::unk_x8
u32 unk_x8
Unknown.
Definition: hid_la.h:82
HidLaControllerSupportMode_ShowControllerSupport
@ HidLaControllerSupportMode_ShowControllerSupport
ShowControllerSupport.
Definition: hid_la.h:13
HidLaControllerSupportArgHeader::enable_take_over_connection
u8 enable_take_over_connection
enableTakeOverConnection, non-zero to enable. Disconnects the controllers when not enabled.
Definition: hid_la.h:42