dix: unexport non-public functions from dixgrabs.h and document prototypes

* unexport functions from dixgrab.h, that aren't used by any driver/module.
* add paremeter names to prototypes
* add doxygen-style documentation for all the prototypes

Signed-off-by: Enrico Weigelt, metux IT consult <info@metux.net>

Xi/exevents.c

@@ -91,6 +91,7 @@ SOFTWARE.
 #include <X11/extensions/XKBproto.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/eventconvert.h"
 #include "dix/exevents_priv.h"
 #include "dix/input_priv.h"
@@ -103,7 +104,6 @@ SOFTWARE.
 #include "exglobals.h"
 #include "eventstr.h"
 #include "dixevents.h"          /* DeliverFocusedEvent */
-#include "dixgrabs.h"           /* CreateGrab() */
 #include "scrnintstr.h"
 #include "listdev.h"            /* for CopySwapXXXClass */
 #include "xace.h"

Xi/ungrdevb.c

@@ -56,11 +56,11 @@ SOFTWARE.
 #include <X11/extensions/XIproto.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 
 #include "inputstr.h"           /* DeviceIntPtr      */
 #include "windowstr.h"          /* window structure  */
 #include "exglobals.h"
-#include "dixgrabs.h"
 #include "ungrdevb.h"
 
 #define AllModifiersMask ( \

Xi/ungrdevk.c

@@ -56,11 +56,11 @@ SOFTWARE.
 #include <X11/extensions/XIproto.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 
 #include "inputstr.h"           /* DeviceIntPtr      */
 #include "windowstr.h"          /* window structure  */
 #include "exglobals.h"
-#include "dixgrabs.h"
 #include "xkbsrv.h"
 #include "xkbstr.h"
 #include "ungrdevk.h"

Xi/xipassivegrab.c

@@ -35,6 +35,7 @@
 #include <X11/extensions/XI2proto.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/exevents_priv.h"
 
 #include "inputstr.h"           /* DeviceIntPtr      */
@@ -42,7 +43,6 @@
 #include "swaprep.h"
 #include "exglobals.h"          /* BadDevice */
 #include "xipassivegrab.h"
-#include "dixgrabs.h"
 #include "misc.h"
 #include "inpututils.h"
 

dix/devices.c

@@ -56,6 +56,7 @@ SOFTWARE.
 #include <X11/extensions/XIproto.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/exevents_priv.h"
 #include "dix/input_priv.h"
 #include "dix/ptrveloc_priv.h"
@@ -77,7 +78,6 @@ SOFTWARE.
 #include "dixevents.h"
 #include "mipointer.h"
 #include "eventstr.h"
-#include "dixgrabs.h"
 #include "exglobals.h"
 #include "xiquerydevice.h"      /* for SizeDeviceClasses */
 #include "xiproperty.h"

dix/dixgrabs_priv.h

@@ -0,0 +1,171 @@
+/* SPDX-License-Identifier: MIT OR X11
+ *
+ * Copyright © 2024 Enrico Weigelt, metux IT consult <info@metux.net>
+ */
+#ifndef _XSERVER_DIXGRABS_PRIV_H_
+#define _XSERVER_DIXGRABS_PRIV_H_
+
+#include <X11/extensions/XIproto.h>
+
+#include "misc.h"
+#include "window.h"
+#include "input.h"
+#include "cursor.h"
+
+struct _GrabParameters;
+
+/**
+ * @brief Print current device grab information for specific device
+ *
+ * Walks through all active grabs and dumps them into the Xserver's error log.
+ * This is usually for debugging and troubleshooting. Will also be called by
+ * UngrabAllDevices().
+ *
+ * @param dev the device to act on
+ */
+void PrintDeviceGrabInfo(DeviceIntPtr dev);
+
+/**
+ * @brief Forcefully remove _all_ device grabs
+ *
+ * Forcefully remove all device grabs on all devices. Optionally kill the
+ * clients holding a grab
+ *
+ * @param kill_client TRUE if clients holding a grab should be killed
+ */
+void UngrabAllDevices(Bool kill_client);
+
+/**
+ * @brief Allocate new grab, optionally copy from existing
+ *
+ * Allocate a new grab structure. If src is non-null, copy parameters from
+ * the existing grab.
+ *
+ * Returns NULL in case of OOM or when src grab is given, but copy failed.
+ *
+ * @param src optional grab to copy from (NULL = don't copy)
+ * @return pointer to new grab. Must be freed via ::FreeGrab().
+ */
+GrabPtr AllocGrab(const GrabPtr src);
+
+/**
+ * @brief Free a grab
+ *
+ * Free a grab (that had been allocated by ::AllocGrab()). If the grab has
+ * a cursor, this will also be unref'ed / free'd.
+ *
+ * @param grab pointer to the grab to be freed. Tolerates NULL.
+ */
+void FreeGrab(GrabPtr grab);
+
+/**
+ * @brief create a new grab for given client
+ *
+ * Create a new grab for given client, with given parameters.
+ * Returns NULL on OOM.
+ *
+ * @param client _Index_ of the client who will hold the grab
+ * @param device Device that's being grabbed
+ * @param modDevice Device whose modifiers are used (NULL = use core keyboard)
+ * @param window the window getting the events
+ * @param grabtype type of grab (see ::"enum InputLevel")
+ * @param mask mask for fields used from param
+ * @param param pointer to struct holding additional parameters
+ * @param eventType type of event to grab on (eg. DeviceButtonPress)
+ * @param keyCode KeyCode of key or button to grab
+ * @param confineTo window to restrict device into (may be NULL)
+ * @param cursor cursor to be used while grabbed (may be NULL)
+ * @return newly created grab. Must be freed by ::FreeGrab()
+ */
+GrabPtr CreateGrab(int client,
+                   DeviceIntPtr device,
+                   DeviceIntPtr modDevice,
+                   WindowPtr window,
+                   enum InputLevel grabtype,
+                   GrabMask *mask,
+                   struct _GrabParameters *param,
+                   int eventType,
+                   KeyCode keycode,
+                   WindowPtr confineTo,
+                   CursorPtr cursor);
+
+/**
+ * @brief check whether it is a pointer grab
+ *
+ * @param grab pointer to the grab structure to check
+ * @return TRUE if grabbed a pointer
+ */
+Bool GrabIsPointerGrab(GrabPtr grab);
+
+/**
+ * @brief check whether it is a keyboard grab
+ *
+ * @param grab pointer to the grab structure to check
+ * @return TRUE if grabbed a keyboard
+ */
+Bool GrabIsKeyboardGrab(GrabPtr grab);
+
+/**
+ * @brief check whether it is a gesture grab
+ *
+ * @param grab pointer to the grab structure to check
+ * @return TRUE if grabbed a gesture
+ */
+Bool GrabIsGestureGrab(GrabPtr grab);
+
+/**
+ * @brief destructor for X11_RESTYPE_PASSIVEGRAB resource type
+ *
+ * Destructor for the X11_RESTYPE_PASSIVEGRAB resource type.
+ * Should not be used anywhere else
+ *
+ * @param value pointer to the resource data object
+ * @param XID the X11 ID of the resource object
+ * @return result code (always Success)
+ */
+int DeletePassiveGrab(void *value, XID id);
+
+/*
+ * @brief compare to grabs
+ *
+ * Check whether two grabs match each other: grabbing the same events
+ * and (optional) grabbing on the same device.
+ *
+ * @param pFirstGrab first grab to compare
+ * @param pSecondGrab second grab to compare
+ * @param ignoreDevice TRUE if devices don't need to match
+ * @return TRUE if both grabs are having the same claims
+ */
+Bool GrabMatchesSecond(GrabPtr pFirstGrab,
+                       GrabPtr pSecondGrab,
+                       Bool ignoreDevice);
+
+/**
+ * @brief add passive grab to a client
+ *
+ * Prepend a grab to the clients's list of passive grabs.
+ * Previously existing matching ones are deleted.
+ * On conflict with another client's grabs, return BadAccess.
+ *
+ * @param client pointer to the client the new grab is added to
+ * @param pGrab pointer to the grab to be added.
+ * @return X11 error code: BadAccess on conflict, otherwise Success
+ */
+int AddPassiveGrabToList(ClientPtr client, GrabPtr pGrab);
+
+/**
+ * @brief delete grab claims from a window's passive grabs list
+ *
+ * Delete the items affected by given grab from the currently existing
+ * passive grabs on a window. This walk through list of passive grabs
+ * of the associated window and delete the claims matching this one's.
+ *
+ * The grab structure passed in here is just used as a vehicle for
+ * specifying which claims should be deleted (on which window).
+ *
+ * @param pMinuedGrab GrabRec structure specifying which claims to delete
+ * @return TRUE if succeeded (FALSE usually indicated allocation failure)
+ */
+Bool DeletePassiveGrabFromList(GrabPtr pMinuendGrab);
+
+#endif /* _XSERVER_DIXGRABS_PRIV_H_ */

dix/events.c

@@ -104,6 +104,12 @@ Equipment Corporation.
 #include <dix-config.h>
 
 #include <X11/X.h>
+#include <X11/extensions/ge.h>
+#include <X11/extensions/XKBproto.h>
+#include <X11/extensions/XIproto.h>
+#include <X11/extensions/XI2proto.h>
+#include <X11/extensions/XI.h>
+#include <X11/extensions/XI2.h>
 #include <X11/Xproto.h>
 #include <X11/extensions/ge.h>
 #include <X11/extensions/XI.h>
@@ -114,6 +120,7 @@ Equipment Corporation.
 
 #include "dix/cursor_priv.h"
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/input_priv.h"
 #include "dix/eventconvert.h"
 #include "dix/exevents_priv.h"
@@ -137,7 +144,6 @@ Equipment Corporation.
 #include "exglobals.h"
 #include "extnsionst.h"
 #include "dixevents.h"
-#include "dixgrabs.h"
 #include "dispatch.h"
 #include "geext.h"
 #include "geint.h"

dix/gestures.c

@@ -26,12 +26,12 @@
 #include <dix-config.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/eventconvert.h"
 #include "dix/input_priv.h"
 
 #include "inputstr.h"
 #include "scrnintstr.h"
-#include "dixgrabs.h"
 #include "eventstr.h"
 #include "exevents.h"
 #include "exglobals.h"

dix/grabs.c

@@ -53,6 +53,7 @@ SOFTWARE.
 
 #include "dix/cursor_priv.h"
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/exevents_priv.h"
 #include "os/auth.h"
 #include "os/client_priv.h"
@@ -61,7 +62,6 @@ SOFTWARE.
 #include "windowstr.h"
 #include "inputstr.h"
 #include "cursorstr.h"
-#include "dixgrabs.h"
 #include "xace.h"
 #include "exglobals.h"
 #include "inpututils.h"

dix/resource.c

@@ -122,6 +122,7 @@ Equipment Corporation.
 #include <X11/X.h>
 
 #include "dix/colormap_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/gc_priv.h"
 #include "dix/registry_priv.h"
 #include "os/osdep.h"
@@ -135,8 +136,6 @@ Equipment Corporation.
 #include "dixfont.h"
 #include "colormap.h"
 #include "inputstr.h"
-#include "dixevents.h"
-#include "dixgrabs.h"
 #include "cursor.h"
 #ifdef PANORAMIX
 #include "panoramiX.h"

dix/touch.c

@@ -27,13 +27,13 @@
 #include <dix-config.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/eventconvert.h"
 #include "dix/exevents_priv.h"
 #include "dix/input_priv.h"
 
 #include "inputstr.h"
 #include "scrnintstr.h"
-#include "dixgrabs.h"
 #include "eventstr.h"
 #include "exglobals.h"
 #include "inpututils.h"

hw/xfree86/sdksyms.sh

@@ -236,7 +236,6 @@ cat > sdksyms.c << EOF
 #define _FONTPROTO_H
 #include "dixfont.h"
 #include "dixfontstr.h"
-#include "dixgrabs.h"
 #include "dixstruct.h"
 #include "exevents.h"
 #include "extension.h"

hw/xfree86/xkb/xkbPrivate.c

@@ -10,7 +10,6 @@
 #include "windowstr.h"
 #include <xkbsrv.h>
 
-#include "dixgrabs.h"
 #include "os.h"
 #include "xf86.h"
 

include/dixgrabs.h

@@ -1,64 +0,0 @@
-/************************************************************
-
-Copyright 1996 by Thomas E. Dickey <dickey@clark.net>
-
-                        All Rights Reserved
-
-Permission to use, copy, modify, and distribute this software and its
-documentation for any purpose and without fee is hereby granted,
-provided that the above copyright notice appear in all copies and that
-both that copyright notice and this permission notice appear in
-supporting documentation, and that the name of the above listed
-copyright holder(s) not be used in advertising or publicity pertaining
-to distribution of the software without specific, written prior
-permission.
-
-THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM ALL WARRANTIES WITH REGARD
-TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS, IN NO EVENT SHALL THE ABOVE LISTED COPYRIGHT HOLDER(S) BE
-LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-********************************************************/
-
-#ifndef DIXGRABS_H
-#define DIXGRABS_H 1
-
-struct _GrabParameters;
-
-extern void PrintDeviceGrabInfo(DeviceIntPtr dev);
-extern void UngrabAllDevices(Bool kill_client);
-
-extern GrabPtr AllocGrab(const GrabPtr src);
-extern void FreeGrab(GrabPtr grab);
-
-extern GrabPtr CreateGrab(int /* client */ ,
-                          DeviceIntPtr /* device */ ,
-                          DeviceIntPtr /* modDevice */ ,
-                          WindowPtr /* window */ ,
-                          enum InputLevel /* grabtype */ ,
-                          GrabMask * /* mask */ ,
-                          struct _GrabParameters * /* param */ ,
-                          int /* eventType */ ,
-                          KeyCode /* keybut */ ,
-                          WindowPtr /* confineTo */ ,
-                          CursorPtr /* cursor */ );
-
-extern _X_EXPORT int DeletePassiveGrab(void *value,
-                                       XID id);
-
-extern _X_EXPORT Bool GrabMatchesSecond(GrabPtr /* pFirstGrab */ ,
-                                        GrabPtr /* pSecondGrab */ ,
-                                        Bool /*ignoreDevice */ );
-
-extern _X_EXPORT int AddPassiveGrabToList(ClientPtr /* client */ ,
-                                          GrabPtr /* pGrab */ );
-
-extern _X_EXPORT Bool DeletePassiveGrabFromList(GrabPtr /* pMinuendGrab */ );
-
-extern Bool GrabIsPointerGrab(GrabPtr grab);
-extern Bool GrabIsKeyboardGrab(GrabPtr grab);
-extern Bool GrabIsGestureGrab(GrabPtr grab);
-#endif                          /* DIXGRABS_H */

include/meson.build

@@ -453,7 +453,6 @@ if build_xorg
             'dixevents.h',
             'dixfont.h',
             'dixfontstr.h',
-            'dixgrabs.h',
             'dixstruct.h',
             'events.h',
             'exevents.h',

test/input.c

@@ -33,6 +33,7 @@
 #include <X11/Xatom.h>
 
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/eventconvert.h"
 #include "dix/exevents_priv.h"
 #include "dix/input_priv.h"
@@ -42,7 +43,6 @@
 #include "windowstr.h"
 #include "inputstr.h"
 #include "exglobals.h"
-#include "dixgrabs.h"
 #include "eventstr.h"
 #include "inpututils.h"
 #include "mi.h"

xkb/xkbActions.c

@@ -35,6 +35,7 @@ THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 #include "dix/cursor_priv.h"
 #include "dix/dix_priv.h"
+#include "dix/dixgrabs_priv.h"
 #include "dix/input_priv.h"
 #include "xkb/xkbsrv_priv.h"
 
@@ -45,7 +46,6 @@ THE USE OR PERFORMANCE OF THIS SOFTWARE.
 #include "mi.h"
 #include "mipointer.h"
 #include "inpututils.h"
-#include "dixgrabs.h"
 
 #define EXTENSION_EVENT_BASE 64