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
43extern "C" {
44#endif
45
46typedef struct xcb_property_handlers xcb_property_handlers_t;
47typedef 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
49typedef struct {
50	uint32_t                       long_len;
51	xcb_generic_property_handler_t handler;
52	void                          *data;
53} xcb_property_handler_t;
54
55typedef struct xcb_property_handler_node xcb_property_handler_node_t;
56struct xcb_property_handler_node {
57	xcb_property_handler_node_t *next;
58	xcb_atom_t     name;
59	xcb_property_handler_t h;
60};
61
62struct 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 */
77xcb_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 */
86xcb_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 */
96void 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 */
102void 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 */
110xcb_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 */
123uint8_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 */
142uint8_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 */
151int 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__ */
162