Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
.\" Copyright \(co 2009 Red Hat, Inc.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a
|
|
|
|
|
.\" copy of this software and associated documentation files (the "Software"),
|
|
|
|
|
.\" to deal in the Software without restriction, including without limitation
|
|
|
|
|
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
|
|
|
|
.\" and/or sell copies of the Software, and to permit persons to whom the
|
|
|
|
|
.\" Software is furnished to do so, subject to the following conditions:
|
|
|
|
|
.\"
|
|
|
|
|
.\" The above copyright notice and this permission notice (including the next
|
|
|
|
|
.\" paragraph) shall be included in all copies or substantial portions of the
|
|
|
|
|
.\" Software.
|
|
|
|
|
.\"
|
|
|
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
|
|
|
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
|
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
|
|
|
|
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
|
|
|
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
|
|
|
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
|
|
|
|
.\" DEALINGS IN THE SOFTWARE.
|
|
|
|
|
.\"
|
|
|
|
|
.ds xT X Toolkit Intrinsics \- C Language Interface
|
|
|
|
|
.ds xW Athena X Widgets \- C Language X Toolkit Interface
|
|
|
|
|
.ds xL Xlib \- C Language X Interface
|
|
|
|
|
.ds xC Inter-Client Communication Conventions Manual
|
|
|
|
|
.TH XGetEventData __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
|
|
|
|
|
.SH NAME
|
|
|
|
|
XGetEventData, XFreeEventData, XGenericEventCookie \- retrieve and free additional event data through cookies.
|
|
|
|
|
.SH SYNTAX
|
|
|
|
|
.HP
|
|
|
|
|
Bool XGetEventData\^(\^Display *\fIdisplay\fP\^, XGenericEventCookie *\fIcookie\fP\^);
|
|
|
|
|
.HP
|
|
|
|
|
void XFreeEventData\^(\^Display *\fIdisplay\fP\^, XGenericEventCookie *\fIcookie\fP\^);
|
|
|
|
|
.HP
|
|
|
|
|
.SH ARGUMENTS
|
|
|
|
|
.IP \fIdisplay\fP 1i
|
|
|
|
|
Specifies the connection to the X server.
|
|
|
|
|
.IP \fIcookie\fP 1i
|
|
|
|
|
Specifies the cookie to free or retrieve the data for.
|
|
|
|
|
|
|
|
|
|
.SH STRUCTURES
|
2019-07-29 17:47:35 +02:00
|
|
|
.EX
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
typedef struct {
|
2012-08-23 08:24:17 -04:00
|
|
|
int type;
|
|
|
|
|
unsigned long serial;
|
|
|
|
|
Bool send_event;
|
|
|
|
|
Display *display;
|
|
|
|
|
int extension;
|
|
|
|
|
int evtype;
|
|
|
|
|
unsigned int cookie;
|
|
|
|
|
void *data;
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
} XGenericEventCookie;
|
2019-07-29 17:47:35 +02:00
|
|
|
.EE
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
Some extension
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGenericEvents
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
require additional memory to store information.
|
|
|
|
|
For these events, the library returns a
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGenericEventCookie
|
2019-07-30 05:07:40 -04:00
|
|
|
with a token ('cookie') unique to this event.
|
|
|
|
|
The
|
2019-07-03 18:18:09 +02:00
|
|
|
.BR XGenericEventCookie 's
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
data pointer is undefined until
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGetEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
is called.
|
|
|
|
|
|
|
|
|
|
The
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGetEventData
|
2019-07-30 05:07:40 -04:00
|
|
|
function retrieves this extra data for the given cookie.
|
|
|
|
|
No round-trip to
|
|
|
|
|
the server is required.
|
|
|
|
|
If the cookie is invalid or the
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
event is not an event handled by cookie handlers,
|
2019-07-03 18:18:09 +02:00
|
|
|
.B False
|
2019-07-30 05:07:40 -04:00
|
|
|
is returned.
|
|
|
|
|
If
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGetEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
returns
|
2019-07-03 18:18:09 +02:00
|
|
|
.BR True ,
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
the cookie's data pointer points to the memory containing the event
|
2019-07-30 05:07:40 -04:00
|
|
|
information.
|
|
|
|
|
A client must call
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XFreeEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
to free this memory.
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGetEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
returns
|
2019-07-03 18:18:09 +02:00
|
|
|
.B False
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
for multiple calls for the same event cookie.
|
|
|
|
|
|
|
|
|
|
The
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XFreeEventData
|
2019-07-30 05:07:40 -04:00
|
|
|
function frees the data associated with a cookie.
|
|
|
|
|
A client must call
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XFreeEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
for each cookie claimed with
|
2019-07-03 18:18:09 +02:00
|
|
|
.BR XGetEventData .
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
|
|
|
|
|
.SH EXAMPLE CODE
|
2019-07-29 17:47:35 +02:00
|
|
|
.EX
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
XEvent event;
|
|
|
|
|
XGenericEventCookie *cookie = &ev;
|
|
|
|
|
|
|
|
|
|
XNextEvent(display, &event);
|
|
|
|
|
if (XGetEventData(display, cookie)) {
|
|
|
|
|
handle_cookie_event(cookie->data);
|
|
|
|
|
} else
|
|
|
|
|
handle_event(&event);
|
|
|
|
|
}
|
|
|
|
|
XFreeEventData(display, cookie);
|
2019-07-29 17:47:35 +02:00
|
|
|
.EE
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
|
|
|
|
|
.SH NOTES
|
|
|
|
|
A cookie is defined as unclaimed if it has been returned to the client
|
|
|
|
|
through
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XNextEvent
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
but its data has not been retrieved via
|
2019-07-03 18:18:09 +02:00
|
|
|
.BR XGetEventData .
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
Subsequent calls to
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XNextEvent
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
may free memory associated with unclaimed cookies.
|
|
|
|
|
Multi-threaded X clients must ensure that
|
2019-07-03 18:18:09 +02:00
|
|
|
.B XGetEventData
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
is called before the next call to
|
2019-07-03 18:18:09 +02:00
|
|
|
.BR XNextEvent .
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
|
|
|
|
|
.SH "SEE ALSO"
|
2025-07-13 10:57:31 -07:00
|
|
|
.BR XNextEvent (__libmansuffix__),
|
Add generic event cookie handling to libX11.
Generic events require more bytes than Xlib provides in the standard XEvent.
Memory allocated by the extension and stored as pointers inside the event is
prone to leak by simple 'while (1) { XNextEvent(...); }' loops.
This patch adds cookie handling for generic events. Extensions may register
a cookie handler in addition to the normal event vectors. If an extension
has registered a cookie handler, _all_ generic events for this extensions
must be handled through cookies. Otherwise, the default event handler is
used.
The cookie handler must return an XGenericEventCookie with a pointer to the
data.The rest of the event (type, serialNumber, etc.) are to be filled as
normal. When a client retrieves such a cookie event, the data is stored in
an internal queue (the 'cookiejar'). This data is freed on the next call to
XNextEvent().
New extension interfaces:
XESetWireToEventCookie(display, extension_number, cookie_handler)
Where cookie_handler must set cookie->data. The data pointer is of arbitray
size and type but must be a single memory block. This memory block
represents the actual extension's event.
New client interfaces:
XGetEventData(display, *cookie);
XFreeEventData(display, *cookie);
If the client needs the actual event data, it must call XGetEventData() with
the cookie. This returns the data pointer (and removes it from the cookie
jar) and the client is then responsible for freeing the event with
XFreeEventData(). It is safe to call either function with a non-cookie
event. Events unclaimed or not handled by the XGetEventData() are cleaned up
automatically.
Example client code:
XEvent event;
XGenericEventCookie *cookie = &ev;
XNextEvent(display, &event);
if (XGetEventData(display, cookie)) {
XIEvent *xievent = cookie->data;
...
} else if (cookie->type == GenericEvent) {
/* handle generic event */
} else {
/* handle extension/core event */
}
XFreeEventData(display, cookie);
Cookies are not multi-threading safe. Clients that use XGetEventData() must
lock between XNextEvent and XGetEventData to avoid other threads freeing
cookies.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2009-06-26 11:27:43 +10:00
|
|
|
.br
|
|
|
|
|
\fI\*(xL\fP
|
|
|
|
|
|
