libnx  v4.2.0
sm.h
Go to the documentation of this file.
1 /**
2  * @file sm.h
3  * @brief Service manager (sm) IPC wrapper.
4  * @author plutoo
5  * @author yellows8
6  * @copyright libnx Authors
7  */
8 #pragma once
9 #include "../types.h"
10 #include "../kernel/svc.h"
11 #include "../sf/service.h"
12 #include "../sf/tipc.h"
13 
14 /// Structure representing a service name (null terminated, remaining characters set to zero).
15 typedef struct SmServiceName {
16  char name[8];
18 
19 /// Converts a service name into a 64-bit integer.
21 {
22  u64 ret = 0;
23  __builtin_memcpy(&ret, &name, sizeof(u64));
24  return ret;
25 }
26 
27 /// Converts a 64-bit integer into a service name.
29 {
30  SmServiceName ret = {0};
31  __builtin_memcpy(&ret, &name, sizeof(SmServiceName));
32  return ret;
33 }
34 
35 /**
36  * @brief Checks whether two service names are equal.
37  * @param[in] a First name.
38  * @param[in] b Second name.
39  * @return Comparison result.
40  */
42 {
43  return smServiceNameToU64(a) == smServiceNameToU64(b);
44 }
45 
46 /**
47  * @brief Encodes a service name string as a \ref SmServiceName structure.
48  * @param[in] name Name of the service.
49  * @return Encoded name.
50  */
52 {
53  SmServiceName name_encoded = {};
54  unsigned len = __builtin_strlen(name);
55 #define __COPY_CHAR(_n) \
56  if (len > _n) name_encoded.name[_n] = name[_n]
57  __COPY_CHAR(0); __COPY_CHAR(1); __COPY_CHAR(2); __COPY_CHAR(3);
58  __COPY_CHAR(4); __COPY_CHAR(5); __COPY_CHAR(6); __COPY_CHAR(7);
59 #undef __COPY_CHAR
60  return name_encoded;
61 }
62 
63 /**
64  * @brief Initializes SM.
65  * @return Result code.
66  * @note This function is already called in the default application startup code (before main() is called).
67  */
68 Result smInitialize(void);
69 
70 /**
71  * @brief Uninitializes SM.
72  * @return Result code.
73  * @note This function is already handled in the default application exit code (after main() returns).
74  */
75 void smExit(void);
76 
77 /**
78  * @brief Requests a service from SM, allowing overrides.
79  * @param[out] service_out Service structure which will be filled in.
80  * @param[in] name Name of the service to request.
81  * @return Result code.
82  */
84 
85 /**
86  * @brief Requests a service from SM, as an IPC session handle directly
87  * @param[out] handle_out Variable containing IPC session handle.
88  * @param[in] name Name of the service to request.
89  * @return Result code.
90  */
92 
93 /**
94  * @brief Requests a service from SM.
95  * @param[out] service_out Service structure which will be filled in.
96  * @param[in] name Name of the service to request (as a string).
97  * @return Result code.
98  */
99 NX_INLINE Result smGetService(Service* service_out, const char* name)
100 {
101  return smGetServiceWrapper(service_out, smEncodeName(name));
102 }
103 
104 /**
105  * @brief Retrieves an overriden service in the homebrew environment.
106  * @param[in] name Name of the service to request.
107  * @return IPC session handle.
108  */
110 
111 /**
112  * @brief Creates and registers a new service within SM.
113  * @param[out] handle_out Variable containing IPC port handle.
114  * @param[in] name Name of the service.
115  * @param[in] is_light "Is light"
116  * @param[in] max_sessions Maximum number of concurrent sessions that the service will accept.
117  * @return Result code.
118  */
119 Result smRegisterService(Handle* handle_out, SmServiceName name, bool is_light, s32 max_sessions);
120 
121 /// Same as \ref smRegisterService, but always using cmif serialization.
122 Result smRegisterServiceCmif(Handle* handle_out, SmServiceName name, bool is_light, s32 max_sessions);
123 
124 /// Same as \ref smRegisterService, but always using tipc serialization.
125 Result smRegisterServiceTipc(Handle* handle_out, SmServiceName name, bool is_light, s32 max_sessions);
126 
127 /**
128  * @brief Unregisters a previously registered service in SM.
129  * @param[in] name Name of the service.
130  * @return Result code.
131  */
133 
134 /// Same as \ref smUnregisterService, but always using cmif serialization.
136 
137 /// Same as \ref smUnregisterService, but always using tipc serialization.
139 
140 /**
141  * @brief Detaches the current SM session.
142  * @note After this function is called, the rest of the SM API cannot be used.
143  * @note Only available on [11.0.0-11.0.1], or Atmosphère.
144  */
145 Result smDetachClient(void);
146 
147 /// Same as \ref smDetachClient, but always using cmif serialization.
149 
150 /// Same as \ref smDetachClient, but always using tipc serialization.
152 
153 /**
154  * @brief Gets the Service session used to communicate with SM.
155  * @return Pointer to service session used to communicate with SM.
156  */
158 
159 /**
160  * @brief Gets the TipcService session used to communicate with SM.
161  * @return Pointer to tipc service session used to communicate with SM.
162  * @note Only available on [12.0.0+], or Atmosphère.
163  */
165 
166 /**
167  * @brief Overrides a service with a custom IPC service handle.
168  * @param[in] name Name of the service.
169  * @param[in] handle IPC session handle.
170  */
171 void smAddOverrideHandle(SmServiceName name, Handle handle);
smEncodeName
static SmServiceName smEncodeName(const char *name)
Encodes a service name string as a SmServiceName structure.
Definition: sm.h:51
smGetServiceSessionTipc
TipcService * smGetServiceSessionTipc(void)
Gets the TipcService session used to communicate with SM.
smUnregisterServiceCmif
Result smUnregisterServiceCmif(SmServiceName name)
Same as smUnregisterService, but always using cmif serialization.
smServiceNameToU64
static u64 smServiceNameToU64(SmServiceName name)
Converts a service name into a 64-bit integer.
Definition: sm.h:20
NX_CONSTEXPR
#define NX_CONSTEXPR
Flags a function as constexpr in C++14 and above; or as (always) inline otherwise.
Definition: types.h:88
smGetServiceOriginal
Result smGetServiceOriginal(Handle *handle_out, SmServiceName name)
Requests a service from SM, as an IPC session handle directly.
smDetachClient
Result smDetachClient(void)
Detaches the current SM session.
smGetServiceWrapper
Result smGetServiceWrapper(Service *service_out, SmServiceName name)
Requests a service from SM, allowing overrides.
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
smServiceNamesAreEqual
static bool smServiceNamesAreEqual(SmServiceName a, SmServiceName b)
Checks whether two service names are equal.
Definition: sm.h:41
SmServiceName
Structure representing a service name (null terminated, remaining characters set to zero).
Definition: sm.h:15
smUnregisterServiceTipc
Result smUnregisterServiceTipc(SmServiceName name)
Same as smUnregisterService, but always using tipc serialization.
smServiceNameFromU64
static SmServiceName smServiceNameFromU64(u64 name)
Converts a 64-bit integer into a service name.
Definition: sm.h:28
smRegisterService
Result smRegisterService(Handle *handle_out, SmServiceName name, bool is_light, s32 max_sessions)
Creates and registers a new service within SM.
smInitialize
Result smInitialize(void)
Initializes SM.
smDetachClientTipc
Result smDetachClientTipc(void)
Same as smDetachClient, but always using tipc serialization.
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
Result
u32 Result
Function error code result type.
Definition: types.h:44
smGetServiceSession
Service * smGetServiceSession(void)
Gets the Service session used to communicate with SM.
smGetServiceOverride
Handle smGetServiceOverride(SmServiceName name)
Retrieves an overriden service in the homebrew environment.
TipcService
tipc Service object structure
Definition: tipc.h:18
smRegisterServiceCmif
Result smRegisterServiceCmif(Handle *handle_out, SmServiceName name, bool is_light, s32 max_sessions)
Same as smRegisterService, but always using cmif serialization.
smUnregisterService
Result smUnregisterService(SmServiceName name)
Unregisters a previously registered service in SM.
smDetachClientCmif
Result smDetachClientCmif(void)
Same as smDetachClient, but always using cmif serialization.
Service
Service object structure.
Definition: service.h:13
smGetService
static Result smGetService(Service *service_out, const char *name)
Requests a service from SM.
Definition: sm.h:99
smAddOverrideHandle
void smAddOverrideHandle(SmServiceName name, Handle handle)
Overrides a service with a custom IPC service handle.
smRegisterServiceTipc
Result smRegisterServiceTipc(Handle *handle_out, SmServiceName name, bool is_light, s32 max_sessions)
Same as smRegisterService, but always using tipc serialization.
NX_INLINE
#define NX_INLINE
Flags a function as (always) inline.
Definition: types.h:82
smExit
void smExit(void)
Uninitializes SM.
Handle
u32 Handle
Kernel object handle.
Definition: types.h:43