Add: API definition of our upcoming social integration API

README.md

@@ -198,7 +198,10 @@ The icu scriptrun implementation in `src/3rdparty/icu` is licensed under the Uni
 See `src/3rdparty/icu/LICENSE` for the complete license text.
 
 The monocypher implementation in `src/3rdparty/monocypher` is licensed under the 2-clause BSD and CC-0 license.
-See src/3rdparty/monocypher/LICENSE.md` for the complete license text.
+See `src/3rdparty/monocypher/LICENSE.md` for the complete license text.
+
+The OpenTTD Social Integration API in `src/3rdparty/openttd_social_integration_api` is licensed under the MIT license.
+See `src/3rdparty/openttd_social_integration_api/LICENSE` for the complete license text.
 
 ## 4.0 Credits
 

src/3rdparty/CMakeLists.txt

@@ -6,3 +6,4 @@ add_subdirectory(monocypher)
 add_subdirectory(squirrel)
 add_subdirectory(nlohmann)
 add_subdirectory(opengl)
+add_subdirectory(openttd_social_integration_api)

src/3rdparty/openttd_social_integration_api/CMakeLists.txt

@@ -0,0 +1,4 @@
+add_files(
+    openttd_social_integration_api.h
+    openttd_social_integration_api_v1.h
+)

src/3rdparty/openttd_social_integration_api/LICENSE

@@ -0,0 +1,20 @@
+ Copyright 2024 OpenTTD project
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files
+ (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge,
+ publish, distribute, sublicense, and/or sell copies of the Software,
+ and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+ OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.

src/3rdparty/openttd_social_integration_api/openttd_social_integration_api.h

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2024 OpenTTD project
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+ * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/*
+ * Although all the source-files created by OpenTTD are licensed under the
+ * GPL-v2, this file is an exception. This file is part of the API for
+ * social integration plugins, and licensed under the MIT license, to allow
+ * for non-free implementations.
+ */
+
+/** @file openttd_social_integration_api.h Interface definitions for plugins to report/respond to social integration. */
+
+#ifndef OPENTTD_SOCIAL_INTEGRATION_API_H
+#define OPENTTD_SOCIAL_INTEGRATION_API_H
+
+#include "openttd_social_integration_api_v1.h"
+
+#endif /* OPENTTD_SOCIAL_INTEGRATION_API_H */

src/3rdparty/openttd_social_integration_api/openttd_social_integration_api_v1.h

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2024 OpenTTD project
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files
+ * (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+ * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/*
+ * Although all the source-files created by OpenTTD are licensed under the
+ * GPL-v2, this file is an exception. This file is part of the API for
+ * social integration plugins, and licensed under the MIT license, to allow
+ * for non-free implementations.
+ */
+
+/** @file v1.h Version 1 definition of the OpenTTD Social Integration Plugin API. */
+
+#ifndef OPENTTD_SOCIAL_INTEGRATION_API_V1_H
+#define OPENTTD_SOCIAL_INTEGRATION_API_V1_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Pointers supplied by the plugin for OpenTTD to use. */
+struct OpenTTD_SocialIntegration_v1_PluginInfo {
+	/**
+	 * The Social Platform this plugin is for.
+	 *
+	 * UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
+	 *
+	 * As there can only be one plugin active for each Social Platform, this
+	 * value is used to determine which plugin to use.
+	 *
+	 * A complete list of names can be found here:
+	 * https://wiki.openttd.org/en/Development/Social%20Integration
+	 *
+	 * Please use names from that list, including capitalization.
+	 *
+	 * If you create a plugin for a new Social Platform, please add it to the
+	 * wiki page.
+	 */
+	const char *social_platform;
+
+	const char *name; ///< Full name of the plugin. UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
+	const char *version; ///< Version of the plugin. UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
+};
+
+/** Pointers supplied by the plugin for OpenTTD to use. */
+struct OpenTTD_SocialIntegration_v1_PluginApi {
+	/**
+	 * OpenTTD tells the plugin to shut down.
+	 *
+	 * The plugin should free any resources it allocated, and must not call any of the callback functions after this call.
+	 */
+	void (*shutdown)();
+
+	/**
+	 * OpenTTD calls this function at regular intervals, to handle any callbacks the plugin might have.
+	 *
+	 * It is also safe to call the OpenTTD_SocialIntegrationCallbacks functions here.
+	 *
+	 * @return True if the plugin wants to be called again, false if the plugin wants to be unloaded.
+	 */
+	bool (*run_callbacks)();
+
+	/**
+	 * The player has entered the main menu.
+	 */
+	void (*event_enter_main_menu)();
+
+	/**
+	 * The player has entered the Scenario Editor.
+	 *
+	 * @param map_width The width of the map in tiles.
+	 * @param map_height The height of the map in tiles.
+	 */
+	void (*event_enter_scenario_editor)(unsigned int map_width, unsigned int map_height);
+
+	/**
+	 * The player has entered a singleplayer game.
+	 *
+	 * @param map_width The width of the map in tiles.
+	 * @param map_height The height of the map in tiles.
+	 */
+	void (*event_enter_singleplayer)(unsigned int map_width, unsigned int map_height);
+
+	/**
+	 * The player has entered a multiplayer game.
+	 *
+	 * @param map_width The width of the map in tiles.
+	 * @param map_height The height of the map in tiles.
+	 */
+	void (*event_enter_multiplayer)(unsigned int map_width, unsigned int map_height);
+
+	/**
+	 * The player is joining a multiplayer game.
+	 *
+	 * This is followed by event_enter_multiplayer() if the join was successful.
+	 */
+	void (*event_joining_multiplayer)();
+};
+
+/** Pointers supplied by OpenTTD, for the plugin to use. */
+struct OpenTTD_SocialIntegration_v1_OpenTTDInfo {
+	const char *openttd_version; ///< Version of OpenTTD. UTF-8, nul-terminated. OpenTTD is and remains the owner of the memory.
+};
+
+/** The result of the initialization. */
+enum OpenTTD_SocialIntegration_v1_InitResult : int {
+	OTTD_SOCIAL_INTEGRATION_V1_INIT_SUCCESS = 1, ///< Plugin initialized successfully.
+	OTTD_SOCIAL_INTEGRATION_V1_INIT_FAILED = -1, ///< Plugin failed to initialize (generic error).
+	OTTD_SOCIAL_INTEGRATION_V1_INIT_PLATFORM_NOT_RUNNING = -2, ///< The Social Platform is not running.
+};
+
+/**
+ * Type of the Init function the plugin is expected to export from its dynamic library.
+ *
+ * The plugin has to export the implementation of this function as "SocialIntegration_vN_Init", where N is the API version this entry point is for.
+ * A single plugin can have multiple versions implemented.
+ *
+ * @param[out] plugin_api    Structure the plugin must fill with pointers. Can contain nullptr if the plugin does not support a feature. The plugin is owner of the memory.
+ * @param[in]  openttd_info  Structure that OpenTTD filled with pointers. All pointers will remain valid until shutdown(). OpenTTD is owner of the memory.
+ * @return                   The status of the initialization.
+ */
+typedef OpenTTD_SocialIntegration_v1_InitResult (*OpenTTD_SocialIntegration_v1_Init)(OpenTTD_SocialIntegration_v1_PluginApi *plugin_api, const OpenTTD_SocialIntegration_v1_OpenTTDInfo *openttd_info);
+
+/**
+ * Type of the GetInfo function the plugin is expected to export from its dynamic library.
+ *
+ * The plugin has to export the implementation of this function as "SocialIntegration_vN_GetInfo", where N is the API version this entry point is for.
+ * A single plugin can have multiple versions implemented.
+ *
+ * @param[out] plugin_info   Structure the plugin must fill with pointers. The plugin is owner of the memory.
+ */
+typedef void (*OpenTTD_SocialIntegration_v1_GetInfo)(OpenTTD_SocialIntegration_v1_PluginInfo *plugin_info);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* OPENTTD_SOCIAL_INTEGRATION_API_V1_H */