mudgangster

Tiny, scriptable MUD client
Log | Files | Refs | README

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_ */