src/3rdparty/openttd_social_integration_api/openttd_social_integration_api_v1.h

   1 /*
   2  * Copyright 2024 OpenTTD project
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files
   6  * (the "Software"), to deal in the Software without restriction,
   7  * including without limitation the rights to use, copy, modify, merge,
   8  * publish, distribute, sublicense, and/or sell copies of the Software,
   9  * and to permit persons to whom the Software is furnished to do so,
  10  * subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included
  13  * in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  19  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  20  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  21  * OTHER DEALINGS IN THE SOFTWARE.
  22  */
  23
  24 /*
  25  * Although all the source-files created by OpenTTD are licensed under the
  26  * GPL-v2, this file is an exception. This file is part of the API for
  27  * social integration plugins, and licensed under the MIT license, to allow
  28  * for non-free implementations.
  29  */
  30
  31 /** @file v1.h Version 1 definition of the OpenTTD Social Integration Plugin API. */
  32
  33 #ifndef OPENTTD_SOCIAL_INTEGRATION_API_V1_H
  34 #define OPENTTD_SOCIAL_INTEGRATION_API_V1_H
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /** Pointers supplied by the plugin for OpenTTD to use. */
  41 struct OpenTTD_SocialIntegration_v1_PluginInfo {
  42         /**
  43          * The Social Platform this plugin is for.
  44          *
  45          * UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
  46          *
  47          * As there can only be one plugin active for each Social Platform, this
  48          * value is used to determine which plugin to use.
  49          *
  50          * A complete list of names can be found here:
  51          * https://wiki.openttd.org/en/Development/Social%20Integration
  52          *
  53          * Please use names from that list, including capitalization.
  54          *
  55          * If you create a plugin for a new Social Platform, please add it to the
  56          * wiki page.
  57          */
  58         const char *social_platform;
  59
  60         const char *name; ///< Full name of the plugin. UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
  61         const char *version; ///< Version of the plugin. UTF-8, nul-terminated. The plugin is and remains the owner of the memory.
  62 };
  63
  64 /** Pointers supplied by the plugin for OpenTTD to use. */
  65 struct OpenTTD_SocialIntegration_v1_PluginApi {
  66         /**
  67          * OpenTTD tells the plugin to shut down.
  68          *
  69          * The plugin should free any resources it allocated, and must not call any of the callback functions after this call.
  70          */
  71         void (*shutdown)();
  72
  73         /**
  74          * OpenTTD calls this function at regular intervals, to handle any callbacks the plugin might have.
  75          *
  76          * It is also safe to call the OpenTTD_SocialIntegrationCallbacks functions here.
  77          *
  78          * @return True if the plugin wants to be called again, false if the plugin wants to be unloaded.
  79          */
  80         bool (*run_callbacks)();
  81
  82         /**
  83          * The player has entered the main menu.
  84          */
  85         void (*event_enter_main_menu)();
  86
  87         /**
  88          * The player has entered the Scenario Editor.
  89          *
  90          * @param map_width The width of the map in tiles.
  91          * @param map_height The height of the map in tiles.
  92          */
  93         void (*event_enter_scenario_editor)(unsigned int map_width, unsigned int map_height);
  94
  95         /**
  96          * The player has entered a singleplayer game.
  97          *
  98          * @param map_width The width of the map in tiles.
  99          * @param map_height The height of the map in tiles.
 100          */
 101         void (*event_enter_singleplayer)(unsigned int map_width, unsigned int map_height);
 102
 103         /**
 104          * The player has entered a multiplayer game.
 105          *
 106          * @param map_width The width of the map in tiles.
 107          * @param map_height The height of the map in tiles.
 108          */
 109         void (*event_enter_multiplayer)(unsigned int map_width, unsigned int map_height);
 110
 111         /**
 112          * The player is joining a multiplayer game.
 113          *
 114          * This is followed by event_enter_multiplayer() if the join was successful.
 115          */
 116         void (*event_joining_multiplayer)();
 117 };
 118
 119 /** Pointers supplied by OpenTTD, for the plugin to use. */
 120 struct OpenTTD_SocialIntegration_v1_OpenTTDInfo {
 121         const char *openttd_version; ///< Version of OpenTTD. UTF-8, nul-terminated. OpenTTD is and remains the owner of the memory.
 122 };
 123
 124 /** The result of the initialization. */
 125 enum OpenTTD_SocialIntegration_v1_InitResult : int {
 126         OTTD_SOCIAL_INTEGRATION_V1_INIT_SUCCESS = 1, ///< Plugin initialized successfully.
 127         OTTD_SOCIAL_INTEGRATION_V1_INIT_FAILED = -1, ///< Plugin failed to initialize (generic error).
 128         OTTD_SOCIAL_INTEGRATION_V1_INIT_PLATFORM_NOT_RUNNING = -2, ///< The Social Platform is not running.
 129 };
 130
 131 /**
 132  * Type of the Init function the plugin is expected to export from its dynamic library.
 133  *
 134  * 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.
 135  * A single plugin can have multiple versions implemented.
 136  *
 137  * @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.
 138  * @param[in]  openttd_info  Structure that OpenTTD filled with pointers. All pointers will remain valid until shutdown(). OpenTTD is owner of the memory.
 139  * @return                   The status of the initialization.
 140  */
 141 typedef OpenTTD_SocialIntegration_v1_InitResult (*OpenTTD_SocialIntegration_v1_Init)(OpenTTD_SocialIntegration_v1_PluginApi *plugin_api, const OpenTTD_SocialIntegration_v1_OpenTTDInfo *openttd_info);
 142
 143 /**
 144  * Type of the GetInfo function the plugin is expected to export from its dynamic library.
 145  *
 146  * 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.
 147  * A single plugin can have multiple versions implemented.
 148  *
 149  * @param[out] plugin_info   Structure the plugin must fill with pointers. The plugin is owner of the memory.
 150  */
 151 typedef void (*OpenTTD_SocialIntegration_v1_GetInfo)(OpenTTD_SocialIntegration_v1_PluginInfo *plugin_info);
 152
 153 #ifdef __cplusplus
 154 } /* extern "C" */
 155 #endif
 156
 157 #endif /* OPENTTD_SOCIAL_INTEGRATION_API_V1_H */