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