Skip to content

One keyboard and mouse for a Mac and a Windows PC over the local network, in either direction.

17.2 KB
Raw Blame
"""Windows clipboard access via ctypes (user32 + kernel32), guarded like
input_injector.py so this module stays importable -- and its orchestration
testable -- on a machine without ctypes.windll, e.g. the Mac this was
developed on.

The clipboard is a contended, system-wide resource: any other process that
briefly holds it makes OpenClipboard fail, which is normal and expected, not
exceptional. `_open_clipboard` retries a handful of times with a short sleep
before giving up. This still wants confirmation on real Windows hardware
under load -- contention behaviour and timing were chosen to match common
guidance, not measured on a real desktop.

Images cross the wire as PNG but live on this clipboard as CF_DIB, so each
direction converts. The DIB half (`dib_to_bgra`, `bgra_to_dib`) is pure
Python over bytes and slices, so it runs and is tested on the Mac; the PNG
codec is Qt's QImage, which the app already ships for its window, imported
lazily so this module needs neither Qt nor Windows to load. No Pillow: it
would be a second imaging library and a binary wheel in the PyInstaller
build for a job QtGui already does.
"""

import ctypes
import logging
import struct
import sys
import threading
import time
from typing import Optional, Tuple


LOGGER = logging.getLogger(__name__)

_IS_WINDOWS = sys.platform == "win32"

user32 = ctypes.WinDLL("user32", use_last_error=True) if _IS_WINDOWS else None
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) if _IS_WINDOWS else None

if _IS_WINDOWS:
    user32.OpenClipboard.restype = ctypes.c_int
    user32.OpenClipboard.argtypes = [ctypes.c_void_p]
    user32.CloseClipboard.restype = ctypes.c_int
    user32.CloseClipboard.argtypes = []
    user32.EmptyClipboard.restype = ctypes.c_int
    user32.EmptyClipboard.argtypes = []
    user32.GetClipboardData.restype = ctypes.c_void_p
    user32.GetClipboardData.argtypes = [ctypes.c_uint]
    user32.IsClipboardFormatAvailable.restype = ctypes.c_int
    user32.IsClipboardFormatAvailable.argtypes = [ctypes.c_uint]
    user32.SetClipboardData.restype = ctypes.c_void_p
    user32.SetClipboardData.argtypes = [ctypes.c_uint, ctypes.c_void_p]
    kernel32.GlobalAlloc.restype = ctypes.c_void_p
    kernel32.GlobalAlloc.argtypes = [ctypes.c_uint, ctypes.c_size_t]
    kernel32.GlobalLock.restype = ctypes.c_void_p
    kernel32.GlobalLock.argtypes = [ctypes.c_void_p]
    kernel32.GlobalUnlock.restype = ctypes.c_int
    kernel32.GlobalUnlock.argtypes = [ctypes.c_void_p]
    kernel32.GlobalFree.restype = ctypes.c_void_p
    kernel32.GlobalFree.argtypes = [ctypes.c_void_p]
    kernel32.GlobalSize.restype = ctypes.c_size_t
    kernel32.GlobalSize.argtypes = [ctypes.c_void_p]
    user32.GetClipboardSequenceNumber.restype = ctypes.c_uint32
    user32.GetClipboardSequenceNumber.argtypes = []
    user32.CreateWindowExW.restype = ctypes.c_void_p
    user32.CreateWindowExW.argtypes = [
        ctypes.c_uint32, ctypes.c_wchar_p, ctypes.c_wchar_p, ctypes.c_uint32,
        ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
        ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p,
    ]
    user32.DestroyWindow.restype = ctypes.c_int
    user32.DestroyWindow.argtypes = [ctypes.c_void_p]

CF_DIB = 8
CF_UNICODETEXT = 13
GMEM_MOVEABLE = 0x0002

BI_RGB = 0
BI_BITFIELDS = 3
BITMAPINFOHEADER_SIZE = 40
# BITMAPINFOHEADER, V2, V3, V4 and V5. Windows hands a CF_DIBV5 source back
# through CF_DIB with its 124-byte header intact, so the reader must take
# all of them, not just the 40-byte one it writes.
_DIB_HEADER_SIZES = frozenset({40, 52, 56, 108, 124})
_BGR_MASKS = (0x00FF0000, 0x0000FF00, 0x000000FF)
_ALPHA_MASK = 0xFF000000

# The clipboard's sequence number when it was last sent to the Mac or written from it; None until
# then and after forget_sync. A switch sends the clipboard only when the number has moved since,
# so an unchanged screenshot is not pushed across on every switch.
_synced_sequence = None
_written_sequence = None
_LOCK = threading.RLock()

OPEN_RETRY_ATTEMPTS = 5
OPEN_RETRY_DELAY_SECONDS = 0.05


def dib_to_bgra(dib: bytes):
    """Decode a CF_DIB payload to (width, height, BGRA bytes, top-down rows),
    or None for anything this does not handle: 24/32-bit BI_RGB and 32-bit
    BI_BITFIELDS with the standard BGR(A) masks are what every screenshot
    tool, browser and Office app writes, so a palette, 16-bit or RLE DIB is
    rare enough to drop rather than decode. Never raises on junk."""
    try:
        if len(dib) < BITMAPINFOHEADER_SIZE:
            return None
        size, width, height, planes, bpp, compression = struct.unpack_from("<IiiHHI", dib, 0)
        clr_used = struct.unpack_from("<I", dib, 32)[0]
        if size not in _DIB_HEADER_SIZES or width <= 0 or height == 0 or bpp not in (24, 32):
            return None
        rows = abs(height)
        offset = size + clr_used * 4
        alpha_declared = False
        if compression == BI_BITFIELDS:
            if bpp != 32:
                return None
            masks = struct.unpack_from("<IIII" if size > BITMAPINFOHEADER_SIZE else "<III", dib, BITMAPINFOHEADER_SIZE)
            if size == BITMAPINFOHEADER_SIZE:
                offset += 12
            if tuple(masks[:3]) != _BGR_MASKS:
                return None
            alpha_declared = len(masks) == 4 and masks[3] == _ALPHA_MASK
        elif compression != BI_RGB:
            return None
        stride = (width * bpp // 8 + 3) & ~3
        if len(dib) < offset + stride * rows:
            return None
        row_bytes = width * bpp // 8
        lines = [dib[offset + i * stride: offset + i * stride + row_bytes] for i in range(rows)]
        if height > 0:
            lines.reverse()
        count = width * rows
        if bpp == 24:
            bgr = b"".join(lines)
            out = bytearray(count * 4)
            out[0::4] = bgr[0::3]
            out[1::4] = bgr[1::3]
            out[2::4] = bgr[2::3]
            out[3::4] = b"\xff" * count
        else:
            out = bytearray(b"".join(lines))
            # Under BI_RGB the fourth byte is officially reserved: GDI leaves
            # it zero, which read as alpha is a fully transparent image, while
            # Chrome and Paint.NET put real alpha there. All-zero means opaque;
            # anything else is taken as alpha, as those readers do.
            if not alpha_declared and out[3::4].count(0) == count:
                out[3::4] = b"\xff" * count
        return width, rows, bytes(out)
    except (struct.error, ValueError, OverflowError, MemoryError):
        return None


def bgra_to_dib(width: int, height: int, bgra: bytes) -> bytes:
    """Encode top-down BGRA rows as a 32-bit bottom-up BITMAPINFOHEADER DIB,
    the shape Windows' own tools put on the clipboard. Alpha rides in the
    fourth byte under BI_RGB, which the apps that care (Teams, Office,
    browsers) honour; a screenshot is opaque so nothing is lost either way."""
    stride = width * 4
    header = struct.pack(
        "<IiiHHIIiiII", BITMAPINFOHEADER_SIZE, width, height, 1, 32, BI_RGB, stride * height, 2835, 2835, 0, 0
    )
    rows = [bgra[i * stride: (i + 1) * stride] for i in range(height)]
    return header + b"".join(reversed(rows))


def _png_to_bgra(png: bytes):
    """Decode PNG to (width, height, BGRA top-down) with QImage, or None if it
    will not decode. QImage is safe off the GUI thread and needs no
    application object for the built-in PNG format."""
    from PySide6.QtGui import QImage

    image = QImage.fromData(png, "PNG")
    if image.isNull():
        return None
    image = image.convertToFormat(QImage.Format.Format_ARGB32)
    # ARGB32 is one native-endian uint32 per pixel, which on x86 lands in
    # memory as B, G, R, A: the DIB order, so the bytes are used as they are.
    return image.width(), image.height(), bytes(image.constBits())


def _bgra_to_png(width: int, height: int, bgra: bytes) -> Optional[bytes]:
    from PySide6.QtCore import QBuffer, QIODevice
    from PySide6.QtGui import QImage

    image = QImage(bgra, width, height, width * 4, QImage.Format.Format_ARGB32)
    buffer = QBuffer()
    buffer.open(QIODevice.OpenModeFlag.WriteOnly)
    if not image.save(buffer, "PNG"):
        return None
    return bytes(buffer.data())


def png_to_dib(png: bytes) -> Optional[bytes]:
    """PNG bytes to a CF_DIB payload, or None. Never raises."""
    try:
        decoded = _png_to_bgra(png)
    except Exception:
        LOGGER.exception("failed to decode a clipboard PNG")
        return None
    if decoded is None:
        return None
    width, height, bgra = decoded
    if width <= 0 or height <= 0 or len(bgra) != width * height * 4:
        return None
    return bgra_to_dib(width, height, bgra)


def dib_to_png(dib: bytes) -> Optional[bytes]:
    """CF_DIB payload to PNG bytes, or None. Never raises."""
    decoded = dib_to_bgra(dib)
    if decoded is None:
        return None
    try:
        return _bgra_to_png(*decoded)
    except Exception:
        LOGGER.exception("failed to encode the clipboard image as PNG")
        return None


def _open_clipboard(win32, attempts=OPEN_RETRY_ATTEMPTS, delay=OPEN_RETRY_DELAY_SECONDS, sleep=time.sleep, owner=None):
    """Try OpenClipboard(owner) up to `attempts` times, sleeping `delay`
    seconds between tries. Pure orchestration over an injected `win32` (the
    real user32 WinDLL, or a duck-typed fake) so the retry/backoff decision
    is testable without a real Windows clipboard."""
    for attempt in range(attempts):
        if win32.OpenClipboard(owner):
            return True
        if attempt + 1 < attempts:
            sleep(delay)
    return False


def _read_clipboard_text(win32, mem32):
    """Copy CF_UNICODETEXT out of the (already-open) clipboard, or return None
    if there is none. Caller holds the clipboard open."""
    handle = win32.GetClipboardData(CF_UNICODETEXT)
    if not handle:
        if win32.IsClipboardFormatAvailable(CF_UNICODETEXT):
            raise OSError("the clipboard text provider could not be read")
        return None
    pointer = mem32.GlobalLock(handle)
    if not pointer:
        raise OSError("the clipboard text could not be locked")
    try:
        text = ctypes.wstring_at(pointer)
    finally:
        mem32.GlobalUnlock(handle)
    return text if text else None


def _read_clipboard_dib(win32, mem32):
    """Copy the CF_DIB payload out of the (already-open) clipboard, or return
    None if there is no image. Windows synthesises CF_DIB from a CF_BITMAP
    or CF_DIBV5 source, so this one format covers them all."""
    handle = win32.GetClipboardData(CF_DIB)
    if not handle:
        if win32.IsClipboardFormatAvailable(CF_DIB):
            raise OSError("the clipboard image provider could not be read")
        return None
    size = mem32.GlobalSize(handle)
    if not size:
        raise OSError("the clipboard image size could not be read")
    pointer = mem32.GlobalLock(handle)
    if not pointer:
        raise OSError("the clipboard image could not be locked")
    try:
        return ctypes.string_at(pointer, size)
    finally:
        mem32.GlobalUnlock(handle)


def _put_clipboard_data(win32, mem32, clipboard_format, payload):
    """Hand `payload` to the (already-open, already-emptied) clipboard under
    `clipboard_format`. Returns True on success. On success, ownership of the
    allocated global memory handle passes to the system and must not be freed
    here; on failure it is freed before returning."""
    handle = mem32.GlobalAlloc(GMEM_MOVEABLE, len(payload))
    if not handle:
        return False
    pointer = mem32.GlobalLock(handle)
    if not pointer:
        mem32.GlobalFree(handle)
        return False
    try:
        ctypes.memmove(pointer, payload, len(payload))
    finally:
        mem32.GlobalUnlock(handle)
    if not win32.SetClipboardData(clipboard_format, handle):
        mem32.GlobalFree(handle)
        return False
    return True


def _get_contents(win32, mem32, attempts=OPEN_RETRY_ATTEMPTS, delay=OPEN_RETRY_DELAY_SECONDS, sleep=time.sleep,
                  strict=False):
    if not _open_clipboard(win32, attempts, delay, sleep):
        LOGGER.warning("could not open the clipboard for reading")
        if strict:
            raise OSError("could not open the clipboard for reading")
        return None, None
    failed = False
    try:
        try:
            text = _read_clipboard_text(win32, mem32)
        except Exception:
            failed = True
            LOGGER.exception("failed to read clipboard text")
            text = None
        try:
            dib = _read_clipboard_dib(win32, mem32)
        except Exception:
            failed = True
            LOGGER.exception("failed to read the clipboard image")
            dib = None
    finally:
        win32.CloseClipboard()
    # Converted after the clipboard is closed: a Retina-sized DIB takes
    # tens of milliseconds to encode and nothing else can use the clipboard
    # while it is held.
    png = dib_to_png(dib) if dib is not None else None
    if strict and failed and text is None and png is None:
        raise OSError("the clipboard provider could not be read")
    return text, png


def _set_contents(win32, mem32, text, png, attempts=OPEN_RETRY_ATTEMPTS, delay=OPEN_RETRY_DELAY_SECONDS, sleep=time.sleep, written=None):
    dib = png_to_dib(png) if png is not None else None
    if png is not None and dib is None:
        LOGGER.warning("inbound clipboard image did not decode; setting the text only")
    if text is None and dib is None:
        return False
    # EmptyClipboard with a NULL owner makes SetClipboardData fail. A message-only window
    # belongs to this worker even when the app has no visible panel, and never takes focus.
    owner = win32.CreateWindowExW(0, "STATIC", None, 0, 0, 0, 0, 0, -3, None, None, None)
    if not owner:
        LOGGER.warning("could not create the clipboard owner")
        return False
    try:
        if not _open_clipboard(win32, attempts, delay, sleep, owner=owner):
            LOGGER.warning("could not open the clipboard for writing")
            return False
        try:
            if not win32.EmptyClipboard():
                return False
            wrote = False
            if text is not None:
                # CF_UNICODETEXT is CRLF by convention; a Mac's LF alone reads as one
                # line in the older Windows apps.
                text = text.replace("\r\n", "\n").replace("\n", "\r\n")
                wrote |= _put_clipboard_data(win32, mem32, CF_UNICODETEXT, text.encode("utf-16-le") + b"\x00\x00")
            if dib is not None:
                wrote |= _put_clipboard_data(win32, mem32, CF_DIB, dib)
            if wrote and written is not None:
                written(win32.GetClipboardSequenceNumber())
            return wrote
        finally:
            win32.CloseClipboard()
    finally:
        win32.DestroyWindow(owner)


def get_contents(*, strict=False) -> Tuple[Optional[str], Optional[bytes]]:
    """(text, png) from the Windows clipboard, either None when absent, both
    None if this isn't Windows or reading failed for any reason. Never
    raises."""
    if not _IS_WINDOWS:
        if strict:
            raise OSError("the Windows clipboard is unavailable")
        return None, None
    try:
        with _LOCK:
            return _get_contents(user32, kernel32, strict=strict)
    except Exception as exc:
        LOGGER.exception("failed to read the Windows clipboard")
        if strict:
            raise OSError("failed to read the Windows clipboard") from exc
        return None, None


def read_contents() -> Tuple[Optional[str], Optional[bytes]]:
    """Like get_contents, but raise OSError on failure so a caller can retry an unchanged copy."""
    return get_contents(strict=True)


def changed_contents() -> Tuple[Optional[str], Optional[bytes]]:
    """get_contents(), or (None, None) when the clipboard has not changed since it was last sent
    to or written from the Mac. Either way the current contents count as sent from here on."""
    global _synced_sequence
    if not _IS_WINDOWS:
        return None, None
    sequence = user32.GetClipboardSequenceNumber()
    if sequence and sequence == _synced_sequence:
        return None, None
    text, png = get_contents()
    # Only what was read counts as sent: a failed read must not hold this clipboard back.
    if text is not None or png is not None:
        _synced_sequence = sequence
    return text, png


def change_stamp() -> Optional[int]:
    """A number that changes whenever the clipboard does, or None off Windows."""
    return user32.GetClipboardSequenceNumber() if _IS_WINDOWS else None


def forget_sync() -> None:
    """A new link: the Mac may have lost what it was sent, so the next switch sends again."""
    global _synced_sequence
    _synced_sequence = None


def write_stamp():
    """The last peer write, rather than a newer copy made after CloseClipboard."""
    return _written_sequence


def set_contents(text: Optional[str], png: Optional[bytes]) -> bool:
    """Replace the Windows clipboard with `text` and/or `png`. Returns True
    when at least one was set, False if this isn't Windows or the write
    failed. Never raises."""
    if not _IS_WINDOWS:
        return False
    def remember(sequence):
        global _synced_sequence, _written_sequence
        _synced_sequence = _written_sequence = sequence
    try:
        with _LOCK:
            return _set_contents(user32, kernel32, text, png, written=remember)
    except Exception:
        LOGGER.exception("failed to set the Windows clipboard")
        return False