1 #ifndef __XCB_ERRORS_H__ 2 #define __XCB_ERRORS_H__ 3 4 /* Copyright © 2015 Uli Schlachter 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a 7 * copy of this software and associated documentation files (the "Software"), 8 * to deal in the Software without restriction, including without limitation 9 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 10 * and/or sell copies of the Software, and to permit persons to whom the 11 * Software is furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21 * CONNECTION 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 their 24 * institutions shall not be used in advertising or otherwise to promote the 25 * sale, use or other dealings in this Software without prior written 26 * authorization from the authors. 27 */ 28 29 #include <xcb/xcb.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * A context for using this library. 37 * 38 * Create a context with @ref xcb_errors_context_new () and destroy it with @ref 39 * xcb_errors_context_free (). Except for @ref xcb_errors_context_free (), all 40 * functions in this library are thread-safe and can be called from multiple 41 * threads at the same time, even on the same context. 42 */ 43 typedef struct xcb_errors_context_t xcb_errors_context_t; 44 45 /** 46 * Create a new @ref xcb_errors_context_t. 47 * 48 * @param conn A XCB connection which will be used until you destroy the context 49 * with @ref xcb_errors_context_free (). 50 * @param ctx A pointer to an xcb_cursor_context_t* which will be modified to 51 * refer to the newly created context. 52 * @return 0 on success, -1 otherwise. This function may fail due to memory 53 * allocation failures or if the connection ends up in an error state. 54 */ 55 int xcb_errors_context_new(xcb_connection_t *conn, xcb_errors_context_t **ctx); 56 57 /** 58 * Free the @ref xcb_cursor_context_t. 59 * 60 * @param ctx The context to free. 61 */ 62 void xcb_errors_context_free(xcb_errors_context_t *ctx); 63 64 /** 65 * Get the name corresponding to some major code. This is either the name of 66 * some core request or the name of the extension that owns this major code. 67 * 68 * @param ctx An errors context, created with @ref xcb_errors_context_new () 69 * @param major_code The major code 70 * @return A string allocated in static storage that contains a name for this 71 * major code. This will never return NULL, but other functions in this library 72 * may. 73 */ 74 const char *xcb_errors_get_name_for_major_code(xcb_errors_context_t *ctx, 75 uint8_t major_code); 76 77 /** 78 * Get the name corresponding to some minor code. When the major_code does not 79 * belong to any extension or the minor_code is not assigned inside this 80 * extension, NULL is returned. 81 * 82 * @param ctx An errors context, created with @ref xcb_errors_context_new () 83 * @param major_code The major code under which to look up the minor code 84 * @param major_code The minor code 85 * @return A string allocated in static storage that contains a name for this 86 * major code or NULL for unknown codes. 87 */ 88 const char *xcb_errors_get_name_for_minor_code(xcb_errors_context_t *ctx, 89 uint8_t major_code, 90 uint16_t minor_code); 91 92 /** 93 * Get the name corresponding to some core event code. If possible, you should 94 * use @ref xcb_errors_get_name_for_xcb_event instead. 95 * 96 * @param ctx An errors context, created with @ref xcb_errors_context_new () 97 * @param event_code The response_type of an event. 98 * @param extension Will be set to the name of the extension that generated this 99 * event or NULL for unknown events or core X11 events. This argument may be 100 * NULL. 101 * @return A string allocated in static storage that contains a name for this 102 * major code. This will never return NULL, but other functions in this library 103 * may. 104 */ 105 const char *xcb_errors_get_name_for_core_event(xcb_errors_context_t *ctx, 106 uint8_t event_code, const char **extension); 107 108 /** 109 * Get the name corresponding to some XGE or XKB event. XKB does not actually 110 * use the X generic event extension, but implements its own event multiplexing. 111 * This function also handles XKB's xkbType events as a event_type. 112 * 113 * If possible, you should use @ref xcb_errors_get_name_for_xcb_event instead. 114 * 115 * @param ctx An errors context, created with @ref xcb_errors_context_new () 116 * @param major_code The extension's major code 117 * @param event_type The type of the event in that extension. 118 * @return A string allocated in static storage that contains a name for this 119 * event or NULL for unknown event types. 120 */ 121 const char *xcb_errors_get_name_for_xge_event(xcb_errors_context_t *ctx, 122 uint8_t major_code, uint16_t event_type); 123 124 /** 125 * Get a human printable name describing the type of some event. 126 * 127 * @param ctx An errors context, created with @ref xcb_errors_context_new () 128 * @param event The event to investigate. 129 * @param extension Will be set to the name of the extension that generated this 130 * event or NULL for unknown events or core X11 events. This argument may be 131 * NULL. 132 * @return A string allocated in static storage that contains a name for this 133 * event or NULL for unknown event types. 134 */ 135 const char *xcb_errors_get_name_for_xcb_event(xcb_errors_context_t *ctx, 136 xcb_generic_event_t *event, const char **extension); 137 138 /** 139 * Get the name corresponding to some error. 140 * 141 * @param ctx An errors context, created with @ref xcb_errors_context_new () 142 * @param error_code The error_code of an error reply. 143 * @param extension Will be set to the name of the extension that generated this 144 * event or NULL for unknown errors or core X11 errors. This argument may be 145 * NULL. 146 * @return A string allocated in static storage that contains a name for this 147 * major code. This will never return NULL, but other functions in this library 148 * may. 149 */ 150 const char *xcb_errors_get_name_for_error(xcb_errors_context_t *ctx, 151 uint8_t error_code, const char **extension); 152 153 #ifdef __cplusplus 154 } 155 #endif 156 157 #endif /* __XCB_ERRORS_H__ */ 158