libclipboard.h (9194B)
1 /** 2 * \file libclipboard.h 3 * \brief Main header file 4 * 5 * \copyright Copyright (C) 2016 Jeremy Tan. 6 * This file is released under the MIT license. 7 * 8 * The MIT License (MIT) 9 * 10 * Copyright (c) 2016 Jeremy Tan 11 * 12 * Permission is hereby granted, free of charge, to any person obtaining a copy 13 * of this software and associated documentation files (the "Software"), to deal 14 * in the Software without restriction, including without limitation the rights 15 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 16 * copies of the Software, and to permit persons to whom the Software is 17 * furnished to do so, subject to the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be included in all 20 * copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 25 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 27 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 28 * SOFTWARE. 29 */ 30 31 #ifndef _LIBCLIPBOARD_H_ 32 #define _LIBCLIPBOARD_H_ 33 34 #include "libclipboard-config.h" 35 #include <stdbool.h> 36 #include <stdint.h> 37 #include <stdlib.h> 38 39 /* Symbol exports and calling convention logic */ 40 #if defined(_WIN32) || defined(__CYGWIN__) 41 # define LIBCLIPBOARD_DLL_IMPORT __declspec(dllimport) 42 # define LIBCLIPBOARD_DLL_EXPORT __declspec(dllexport) 43 # define LIBCLIPBOARD_DLL_LOCAL 44 # if defined(LIBCLIPBOARD_USE_STDCALL) && !defined(_WIN64) 45 # define LCB_CC __stdcall 46 # else 47 # define LCB_CC 48 # endif 49 #else 50 # if __GNUC__ >= 4 51 # define LIBCLIPBOARD_DLL_IMPORT __attribute__ ((visibility ("default"))) 52 # define LIBCLIPBOARD_DLL_EXPORT __attribute__ ((visibility ("default"))) 53 # define LIBCLIPBOARD_DLL_LOCAL __attribute__ ((visibility ("hidden"))) 54 # else 55 # define LIBCLIPBOARD_DLL_IMPORT 56 # define LIBCLIPBOARD_DLL_EXPORT 57 # define LIBCLIPBOARD_DLL_LOCAL 58 # endif 59 # define LCB_CC 60 #endif 61 62 #ifdef LIBCLIPBOARD_BUILD_SHARED 63 # ifdef clipboard_EXPORTS /* Defined by CMake when we're compiling the shared library */ 64 # define LCB_API LIBCLIPBOARD_DLL_EXPORT 65 # else 66 # define LCB_API LIBCLIPBOARD_DLL_IMPORT 67 # endif 68 # define LCB_LOCAL LIBCLIPBOARD_DLL_LOCAL 69 #else 70 # define LCB_API 71 # define LCB_LOCAL 72 #endif 73 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 /** Default action timeout of 1500ms **/ 79 #define LCB_X11_ACTION_TIMEOUT_DEFAULT 1500 80 /** Default transfer size (X11 only), default 1MB (must be multiple of 4) **/ 81 #define LCB_X11_TRANSFER_SIZE_DEFAULT 1048576 82 /** Default max number of retries to try to obtain clipboard lock **/ 83 #define LCB_WIN32_MAX_RETRIES_DEFAULT 5 84 /** Default delay in ms between retries to obtain clipboard lock **/ 85 #define LCB_WIN32_RETRY_DELAY_DEFAULT 5 86 87 /** 88 * \brief For internal use only. Initialises custom allocators. 89 * 90 * \param [out] cb Clipboard context 91 * \param [in] opts Clipboard options 92 */ 93 #define LCB_SET_ALLOCATORS(cb, opts) do { \ 94 (cb)->malloc = (opts) && (opts)->user_malloc_fn ? (opts)->user_malloc_fn : malloc; \ 95 (cb)->calloc = (opts) && (opts)->user_calloc_fn ? (opts)->user_calloc_fn : calloc; \ 96 (cb)->realloc = (opts) && (opts)->user_realloc_fn ? (opts)->user_realloc_fn : realloc; \ 97 (cb)->free = (opts) && (opts)->user_free_fn ? (opts)->user_free_fn : free; \ 98 } while(0) 99 100 /** Custom malloc function signature **/ 101 typedef void *(*clipboard_malloc_fn)(size_t size); 102 /** Custom calloc function signature **/ 103 typedef void *(*clipboard_calloc_fn)(size_t nmemb, size_t size); 104 /** Custom realloc function signature **/ 105 typedef void *(*clipboard_realloc_fn)(void *ptr, size_t size); 106 /** Custom free function signature **/ 107 typedef void (*clipboard_free_fn)(void *ptr); 108 109 /** 110 * Determines which clipboard is used in called functions. 111 */ 112 typedef enum clipboard_mode { 113 /** The primary (global) clipboard **/ 114 LCB_CLIPBOARD = 0, 115 /** The (global) mouse selection clipboard **/ 116 LCB_PRIMARY, 117 /** The (global) mouse selection clipboard; for backwards compatibility **/ 118 LCB_SELECTION = LCB_PRIMARY, 119 /** The largely unused (global) secondary selection clipboard **/ 120 LCB_SECONDARY, 121 /** Sentinel value for end of clipboard modes **/ 122 LCB_MODE_END 123 } clipboard_mode; 124 125 /** 126 * Options to be passed on instantiation. 127 */ 128 typedef struct clipboard_opts { 129 /* I would put the OS specific opts in a union, but anonymous unions are non-standard */ 130 /* Typing out union names is too much effort */ 131 132 /** X11 specific options **/ 133 struct clipboard_opts_x11 { 134 /** Max time (ms) to wait for action to complete **/ 135 int action_timeout; 136 /** Transfer size, in bytes. Must be a multiple of 4. **/ 137 uint32_t transfer_size; 138 /** The name of the X11 display (NULL for default - DISPLAY env. var.) **/ 139 const char *display_name; 140 } x11; 141 142 /** Win32 specific options **/ 143 struct clipboard_opts_win32 { 144 /** 145 * Max number of retries to try to obtain clipboard lock. 146 * If max_retries is zero, the default value will be used. 147 * Specify a negative value for zero retries. 148 */ 149 int max_retries; 150 /** 151 * Delay in ms between retries to obtain clipboard lock. 152 * If retry_delay is zero, the default value will be used. 153 * Specify a negative value for no (zero) delay. 154 */ 155 int retry_delay; 156 } win32; 157 158 /** User specified malloc (NULL for default) **/ 159 clipboard_malloc_fn user_malloc_fn; 160 /** User specified calloc (NULL for default) **/ 161 clipboard_calloc_fn user_calloc_fn; 162 /** User specified realloc (NULL for default) **/ 163 clipboard_realloc_fn user_realloc_fn; 164 /** User specified free (NULL for default) **/ 165 clipboard_free_fn user_free_fn; 166 } clipboard_opts; 167 168 /** Opaque data structure for a clipboard context/instance **/ 169 typedef struct clipboard_c clipboard_c; 170 171 /** 172 * \brief Instantiates a new clipboard instance of the given type. 173 * 174 * \param [in] cb_opts Implementation specific options (optional). 175 * \return The new clipboard instance, or NULL on failure. 176 */ 177 LCB_API clipboard_c *LCB_CC clipboard_new(clipboard_opts *cb_opts); 178 179 /** 180 * \brief Frees associated clipboard data from the provided structure. 181 * 182 * \param [in] cb The clipboard to be freed. 183 */ 184 LCB_API void LCB_CC clipboard_free(clipboard_c *cb); 185 186 /** 187 * \brief Clears the contents of the given clipboard. 188 * 189 * \param [in] cb The clipboard to clear. 190 * \param [in] mode Which clipboard to clear (platform dependent) 191 */ 192 LCB_API void LCB_CC clipboard_clear(clipboard_c *cb, clipboard_mode mode); 193 194 /** 195 * \brief Determines if the clipboard is currently owned 196 * 197 * \param [in] cb The clipboard to check 198 * \param [in] mode Which clipboard to clear (platform dependent) 199 * \return true iff the clipboard data is owned by the provided instance. 200 */ 201 LCB_API bool LCB_CC clipboard_has_ownership(clipboard_c *cb, clipboard_mode mode); 202 203 /** 204 * \brief Retrieves the text currently held on the clipboard. 205 * 206 * \param [in] cb The clipboard to retrieve from 207 * \param [out] length Returns the length of the retrieved data, excluding 208 * the NULL terminator (optional). 209 * \param [in] mode Which clipboard to clear (platform dependent) 210 * \return A copy to the retrieved text. This must be free()'d by the user. 211 * Note that the text is encoded in UTF-8 format. 212 */ 213 LCB_API char *LCB_CC clipboard_text_ex(clipboard_c *cb, int *length, clipboard_mode mode); 214 215 /** 216 * \brief Simplified version of clipboard_text_ex 217 * 218 * \param [in] cb The clipboard to retrieve from 219 * \return As per clipboard_text_ex. 220 * 221 * \details This function assumes LCB_CLIPBOARD as the clipboard mode. 222 */ 223 LCB_API char *LCB_CC clipboard_text(clipboard_c *cb); 224 225 /** 226 * \brief Sets the text for the provided clipboard. 227 * 228 * \param [in] cb The clipboard to set the text. 229 * \param [in] src The UTF-8 encoded text to be set in the clipboard. 230 * \param [in] length The length of text to be set (excluding the NULL 231 * terminator). 232 * \param [in] mode Which clipboard to clear (platform dependent) 233 * \return true iff the clipboard was set (false on error) 234 * 235 * \details If the length parameter is -1, src is treated as a NULL-terminated 236 * string and its length will be determined automatically. 237 */ 238 LCB_API bool LCB_CC clipboard_set_text_ex(clipboard_c *cb, const char *src, int length, clipboard_mode mode); 239 240 /** 241 * \brief Simplified version of clipboard_set_text_ex 242 * 243 * \param [in] cb The clipboard to set the text. 244 * \param [in] src The UTF-8 encoded NULL terminated string to be set. 245 * \return true iff the clipboard was set (false on error) 246 * 247 * \details This function assumes LCB_CLIPBOARD as the clipboard mode. 248 */ 249 LCB_API bool LCB_CC clipboard_set_text(clipboard_c *cb, const char *src); 250 251 #ifdef __cplusplus 252 } 253 #endif 254 255 #endif /* _LIBCLIPBOARD_H_ */