diff --git a/src/3rdparty/openttd_social_integration_api/openttd_social_integration_api_v1.h b/src/3rdparty/openttd_social_integration_api/openttd_social_integration_api_v1.h new file mode 100644 --- /dev/null +++ b/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 */