1+ #pragma once
2+
3+ #include < memory>
4+ #include < string>
5+ #include < vector>
6+
7+ namespace nativeapi {
8+
9+ /* *
10+ * @brief Manage application auto-start behavior on user login (cross-platform).
11+ *
12+ * AutoStart provides a unified API to enable or disable starting your application
13+ * automatically when the user logs in. The actual mechanism is platform-specific,
14+ * but this class abstracts away those differences.
15+ *
16+ * Platform implementations:
17+ * - Windows: HKCU\Software\Microsoft\Windows\CurrentVersion\Run registry key
18+ * - macOS: Launch Agents (~/Library/LaunchAgents/[app_id].plist) with ProgramArguments
19+ * - Linux (XDG): ~/.config/autostart/[app_id].desktop
20+ * - Android/iOS/OHOS: Not supported (returns false from IsSupported/operations)
21+ *
22+ * Notes:
23+ * - This API is intended for desktop environments. On mobile platforms this API is
24+ * typically unsupported by design. Methods will fail gracefully.
25+ * - You can let the implementation determine the current executable path, or call
26+ * SetProgram() to customize the target binary and arguments recorded in the OS.
27+ * - Some platforms may require application-specific permissions or entitlements
28+ * (e.g., sandbox restrictions on macOS). In such cases, operations may fail.
29+ *
30+ * Typical usage:
31+ * @code
32+ * using namespace nativeapi;
33+ *
34+ * if (AutoStart::IsSupported()) {
35+ * AutoStart autostart("com.example.myapp", "MyApp");
36+ * // Optionally override the program and arguments (defaults to current executable):
37+ * autostart.SetProgram("/usr/local/bin/myapp", {"--minimized"});
38+ *
39+ * autostart.Enable();
40+ * bool enabled = autostart.IsEnabled(); // should be true
41+ * }
42+ * @endcode
43+ */
44+ class AutoStart {
45+ public:
46+ /* *
47+ * @brief Check whether auto-start is supported on this platform.
48+ *
49+ * @return true if supported; false for unsupported platforms (e.g., mobile).
50+ */
51+ static bool IsSupported ();
52+
53+ /* *
54+ * @brief Construct an AutoStart manager with default identifier and display name.
55+ *
56+ * The default identifier and display name are implementation-defined. Typically,
57+ * the identifier is derived from the current process/bundle information, and the
58+ * display name is derived from the application or executable name.
59+ */
60+ AutoStart ();
61+
62+ /* *
63+ * @brief Construct an AutoStart manager with a custom identifier.
64+ *
65+ * @param id A stable, unique identifier for your app.
66+ * Examples:
67+ * - Windows: used as the registry value name, e.g., "MyApp"
68+ * - macOS: used as LaunchAgent Label, e.g., "com.example.myapp"
69+ * - Linux: used as the .desktop file name (without extension), e.g., "myapp"
70+ *
71+ * Recommendation: Use a reverse-DNS identifier when possible, e.g., "com.example.myapp".
72+ */
73+ explicit AutoStart (const std::string& id);
74+
75+ /* *
76+ * @brief Construct an AutoStart manager with a custom identifier and display name.
77+ *
78+ * @param id Stable, unique identifier (see above).
79+ * @param display_name Human-readable name shown in OS surfaces where applicable.
80+ */
81+ AutoStart (const std::string& id, const std::string& display_name);
82+
83+ virtual ~AutoStart ();
84+
85+ /* *
86+ * @brief Get the unique identifier associated with this AutoStart instance.
87+ *
88+ * @return The identifier string.
89+ */
90+ std::string GetId () const ;
91+
92+ /* *
93+ * @brief Get the human-readable display name used where applicable.
94+ *
95+ * @return The display name string.
96+ */
97+ std::string GetDisplayName () const ;
98+
99+ /* *
100+ * @brief Set a human-readable display name used where applicable.
101+ *
102+ * Some platforms surface a name in their UI (e.g., Linux .desktop Name, macOS LaunchAgent Label
103+ * often mirrors the identifier but may display the name in some tools).
104+ *
105+ * @param display_name The human-readable name.
106+ * @return true if the value was stored locally; does not change OS registration until Enable().
107+ */
108+ bool SetDisplayName (const std::string& display_name);
109+
110+ /* *
111+ * @brief Set the program (executable) path and optional arguments used for auto-start.
112+ *
113+ * If not set, implementations will try to use the current process executable path.
114+ * On platforms that require a single string (e.g., Windows registry), arguments will
115+ * be encoded appropriately (quoted when needed). On macOS/Linux, arguments are stored
116+ * as vector items (.plist ProgramArguments / .desktop Exec respectively).
117+ *
118+ * @param executable_path Absolute path to the executable to run on login.
119+ * @param arguments Optional arguments; order is preserved.
120+ * @return true if stored locally; does not change OS registration until Enable().
121+ */
122+ bool SetProgram (const std::string& executable_path,
123+ const std::vector<std::string>& arguments = {});
124+
125+ /* *
126+ * @brief Get the currently configured executable path used for auto-start.
127+ *
128+ * This returns the locally configured value (not necessarily what is stored in the OS).
129+ * If never set explicitly and cannot be resolved from the current process, it may be empty.
130+ *
131+ * @return Executable path string (may be empty).
132+ */
133+ std::string GetExecutablePath () const ;
134+
135+ /* *
136+ * @brief Get the currently configured arguments used for auto-start.
137+ *
138+ * This returns the locally configured value (not necessarily what is stored in the OS).
139+ *
140+ * @return Vector of arguments (may be empty).
141+ */
142+ std::vector<std::string> GetArguments () const ;
143+
144+ /* *
145+ * @brief Enable auto-start at user login for the configured program and arguments.
146+ *
147+ * If no program was explicitly set via SetProgram(), the implementation will attempt
148+ * to resolve the current executable path and use that as the program to start.
149+ *
150+ * @return true on success; false on error or when unsupported.
151+ */
152+ bool Enable ();
153+
154+ /* *
155+ * @brief Disable auto-start at user login.
156+ *
157+ * @return true on success; false on error or when unsupported.
158+ */
159+ bool Disable ();
160+
161+ /* *
162+ * @brief Query whether auto-start is currently enabled for this manager's identifier.
163+ *
164+ * This checks the platform-specific mechanism to determine whether the app (program path
165+ * and arguments currently configured) is registered to start at user login.
166+ *
167+ * @return true if currently enabled; false otherwise.
168+ */
169+ bool IsEnabled () const ;
170+
171+ // Prevent copying and moving
172+ AutoStart (const AutoStart&) = delete ;
173+ AutoStart& operator =(const AutoStart&) = delete ;
174+ AutoStart (AutoStart&&) = delete ;
175+ AutoStart& operator =(AutoStart&&) = delete ;
176+
177+ private:
178+ class Impl ;
179+ std::unique_ptr<Impl> pimpl_;
180+ };
181+
182+ } // namespace nativeapi
0 commit comments