property/xcb_property.h

   1 /*
   2  * Copyright (C) 2008 Julien Danjou <julien@danjou.info>
   3  *
   4  * Permission is hereby granted, free of charge, to any person
   5  * obtaining a copy of this software and associated documentation
   6  * files (the "Software"), to deal in the Software without
   7  * restriction, including without limitation the rights to use, copy,
   8  * modify, merge, publish, distribute, sublicense, and/or sell copies
   9  * of the Software, and to permit persons to whom the Software is
  10  * furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
  19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  20  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  21  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22  *
  23  * Except as contained in this notice, the names of the authors or
  24  * their institutions shall not be used in advertising or otherwise to
  25  * promote the sale, use or other dealings in this Software without
  26  * prior written authorization from the authors.
  27  */
  28
  29 /**
  30  * @defgroup xcb__property_t XCB Property Functions
  31  *
  32  * These functions ease the handling of X propertiess received.
  33  *
  34  * @{
  35  */
  36
  37 #ifndef __XCB_PROPERTY_H__
  38 #define __XCB_PROPERTY_H__
  39
  40 #include "xcb_event.h"
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 typedef struct xcb_property_handlers xcb_property_handlers_t;
  47 typedef int (*xcb_generic_property_handler_t)(void *data, xcb_connection_t *c, uint8_t state, xcb_window_t window, xcb_atom_t atom, xcb_get_property_reply_t *property);
  48
  49 typedef struct {
  50         uint32_t                       long_len;
  51         xcb_generic_property_handler_t handler;
  52         void                          *data;
  53 } xcb_property_handler_t;
  54
  55 typedef struct xcb_property_handler_node xcb_property_handler_node_t;
  56 struct xcb_property_handler_node {
  57         xcb_property_handler_node_t *next;
  58         xcb_atom_t     name;
  59         xcb_property_handler_t h;
  60 };
  61
  62 struct xcb_property_handlers {
  63         xcb_property_handler_node_t *head;
  64         xcb_property_handler_t      def;
  65         xcb_event_handlers_t        *evenths;
  66 };
  67
  68 /**
  69  * @brief Get any property from a window, from any format.
  70  * @param c The connection to the X server.
  71  * @param del Boolean value that determines whether the property is deleted.
  72  * @param window The window to get property from.
  73  * @param name The property atom name.
  74  * @param long_len The maximum length of the property.
  75  * @return A cookie.
  76  */
  77 xcb_get_property_cookie_t xcb_get_any_property(xcb_connection_t *c,
  78                                                uint8_t del,
  79                                                xcb_window_t window,
  80                                                xcb_atom_t name,
  81                                                uint32_t long_len);
  82
  83 /**
  84  * @see xcb_get_any_property
  85  */
  86 xcb_get_property_cookie_t xcb_get_any_property_unchecked(xcb_connection_t *c,
  87                                                          uint8_t del,
  88                                                          xcb_window_t window,
  89                                                          xcb_atom_t name,
  90                                                          uint32_t long_len);
  91 /**
  92  * @brief Initialize a property handlers structure.
  93  * @param prophs The property handlers data structure pointer.
  94  * @param evenths The event handlers.
  95  */
  96 void xcb_property_handlers_init(xcb_property_handlers_t *prophs, xcb_event_handlers_t *evenths);
  97
  98 /**
  99  * @brief Wipe a property handler structure.
 100  * @param prophs The property handlers data structure pointer.
 101  */
 102 void xcb_property_handlers_wipe(xcb_property_handlers_t *prophs);
 103
 104 /**
 105  * @brief Get a event handlers from a property handlers data structure.
 106  * @param prophs The property handlers.
 107  * @return The event handlers data structure which was set if any, NULL
 108  * otherwise.
 109  */
 110 xcb_event_handlers_t *xcb_property_get_event_handlers(xcb_property_handlers_t *prophs);
 111
 112 /**
 113  * @brief Set a property handler for an event.
 114  * @param prophs The property handlers.
 115  * @param name The property atom name.
 116  * @param long_len The maximum length of the property value that will be
 117  * handled.
 118  * @param handler The handler callback function.
 119  * @param data Optional data that will be passed as argument of the handler
 120  * callback function. Can be NULL safely if you do not need it.
 121  * @return Return 1 on success, 0 otherwise.
 122  */
 123 uint8_t xcb_property_set_handler(xcb_property_handlers_t *prophs,
 124                                  xcb_atom_t name,
 125                                  uint32_t long_len,
 126                                  xcb_generic_property_handler_t handler,
 127                                  void *data);
 128
 129 /**
 130  * @brief Set the default property handler.
 131  * If a property does not have its own handler function, this one will be
 132  * used.
 133  * @param prophs The property handlers.
 134  * @param name The property atom name.
 135  * @param long_len The maximum length of the property value that will be
 136  * handled.
 137  * @param handler The handler callback function.
 138  * @param data Optional data that will be passed as argument of the handler
 139  * callback function. Can be NULL safely if you do not need it.
 140  * @return Return 1 on success, 0 otherwise.
 141  */
 142 uint8_t xcb_property_set_default_handler(xcb_property_handlers_t *prophs, uint32_t long_len, xcb_generic_property_handler_t handler, void *data);
 143
 144 /**
 145  * @brief Notify that a property has changed and call handler function callback as needed.
 146  * @param prophs The property handlers.
 147  * @param state The property state.
 148  * @param window The window.
 149  * @param atom The property atom name.
 150  */
 151 int xcb_property_changed(xcb_property_handlers_t *prophs, uint8_t state, xcb_window_t window, xcb_atom_t atom);
 152
 153 #ifdef __cplusplus
 154 }
 155 #endif
 156
 157 /**
 158  * @}
 159  */
 160
 161 #endif /* __XCB_PROPERTY_H__ */