1#ifndef BASE_OS_H
2#define BASE_OS_H
3
4#include "detect.h"
5
6#include <cstddef>
7
8/**
9 * OS specific functionality.
10 *
11 * @defgroup OS OS
12 */
13
14/**
15 * Fixes the command line arguments to be encoded in UTF-8 on all systems.
16 *
17 * @ingroup OS
18 *
19 * @param argc A pointer to the argc parameter that was passed to the main function.
20 * @param argv A pointer to the argv parameter that was passed to the main function.
21 *
22 * @remark You need to call @link cmdline_free @endlink once you're no longer using the results.
23 */
24void cmdline_fix(int *argc, const char ***argv);
25
26/**
27 * Frees memory that was allocated by @link cmdline_fix @endlink.
28 *
29 * @ingroup OS
30 *
31 * @param argc The argc obtained from `cmdline_fix`.
32 * @param argv The argv obtained from `cmdline_fix`.
33 */
34void cmdline_free(int argc, const char **argv);
35
36/**
37 * Fixes the command line arguments to be encoded in UTF-8 on all systems.
38 * This is a RAII wrapper for @link cmdline_fix @endlink and @link cmdline_free @endlink.
39 *
40 * @ingroup OS
41 */
42class CCmdlineFix
43{
44 int m_Argc;
45 const char **m_ppArgv;
46
47public:
48 CCmdlineFix(int *pArgc, const char ***pppArgv)
49 {
50 cmdline_fix(argc: pArgc, argv: pppArgv);
51 m_Argc = *pArgc;
52 m_ppArgv = *pppArgv;
53 }
54 ~CCmdlineFix()
55 {
56 cmdline_free(argc: m_Argc, argv: m_ppArgv);
57 }
58 CCmdlineFix(const CCmdlineFix &) = delete;
59};
60
61#if !defined(CONF_PLATFORM_ANDROID)
62/**
63 * Opens a link in the browser.
64 *
65 * @ingroup OS
66 *
67 * @param link The link to open in a browser.
68 *
69 * @return `1` on success, `0` on failure.
70 *
71 * @remark The strings are treated as null-terminated strings.
72 * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
73 */
74int os_open_link(const char *link);
75
76/**
77 * Opens a file or directory with the default program.
78 *
79 * @ingroup OS
80 *
81 * @param path The file or folder to open with the default program.
82 *
83 * @return `1` on success, `0` on failure.
84 *
85 * @remark The strings are treated as null-terminated strings.
86 * @remark This may not be called with untrusted input or it'll result in arbitrary code execution, especially on Windows.
87 */
88int os_open_file(const char *path);
89#endif // !defined(CONF_PLATFORM_ANDROID)
90
91/**
92 * Returns a human-readable version string of the operating system.
93 *
94 * @ingroup OS
95 *
96 * @param version Buffer to use for the output.
97 * @param length Length of the output buffer.
98 *
99 * @return `true` on success, `false` on failure.
100 */
101bool os_version_str(char *version, size_t length);
102
103/**
104 * Returns a string of the preferred locale of the user / operating system.
105 * The string conforms to [RFC 3066](https://www.ietf.org/rfc/rfc3066.txt)
106 * and only contains the characters `a`-`z`, `A`-`Z`, `0`-`9` and `-`.
107 * If the preferred locale could not be determined this function
108 * falls back to the locale `"en-US"`.
109 *
110 * @ingroup OS
111 *
112 * @param locale Buffer to use for the output.
113 * @param length Length of the output buffer.
114 *
115 * @remark The strings are treated as null-terminated strings.
116 */
117void os_locale_str(char *locale, size_t length);
118
119#endif
120