openclaw/deskflow
1
0
Fork 0
Code Issues Pull Requests Actions 17 Packages Projects Releases Wiki Activity

chore: move doc dir to docs

Browse Source
This commit is contained in:
sithlord48
2026-02-22 15:51:20 -05:00
committed by Chris Rizzitello
parent 5ea8874583
commit dfae2aaf20
12 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/CMakeLists.txt Normal file
View File

@ -0,0 +1,26 @@
# SPDX-FileCopyrightText: (C) 2019 - 2025 Chris Rizzitello <sithlord48@gmail.com>
# SPDX-License-Identifier: MIT
find_package(Doxygen QUIET)
option(BUILD_USER_DOCS "Build and install user documentation" ${DOXYGEN_FOUND})
option(BUILD_DEV_DOCS "Build and install developer documentation" OFF)
if (DOXYGEN_FOUND)
# Generic Doxygen options
set(DOXYGEN_EXTRACT_ALL YES)
set(DOXYGEN_EXTRACT_STATIC YES)
set(DOXYGEN_STRIP_FROM_PATH ${CMAKE_SOURCE_DIR})
set(DOXYGEN_QUIET YES)
set(DOXYGEN_PROJECT_NAME ${CMAKE_PROJECT_PROPER_NAME})
set(DOXYGEN_PROJECT_ICON "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png")
set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/deskflow-logo.png")
if (BUILD_USER_DOCS)
add_subdirectory(user)
endif()
if (BUILD_DEV_DOCS)
add_subdirectory(dev)
endif()
else()
message(STATUS "Doxygen not found, skipping docs build")
endif()

BIN
docs/deskflow-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.4 KiB

22
docs/dev/CMakeLists.txt Normal file
View File

@ -0,0 +1,22 @@
# SPDX-FileCopyrightText: (C) 2025 Chris Rizzitello <sithlord48@gmail.com>
# SPDX-License-Identifier: MIT
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE mainpage.md)
set(DOXYGEN_EXCLUDE_PATTERNS "*unittests/*")
set(DOXYGEN_DOT_GRAPH_MAX_NODES 100)
# Files used to make our documents
doxygen_add_docs(dev-docs
${CMAKE_CURRENT_SOURCE_DIR}
${CMAKE_SOURCE_DIR}/src
COMMENT "Generating developer documentation" ALL)
# HACK Only these will show in your IDE
target_sources(dev-docs PRIVATE
mainpage.md
contributing.md
build.md
protocol_reference.md
)
# missing install target is intended generate a local copy

110
docs/dev/build.md Normal file
View File

@ -0,0 +1,110 @@
# Building Deskflow
To build Deskflow you will a minimum of:
- [cmake] 3.24+
- [Qt] 6.7.0+
- [openssl] 3.0+
- [libportal] 0.8+ (linux, bsd)
- [libei] 1.3+ (linux, bsd)
- [google_test] ^
> ^ Will be fetched if not found on the host system.
By default a build of Deskflow will:
- The GUI application `deskflow`
- The Core application `deskflow-core`
- Documentation if [doxygen] was found on your system
- Tests that will be run as part of the build process
## Configuration
Deskflow supports the following CMake options:
| Option | Description | Default Value | Additional requirements |
:-------------------------:|:---------------------------------------:|:------------------:|:-----------------------:|
| BUILD_USER_DOCS | Build user documentation | DOXYGEN_FOUND | `Doxygen` |
| BUILD_DEV_DOCS | Build development documentation | OFF | `Doxygen` |
| BUILD_INSTALLER | Build installers/packages | ON | |
| BUILD_TESTS | Build unit tests and legacy tests | ON | `gtest`|
| BUILD_X11_SUPPORT | Build X11 backend (Linux and BSD only) | ON | `x11 libs`|
| BUILD_OSX_BUNDLE | Build an app bundle (macOS only) | ON | |
| ENABLE_COVERAGE | Enable test coverage | OFF | `gcov` |
| SKIP_BUILD_TESTS | Skip running of tests at build time | OFF | |
| VCPKG_QT | Build Qt w/ vcpkg (Windows only) | OFF | |
| CLEAN_TRS | Remove obsolete strings from tr files | OFF | |
| APPLE_CODESIGN_DEV | Apple codesign cert ID for development | Not set | |
Example cmake configuration:
`cmake -S. -Bbuild -DCMAKE_INSTALL_PREFIX=<INSTALLPREFIX>`
### Windows Configuration
It is recommended to use vcpkg to install the dependencies. The first time you configure Deskflow, all dependencies other than Qt will be built. If you don't want to use vcpkg, you must manually setup the dependencies. However, that will not be covered by this document.
#### Windows and Qt
There are two ways you can install [Qt] on Windows (vcpkg or Qt online installer). The default configuration expects you to use the Qt online installer. You should not install Qt in both ways, as having both can cause some weird things to happen, like Qt getting libs from one install and plugins from the other. When switching between them, remove the previous install first.
##### System Qt
1. Download and install the [Qt] online installer from their website.
2. Add the path of Qt's cmake files to your system path (skipping this may require you provide this path to cmake via `Qt6_DIR` at configure time).
- Often: `C:\Qt\<version>\<msvcinfo>\lib\cmake`
3. Add the path of Qt's binary tools to your system path.
- Often: `C:\Qt\<version>\<msvcinfo>\bin`
##### vcpkg managed Qt
1. Add the option `-DVCPKG_QT=ON` to your cmake configuration command (i.e `cmake -S. -Bbuild -DVCPKG_QT=ON ...`) or if using an IDE, look for the option where you configure the project, have the IDE run cmake again.
2. Once the configuration starts, you should see a lot more packages vcpkg will build. Building Qt takes a long time (potentially hours), so go find something else to do for a while.
3. If you want to use the system Qt again, you must delete the `vcpkg.json` generated in the project root and the `build` folder and reconfigure the project from scratch.
### macOS codesign
The code signing option `APPLE_CODESIGN_DEV` is only for local development and not intended for distributed bundles.
Signing for local development and signing for the distribution bundle must be different because of development entitlements which are unlikely to be safe for use in production. It is impractical (i.e. very slow and cumbersome) to use the distribution bundle for local development. When developing locally, the app bundle is partial and does not contain dependencies and uses external libs, e.g. installed with Homebrew; the entitlements allow those external libs to be loaded which is not allowed by default.
For development codesign:
1. Install Xcode
2. Go to Settings -> Accounts
3. Add your account (requires a free Apple Developer ID)
4. Manage certificates -> Add -> Apple Development
5. To get your ID, run: `security find-identity -v -p codesigning login.keychain-db`
6. Pass the ID to CMake, e.g. `-DAPPLE_CODESIGN_DEV=Apple Development: bob@exmaple.com (KLGSJHLFXY)`
7. Configure and build
8. To verify, run: `codesign -d -r- build/bin/Deskflow.app`
## Build
After configuring you should be able to run make to build all targets.
`cmake --build build`
## Install
To test installation run `DESTDIR=<installDIR> cmake --install build` to install into `<installDir>/<CMAKE_INSTALL_PREFIX>`
Running `cmake --install build` will install to the `CMAKE_INSTALL_PREFIX`
## Making Deskflow packages
Deskflow can generate several packages using `cpack`.
To generate packages build the `package` or `package_source` target.
Example: ` cmake --build build --target package package_source` would generate both package and package source packages.
Deskflow can generate several package types depending on the system.
Archive-based packages should work on all platforms. On Linux deb and rpm info is set up, Flatpaks can be generated from the included file in deploy/linux and a `PKGBUILD` for Arch linux is generated in the build folder. On macos a dmg file will be created and signed. For windows WiX can be used to create an installer.
[Qt]:https://www.qt.io
[doxygen]:http://www.stack.nl/~dimitri/doxygen/
[cmake]:https://cmake.org/
[openssl]:https://www.openssl.org/
[google_test]:https://github.com/google/googletest
[libei]:https://gitlab.freedesktop.org/libinput/libei
[libportal]:https://github.com/flatpak/libportal

13
docs/dev/contributing.md Normal file
View File

@ -0,0 +1,13 @@
# Contributing to Deskflow {#contributing_guide}
Thanks for your interest in contributing to Deskflow! We welcome all kinds of contributions — bug reports, feature suggestions, documentation improvements, and code.
## Read the Full Guidelines
To keep this repository clean and contribution-friendly, we've outlined our full contributing guidelines on the Deskflow Wiki:
👉 [How to Contribute to Deskflow](https://github.com/deskflow/deskflow/wiki/Contributing)
Please take a moment to read through the page before opening an issue or submitting a pull request.
Thanks again for helping make Deskflow better!

55
docs/dev/mainpage.md Normal file
View File

@ -0,0 +1,55 @@
**Deskflow** is a free and open source keyboard and mouse sharing app.
Use the keyboard, mouse, or trackpad of one computer to control nearby computers,
and work seamlessly between them.
Deskflow acts as a software KVM (without video) that allows you to:
- Share keyboard and mouse input across multiple computers
- Synchronize clipboard content between machines
- Work seamlessly across different operating systems (Windows, macOS, Linux, BSD)
Deskflow software consists of a **server** (primary computer) that shares its input devices and **clients** (secondary computers) that receive and execute the input commands over a TCP network connection.
### Architecture Overview
Deskflow is built with a modular, cross-platform architecture:
```
┌─────────────────┐ Network Protocol ┌─────────────────┐
│ Server App │◄──────────────────────►│ Client App │
│ │ (Port 24800) │ (Windows) │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ Screen │ │ │ │ Screen │ │
│ │ Platform │ │ │ │ Platform │ │
│ │ Layer │ │ │ │ Layer │ │
│ └─────────────┘ │ │ └─────────────┘ │
└─────────────────┘ └─────────────────┘
┌───────┐ ┌───────┐
│ Keyb. │ │ Mouse │
└───────┘ └───────┘
┌─────────────────┐
│ Client App │
│ (macOS) │
│ ┌─────────────┐ │
│ │ Screen │ │
│ │ Platform │ │
│ │ Layer │ │
│ └─────────────┘ │
└─────────────────┘
┌─────────────────┐
│ Client App │
│ (Custom) │
│ ┌─────────────┐ │
│ │ Screen │ │
│ │ Platform │ │
│ │ Layer │ │
│ └─────────────┘ │
└─────────────────┘
```
### More info
For more info, see our [Wiki](https://github.com/deskflow/deskflow/wiki).
Check out our [Building guide](build.md) or our general @ref contributing_guide "Contributing section". We also have a detailed [Protocol Reference](protocol_reference.md).

532
docs/dev/protocol_reference.md Normal file
View File

@ -0,0 +1,532 @@
# Protocol Reference {#protocol_reference}
This document provides a comprehensive reference for the Deskflow network protocol. It is the primary source of information for developers implementing Deskflow clients or extending the protocol.
## Protocol Overview
The Deskflow protocol enables keyboard and mouse sharing between multiple computers over a TCP network connection. The protocol uses two distinct sets of terminology to describe the roles of the computers involved:
- **Network Role (Client/Server)**: This describes the connection architecture.
- **Server**: The machine that listens for incoming TCP connections.
- **Client**: The machine that initiates the TCP connection to the server.
- **Input Control Role (Primary/Secondary)**: This describes the flow of keyboard and mouse events.
- **Primary**: The computer whose keyboard and mouse are currently being used to control other computers.
- **Secondary**: A computer that is being controlled by the Primary's keyboard and mouse.
In a typical setup, the Primary computer (the one whose keyboard and mouse are shared) also acts as the Server. However, the protocol is flexible and allows these roles to be separate. For example, a Primary machine can act as a Client to connect to a Secondary machine that is configured as a Server. This can be useful for navigating restrictive network environments like firewalls.
Throughout the documentation, message direction is often described using the Primary/Secondary roles to clarify the input control flow, while Client/Server roles are used when discussing the underlying network connection.
### Key Implementation Files
- **[ProtocolTypes.h](@ref ProtocolTypes.h)** – Complete protocol specification
- **[ProtocolUtil.h](@ref ProtocolUtil.h)** – Message formatting utilities
- **[ClientInfo](@ref ClientInfo)** – Screen information structure
The protocol is designed to be:
- Lightweight and efficient
- Cross-platform compatible
- Extensible for new features
- Backward compatible with older versions
## Protocol Architecture
```
┌─────────────────┐ TCP/IP Network ┌─────────────────┐
│ Primary │◄────────────────────►│ Secondary │
│ (Server) │ Port 24800 │ (Client) │
│ │ │ │
│ • Shares input │ │ • Receives input│
│ • Manages layout│ │ • Reports info │
│ • Coordinates │ │ • Executes cmds │
└─────────────────┘ └─────────────────┘
```
The protocol operates over a standard TCP connection on port 24800. In protocol versions 1.4 and later, TLS encryption is supported for secure communications.
## Protocol State Machine
The client's connection lifecycle is defined by five primary states:
```
┌──────────────────┐
│ START │
└────────┬─────────┘
│
▼
┌────────┴─────────┐
│ DISCONNECTED │
│ (Initial & │◄───────────────────┐
│ Final State) │ │
└────────┬─────────┘ │
│ │
▼ │
┌──────────────────┐ │
│ CONNECTING │ TCP Failure │
│ (TCP handshake) ├───────────────────►┤
└────────┬─────────┘ │
│ │
TCP Success │ │
│ │
▼ │
┌──────────────────┐ │
│ HANDSHAKE │ Version Mismatch │
│ (Hello/HelloBk) ├───────────────────►┤
└────────┬─────────┘ │
│ │
OK │ │
│ │
▼ │
┌──────────────────┐ │
│ CONNECTED │ CCLOSE (close) │
┌───►│ (Authenticated ├───────────────────►┤
│ │ but inactive) │ │
│ └────────┬─────────┘ │
│ │ │
COUT │ CINN │ │
(Leave) │ (Enter)│ │
│ ▼ │
│ ┌──────────────────┐ │
└────┤ ACTIVE │ CCLOSE (close) │
│ (Receiving all ├───────────────────►┘
┌───►│ input events) │
│ └────────┬─────────┘
│ │
│ ▼
│ ┌──────────────────┐
└────┤ PROCESS EVENT │
└──────────────────┘
```
### State Descriptions
1. **Disconnected**: Initial and final state. No connection to @ref Server.
2. **Connecting**: @ref TCPSocket connection attempt in progress.
- Initiating @ref TCPSocket connection.
- On successful TCP connection, moves to the `Handshake` state.
- If TCP connection fails (timeout, RST packet), returns to `Disconnected`.
3. **Handshake**: Protocol version negotiation and authentication.
- @ref Server sends @ref kMsgHello with protocol version information.
- @ref Client responds with @ref kMsgHelloBack including version and screen name.
- @ref Server validates the client's message.
- Success transitions to `Connected`, failure sends @ref kMsgEIncompatible error.
4. **Connected**: Authenticated but not receiving input events.
- @ref Client must respond to @ref kMsgCKeepAlive messages from the @ref Server.
- Receiving @ref kMsgCEnter message transitions to `Active`.
5. **Active**: Receiving and processing input events from @ref Server.
- Receiving @ref kMsgCLeave message transitions back to `Connected`.
- Receiving @ref kMsgCClose message transitions to `Disconnected`.
## Message Categories
The protocol organizes messages into logical categories:
| Category | Prefix | Purpose | Examples |
|----------|---------|----------|-----------|
| **[Handshake](@ref protocol_handshake)** | None | Connection setup | @ref kMsgHello, @ref kMsgHelloBack |
| **[Commands](@ref protocol_commands)** | `C` | Screen control | @ref kMsgCEnter, @ref kMsgCLeave, @ref kMsgCKeepAlive |
| **[Data](@ref protocol_data)** | `D` | Input events | @ref kMsgDKeyDown, @ref kMsgDMouseMove, @ref kMsgCClipboard, @ref kMsgDClipboard |
| **[Queries](@ref protocol_queries)** | `Q` | Information requests | @ref kMsgQInfo |
| **[Errors](@ref protocol_errors)** | `E` | Error notifications | @ref kMsgEIncompatible, @ref kMsgEBusy |
## Message Reference Table
This table lists all protocol messages in alphabetical order. For a typical sequence of messages, see the [Typical Control Flow](#typical-control-flow) section.
| Message | Constant | Category | Direction | Purpose | Constraints | Protocol Version |
|---|---|---|---|---|---|---|
| [**CALV**](@ref kMsgCKeepAlive) | @ref kMsgCKeepAlive | Command | Both | Keep-alive | [MsgSize](#constraint-protocol-max-message-length), [KeepAlive](#constraint-keep-alive) | 1.3+ |
| [**CBYE**](@ref kMsgCClose) | @ref kMsgCClose | Command | Server→Client | Close connection | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**CCLP**](@ref kMsgCClipboard) | @ref kMsgCClipboard | Command | Both | Clipboard ownership notification | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**CIAK**](@ref kMsgCInfoAck) | @ref kMsgCInfoAck | Command | Server→Client | Acknowledge info message | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**CINN**](@ref kMsgCEnter) | @ref kMsgCEnter | Command | Server→Client | Enter screen | [MsgSize](#constraint-protocol-max-message-length), [ScreenEntrySync](#constraint-screen-entry-sync) | 1.0+ |
| [**CNOP**](@ref kMsgCNoop) | @ref kMsgCNoop | Command | Both | No operation | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**COUT**](@ref kMsgCLeave) | @ref kMsgCLeave | Command | Server→Client | Leave screen | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**CROP**](@ref kMsgCResetOptions) | @ref kMsgCResetOptions | Command | Server→Client | Reset options to defaults | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**CSEC**](@ref kMsgCScreenSaver) | @ref kMsgCScreenSaver | Command | Server→Client | Screen saver control | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DCLP**](@ref kMsgDClipboard) | @ref kMsgDClipboard | Data | Both | Clipboard data | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DDRG**](@ref kMsgDDragInfo) | @ref kMsgDDragInfo | Data | Server→Client | Drag file info | [MsgSize](#constraint-protocol-max-message-length), [ListSize](#constraint-max-list) | 1.5+ |
| [**DFTR**](@ref kMsgDFileTransfer) | @ref kMsgDFileTransfer | Data | Both | File transfer data | [MsgSize](#constraint-protocol-max-message-length) | 1.5+ |
| [**DINF**](@ref kMsgDInfo) | @ref kMsgDInfo | Data | Client→Server | Screen information | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DKDL**](@ref kMsgDKeyDownLang) | @ref kMsgDKeyDownLang | Data | Server→Client | Key down with language | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.8+ |
| [**DKDN**](@ref kMsgDKeyDown) | @ref kMsgDKeyDown | Data | Server→Client | Key down | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.1+ |
| [**DKDN**](@ref kMsgDKeyDown1_0) | @ref kMsgDKeyDown1_0 | Data | Server→Client | Key down (legacy) | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.0 |
| [**DKRP**](@ref kMsgDKeyRepeat) | @ref kMsgDKeyRepeat | Data | Server→Client | Key repeat | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.1+ |
| [**DKRP**](@ref kMsgDKeyRepeat1_0) | @ref kMsgDKeyRepeat1_0 | Data | Server→Client | Key repeat (legacy) | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.0 |
| [**DKUP**](@ref kMsgDKeyUp) | @ref kMsgDKeyUp | Data | Server→Client | Key up | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.1+ |
| [**DKUP**](@ref kMsgDKeyUp1_0) | @ref kMsgDKeyUp1_0 | Data | Server→Client | Key up (legacy) | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.0 |
| [**DMDN**](@ref kMsgDMouseDown) | @ref kMsgDMouseDown | Data | Server→Client | Mouse down | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DMMV**](@ref kMsgDMouseMove) | @ref kMsgDMouseMove | Data | Server→Client | Mouse move (absolute) | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DMRM**](@ref kMsgDMouseRelMove) | @ref kMsgDMouseRelMove | Data | Server→Client | Mouse move (relative) | [MsgSize](#constraint-protocol-max-message-length) | 1.2+ |
| [**DMUP**](@ref kMsgDMouseUp) | @ref kMsgDMouseUp | Data | Server→Client | Mouse up | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DMWM**](@ref kMsgDMouseWheel) | @ref kMsgDMouseWheel | Data | Server→Client | Mouse wheel | [MsgSize](#constraint-protocol-max-message-length) | 1.3+ |
| [**DMWM**](@ref kMsgDMouseWheel1_0) | @ref kMsgDMouseWheel1_0 | Data | Server→Client | Mouse wheel (legacy) | [MsgSize](#constraint-protocol-max-message-length) | 1.0-1.2 |
| [**DSOP**](@ref kMsgDSetOptions) | @ref kMsgDSetOptions | Data | Server→Client | Set options | [MsgSize](#constraint-protocol-max-message-length), [ListSize](#constraint-max-list) | 1.0+ |
| [**EBAD**](@ref kMsgEBad) | @ref kMsgEBad | Error | Server→Client | Protocol violation | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**EBSY**](@ref kMsgEBusy) | @ref kMsgEBusy | Error | Server→Client | Server busy | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**EICV**](@ref kMsgEIncompatible) | @ref kMsgEIncompatible | Error | Server→Client | Incompatible version | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**EUNK**](@ref kMsgEUnknown) | @ref kMsgEUnknown | Error | Server→Client | Unknown client | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**Hello**](@ref kMsgHello) | @ref kMsgHello | Handshake | Server→Client | Protocol identification | [HelloSize](#constraint-max-hello), [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**HelloArgs**](@ref kMsgHelloArgs) | @ref kMsgHelloArgs | Handshake | Internal | Hello message construction | [HelloSize](#constraint-max-hello), [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**HelloBack**](@ref kMsgHelloBack) | @ref kMsgHelloBack | Handshake | Client→Server | Client identification | [HelloSize](#constraint-max-hello), [MsgSize](#constraint-protocol-max-message-length), [HandshakeTimeout](#constraint-handshake-timeout) | 1.0+ |
| [**HelloBackArgs**](@ref kMsgHelloBackArgs) | @ref kMsgHelloBackArgs | Handshake | Internal | HelloBack message construction | [HelloSize](#constraint-max-hello), [MsgSize](#constraint-protocol-max-message-length), [HandshakeTimeout](#constraint-handshake-timeout) | 1.0+ |
| [**LSYN**](@ref kMsgDLanguageSynchronisation) | @ref kMsgDLanguageSynchronisation | Data | Server→Client | Language synchronization | [MsgSize](#constraint-protocol-max-message-length) | 1.8+ |
| [**QINF**](@ref kMsgQInfo) | @ref kMsgQInfo | Query | Server→Client | Request screen info | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**SECN**](@ref kMsgDSecureInputNotification) | @ref kMsgDSecureInputNotification | Data | Server→Client | Secure input notification | [MsgSize](#constraint-protocol-max-message-length) | 1.7+ |
## Typical Control Flow
<a id="typical-control-flow"></a>
A typical control flow is as follows:
1. **Handshake**: The server and client exchange `Hello` and `HelloBack` messages to agree on a protocol version.
2. **Information Exchange**: The server requests client information with `QINF`, and the client responds with `DINF`.
3. **Options**: The server sends `DSOP` to configure client options.
4. **Keep-Alive**: The server and client periodically exchange `CALV` messages to maintain the connection.
5. **Screen Entry**: The server sends `CINN` to grant control to the client.
6. **Input Events**: The server sends a stream of input event messages (e.g., `DMMV`, `DMDN`, `DKDN`).
7. **Screen Leave**: The server sends `COUT` to revoke control from the client.
8. **Connection Close**: The server sends `CCLOSE` to terminate the connection.
## Protocol Constraints
To ensure security, stability, and compatibility, the protocol enforces strict constraints:
<a id="constraint-max-msg"></a>
### Message and Data Size Limits
**Maximum Message Size:**
<a id="constraint-protocol-max-message-length"></a>**4,194,304 bytes (4 MB)** — @ref PROTOCOL_MAX_MESSAGE_LENGTH
Maximum total size of any single, length-prefixed data packet
Defined in Protocol Limits
**Maximum List Size:**
<a id="constraint-max-list"></a>**1,048,576 elements** — @ref PROTOCOL_MAX_LIST_LENGTH
Maximum number of items in a list/vector within a message
Defined in Protocol Limits
**Maximum Hello Size:**
<a id="constraint-max-hello"></a>**1,024 bytes** — @ref kMaxHelloLength
Maximum size of the initial Connection Handshake message
Defined in Protocol Limits
<a id="constraint-tls"></a>
### TLS Handshake and Security (Protocol v1.4+)
When encryption is enabled, the protocol follows this sequence:
1. Standard TCP connection established
2. TLS handshake performed over TCP socket
3. Protocol handshake begins only after TLS session is established
- **Implementation Details**:
- The client initiates a standard TCP connection, then the (private) SecureSocket::handleTCPConnected method is called, which begins the TLS handshake
- **Certificate Validation**:
- Client implementations **must** validate the server's certificate
- The reference implementation checks that the public key is RSA or DSA and that the key length is at least 2048 bits
### Key Code and Modifier Mapping
A modifier (modifier mask) represents the state of modifier keys (like Shift, Control, Alt, and Command) on a keyboard. It is a binary code (like 0000 0110) where each bit corresponds to a specific modifier key.
**Key-Up/Key-Down Strategy:**
- <a id="constraint-keymap"></a>Client must use the @ref KeyButton (physical key) to track pressed keys, as the @ref KeyID (virtual key) can change based on modifier state
- This strategy is described in the documentation for @ref kMsgDKeyDown
**Modifier Remapping:**
- The server can command clients to remap modifier keys via the @ref kMsgDSetOptions message
- The client processes the @ref kMsgDSetOptions message and updates the modifier translation table accordingly
## Timing and Synchronization
<a id="constraint-keep-alive"></a>
### Keep-Alive Mechanism (Protocol v1.3+)
**Server-Side Behavior:**
- The server sends kMsgCKeepAlive messages every 3.0 seconds (defined by @ref kKeepAliveRate)
- This timer is implemented in @ref ClientProxy1_3::addHeartbeatTimer in the @ref ClientProxy1_3 class
**Client-Side Behavior:**
- Upon receiving a kMsgCKeepAlive message, the client must immediately send a kMsgCKeepAlive message back
- The client maintains a timeout that is reset each time any message is received
- If no message is received for 9.0 seconds (3 × @ref kKeepAliveRate), client must disconnect
- This is handled by the (private) ServerProxy::handleKeepAliveAlarm method
<a id="constraint-screen-entry-sync"></a>
### Synchronization on Screen Entry
- The @ref kMsgCEnter (Enter Screen) message includes the current modifier state
- Client must synchronize their local modifier state with this mask
<a id="constraint-handshake-timeout"></a>
### Handshake Timeout
- Server allows **30 seconds** for handshake completion
- If client fails to send valid @ref kMsgHelloBack within this time, connection is closed
- When a new client connects, the server creates a temporary @ref ClientProxyUnknown to handle the version handshake
- A one-shot timer is started for 30 seconds
- If the client fails to respond in time, the @ref protocol_errors function is triggered, the connection is logged as unresponsive, and the socket is closed
## Version Compatibility
| Version | Release Date | Project | Features | Compatibility |
|---------|----------|---------------|----------|---------------|
| **1.0** | May 2001 | Synergy | Basic keyboard/mouse sharing (@ref kMsgDKeyDown, @ref kMsgDMouseMove) | All versions |
| **1.1** | Apr 2002 | Synergy | Physical key codes (@ref KeyButton) | 1.1+ |
| **1.2** | Jan 2006 | Synergy | Relative mouse movement | 1.2+ |
| **1.3** | May 2006 | Synergy | Keep-alive (@ref kMsgCKeepAlive), horizontal scroll (@ref kMsgDMouseWheel) | 1.3+ |
| **1.4** | Nov 2012 | Synergy | Encryption support (@ref SecureSocket) | 1.4+ |
| **1.5** | Sep 2013 | Synergy | File transfer | 1.5+ |
| **1.6** | Jan 2014 | Synergy | Clipboard streaming | 1.6+ |
| **1.7** | Nov 2021 | Synergy | Secure input notifications | 1.7+ |
| **1.8** | Jun 2025 | Synergy | Language synchronization | 1.8+ |
### Version Migration Guide
When implementing a client that supports multiple protocol versions:
1. **Version Negotiation**: During handshake, client should advertise highest supported version
2. **Feature Detection**: Check server's version in `Hello` message before using version-specific features
3. **Fallback Mechanism**: Be prepared to operate with only features available in the negotiated version
4. **Graceful Degradation**: If server supports a lower version than client's minimum, handle `EIncompatible` error gracefully
## Implementation Examples
### Connection Lifecycle
```cpp
// 1. Connect to server
std::string server_ip = "192.168.1.100";
connect(server_ip, 24800);
// 2. Receive Hello from server
auto hello = receive_message();
std::string server_version, server_name;
parse_hello(hello, &server_version, &server_name);
// 3. Send HelloBack to server
std::string client_version = "1.8";
std::string client_name = "MyClient";
send_hello_back(client_version, client_name);
// 4. Enter main message loop
bool connected = true;
while (connected) {
auto message = receive_message();
handle_message(message);
}
```
### Message Handling
```cpp
void handle_message(const Message& msg) {
switch (msg.type) {
case "CINN": // Enter screen
handle_enter(msg.x, msg.y, msg.sequence, msg.modifiers);
break;
case "DKDN": // Key down
handle_key_down(msg.key_id, msg.modifiers, msg.key_button);
break;
case "DMMV": // Mouse move
handle_mouse_move(msg.x, msg.y);
break;
// ... handle other message types
}
}
```
### Complete Message Exchange Sequence
Below is a typical message exchange sequence for a client connecting to a server:
```
Client Server
| |
| | Server starts listening on port 24800
| |
| TCP SYN |
| ───────────────────────────────────► |
| |
| ◄─────────────────────────────────── |
| TCP SYN+ACK |
| |
| TCP ACK |
| ───────────────────────────────────► |
| | TCP connection established
| |
| ◄─────────────────────────────────── |
| "Deskflow" + version (1.8) | Hello message
| |
| "Deskflow" + version + name |
| ───────────────────────────────────► | HelloBack message
| |
| ◄─────────────────────────────────── |
| "QINF" | Query screen info
| |
| "DINF" + screen dimensions |
| ───────────────────────────────────► | Report screen info
| |
| ◄─────────────────────────────────── |
| "DSOP" + options | Set options
| |
| ◄─────────────────────────────────── |
| "CALV" | Keep-alive
| |
| "CALV" |
| ───────────────────────────────────► | Keep-alive response
| |
| ◄─────────────────────────────────── |
| "CINN" + x + y + seq + mask | Enter screen
| |
| ◄─────────────────────────────────── |
| "DMMV" + x + y | Mouse move
| |
| ◄─────────────────────────────────── |
| "DMDN" + button | Mouse down
| |
| ◄─────────────────────────────────── |
| "DMUP" + button | Mouse up
| |
| ◄─────────────────────────────────── |
| "DKDN" + key + mask + button | Key down
| |
| ◄─────────────────────────────────── |
| "DKUP" + key + mask + button | Key up
| |
| ◄─────────────────────────────────── |
| "COUT" | Leave screen
| |
| ◄─────────────────────────────────── |
| "CCLOSE" | Close connection
| |
| TCP FIN |
| ◄─────────────────────────────────── |
| |
| TCP FIN+ACK |
| ───────────────────────────────────► |
| | Connection closed
```
**Legend:**
- Hello message: @ref kMsgHello
- HelloBack message: @ref kMsgHelloBack
- Query screen info: @ref kMsgQInfo
- Report screen info: @ref kMsgDInfo
- Set options: @ref kMsgDSetOptions
- Keep-alive: @ref kMsgCKeepAlive
- Enter screen: @ref kMsgCEnter
- Mouse move: @ref kMsgDMouseMove
- Mouse down: @ref kMsgDMouseDown
- Mouse up: @ref kMsgDMouseUp
- Key down: @ref kMsgDKeyDown
- Key up: @ref kMsgDKeyUp
- Leave screen: @ref kMsgCLeave
- Close connection: @ref kMsgCClose
## Debugging and Troubleshooting
### Common Issues
1. **Version Mismatch**: Check protocol version negotiation
2. **Message Format**: Validate message structure and parameters
3. **Byte Order**: Ensure network byte order for multi-byte integers
4. **Keep-Alive**: Implement proper keep-alive response
5. **Screen Info**: Send accurate screen dimensions and mouse position
### Debug Tools
- **Wireshark**: Capture and analyze network traffic
- **Protocol Logs**: Enable verbose logging in Deskflow
- **Message Validation**: Check message format against specification
## Platform-Specific Implementations
For platform-specific implementation details, refer to:
- @ref ProtocolTypes.h – Complete protocol specification
- @ref ProtocolUtil.h – Message formatting utilities
## Implementation Checklist
### Basic Client Implementation
- **Connection Management**
- TCP connection to server port 24800
- Protocol handshake (Hello/HelloBack)
- Version negotiation
- Keep-alive handling
- **Message Processing**
- Message parsing and validation
- Command message handling (Enter/Leave)
- Input event processing (keyboard/mouse)
- Error handling and recovery
- **Screen Management**
- Screen information reporting (DINF)
- Resolution change detection
- Mouse cursor positioning
- **Input Synthesis**
- Keyboard event injection
- Mouse event injection
- Modifier key synchronization
### Advanced Features
- **Clipboard Synchronization**
- Clipboard grab notifications
- Data transfer (@ref kMsgDClipboard - text, images, HTML)
- Streaming for large data (v1.6+)
- **File Transfer** (v1.5+)
- Drag-and-drop initiation
- Chunked file transfer
- Progress tracking
- **Security Features**
- TLS/SSL encryption (v1.4+)
- Secure input notifications (v1.7+)
- Input validation and limits
## Reference Implementation
The @ref ServerProxy class provides a reference implementation demonstrating:
- Basic protocol handling
- Message parsing and generation
- Connection management
- Input event processing
## Contributing
When extending the protocol:
1. **Maintain Compatibility**: New features should be backward compatible
2. **Update Documentation**: Document new messages and parameters
3. **Version Increment**: Bump minor version for new features
4. **Test Thoroughly**: Verify with existing clients and servers
## Support and Resources
- @ref ProtocolTypes.h – Complete protocol specification
- @ref ProtocolUtil.h – Message formatting utilities
---
*This documentation is generated from the source code and is always up-to-date with the latest protocol implementation.*

20
docs/user/CMakeLists.txt Normal file
View File

@ -0,0 +1,20 @@
# SPDX-FileCopyrightText: (C) 2025 Chris Rizzitello <sithlord48@gmail.com>
# SPDX-License-Identifier: MIT
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE mainpage.md)
# Files used to make our documents
# User facing documents will not include doxy comments in source code
doxygen_add_docs(user-docs ${CMAKE_CURRENT_SOURCE_DIR} COMMENT "Generating user documentation" ALL)
# HACK Only these will show in your IDE
target_sources(user-docs PRIVATE
mainpage.md
configuration.md
)
install(
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html"
DESTINATION ${CMAKE_INSTALL_DOCDIR}
COMPONENT deskflow_user_docs
)

813
docs/user/configuration.md Normal file
View File

@ -0,0 +1,813 @@
# GUI Config
Deskflow will automatically figure out where to save settings and other files.
## Search paths
Deskflow will look for settings in several places depending on your operating system.
The search order for a setting file depends on your operating system
### Linux
1. `<XDG_CONFIG_HOME>/Deskflow/Deskflow.conf`
2. `~/.config/Deskflow/Deskflow.conf`
3. `/etc/Deskflow/Deskflow.conf`
A new settings file will be created in the user path if no settings file is found.
The path of the settings file will be used as the base for all other config files.
### macOS
1. `~/Library/Deskflow/Deskflow.conf`
2. `/Library/Deskflow/Deskflow.conf`
A new settings file will be created in the user path if no settings file is found.
The path of the settings file will be used as the base for all other config files.
### Windows
1. `<install-path>/settings/Deskflow.conf`
2. Windows Registry `HKCU\Software\Deskflow\Deskflow`
Windows will save to the install dir if settings are loaded from there. If not, it saves any other config files in: `C:\ProgramData\Deskflow\`
When using settings from the install dir, the service mode will not be available.
## Valid GUI Keys
The GUI config file contains several sections.
Each section is formatted the same.
Option-value pairs are only written if the value is not the default value.
```
[section]
option=value
```
### Client
This section contains options used when in client mode.
It will begin with `[client]`
| Option | Valid Values | Description |
|:------------------|:------------------:|:-----------|
| languageSync | `true` or `false` | Sync to server language [default: true] |
| remoteHost | `IP` or `hostname` | The remote host(s) to connect to. Use a comma separated list when you want to try several hosts |
| yScrollScale | Double 0.1 - 10.0 | Vertical mouse scrolling will be scaled by this amount on the client [default: 1.0] |
| xScrollScale | Double 0.1 - 10.0 | Horizontal mouse scrolling will be scaled by this amount on the client [default: 1.0] |
| invertYScroll | `true` or `false` | Invert vertical scroll on this client [default: false] |
| invertXScroll | `true` or `false` | Invert horizontal scroll on this client [default: false] |
| xdpRestoreToken | UUID | Restore token provided by XDG portals |
### Core
This section contains general options it will begin with `[core]`
|Option | Valid Values|Description|
|:--------------|:-----------:|:-----------|
| coreMode | `0` or `1` or `2` | The mode to start in 0: None, 1: Client, 2: Server [default: 0]|
| display | int | The XWindow display to use [default: autodetected] |
| interface | IP Address | Preferred IP to use for network communication. By default the server board casts on any available address |
| lastVersion | M.m.p.t | The version last run used for checking for updates |
| port | port # | Port to use when connecting [default: 24800 |
| preventSleep | `true` or `false` | Prevent sleep when Deskflow is active [default: false] |
| processMode | `1` or `0` | The mode we use to start the process Service or Desktop |
| computerName | string | Name used to identify the computer [default: machine's hostname] |
| useHooks | `true` or `false` | If Windows uses hooks or not [default: true] |
| language | 639 language | The language to display the GUI in [default: en] |
| wlClipboard | `true` or `false` | When true the wl-clipboard backend will be enabled [default: false] |
### Daemon
This section contains options used by the daemon on windows it will begin with `[daemon]`
|Option | Valid Values|Description|
|:----------|:-----------:|:-----------|
| command | Filename | The filename of the binary the daemon. This binary exists in the same path as the deskflow GUI |
| elevate | `true` or `false` | Elevate the daemon app [default: true unless portable mode ] |
| logFile | Filepath | Filepath of the daemon log |
| logLevel | valid log Level, | Log Level |
### GUI
This section contains options used by the GUI it will begin with `[gui]`
|Option | Valid Values |Description|
|:-------------------------------|:-----------------:|:-----------|
| autoHide | `true` or `false` | When true the app will hide itself on start up [default: false] |
| enableUpdateCheck | `true` or `false` | When true check the update URL to see if a new version was released on start up [default: false] |
| closeReminder | `true` or `false` | Used to track if we have shown the reminder that when you close the app it remain running in the background [default: true]|
| closeToTray | `true` or `false` | When `true` the gui will run in the systemTray when its closed [default: true] |
| logExpanded | `true` or `false` | Should the log section of the GUI be opened [default: false] |
| symbolicTrayIcon | `true` or `false` | When true use the monocolor (symbolic) icon false uses a colorful icon for the tray [default: true] |
| windowGeometry | QRect | Geometry of the window used to restore the window geometry after exiting the app |
| showGenericClientFailureDialog | `true` or `false` | When `true` client connection errors will not show popup error messages [default: true] |
| shownFirstConnectedMessage | `true` or `false` | When `true` GUI has shown the user the message for connecting the first time [default: false] |
| shownServerFirstStartMessage | `true` or `false` | When `true` GUI has shown the user the Deskflow server is now running message [default: false] |
| shownVerionInTitle | `true` or `false` | When `true` GUI will include the version in the window title [default: false] |
| startCoreWithGui | `true` or `false` | When true the Core will be started with the GUI. It is set to the Core's state on exit. |
| updateCheckUrl | URL | The URL to use when checking for a new version number, it should return a version [default: https://api.deskflow.org/version]|
### Log
This section contains options used by the application logging it will begin with `[log]`
|Option | Valid Values |Description|
|:---------|:-----------------:|:-----------|
| file | Filepath | The file to write the log into |
| level | Valid log level | Log level to use |
| toFile | `true` or `false` | When true the log will be written to the value of the `file` option |
| guiDebug | `true` or `false` | When true the log will show the Gui's internal debug messages |
### Security
This section contains options used by the application security it will begin with `[security]`
|Option | Valid Values |Description|
|:----------------------|:-----------------:|:-----------|
| checkPeerFingerprints | `true` or `false` | When true peers will have their fingerprints confirmed by the user and stored [default: true] |
| certificate | Filepath | Path to the certificate to use to encrypt messages.|
| keySize | `2048` OR `4096` | Size of the TLS key to use [default: 2048]|
| tlsEnabled | `true` or `false` | Are we using TLS encryption when communicating [default: true].|
### Server
This section contains options used when in server mode it will begin with `[server]`
|Option | Valid Values |Description|
|:-------------------|:-----------------:|:-----------|
| externalConfig | `true` or `false` | When true use the external config path |
| externalConfigFile | Filepath | Path the server config file if it does not exist the GUI will it generated based on the `internalConfig` section.|
### InternalConfig
This section contains options used when in server mode it will begin with `[internalConfig]`
block of a server config file as seen below. This section is used by the GUI to generate a server configuration
```
[internalConfig]
clipboardSharing=true
clipboardSharingSize=@Variant(\0\0\0\x84\0\0\0\0\0\0<\0)
defaultLockToScreenState=false
disableLockToScreen=false
hasHeartbeat=false
hasSwitchDelay=false
hasSwitchDoubleTap=false
heartbeat=5000
hotkeys\1\actions\1\activeOnRelease=false
hotkeys\1\actions\1\hasScreens=true
hotkeys\1\actions\1\keys\1\key=83
hotkeys\1\actions\1\keys\size=1
hotkeys\1\actions\1\lockCursorToScreen=0
hotkeys\1\actions\1\restartServer=false
hotkeys\1\actions\1\switchInDirection=0
hotkeys\1\actions\1\switchScreenName=void
hotkeys\1\actions\1\type=0
hotkeys\1\actions\1\typeScreenNames\size=0
hotkeys\1\actions\size=1
hotkeys\1\keys\1\key=83
hotkeys\1\keys\size=1
hotkeys\size=1
numColumns=5
numRows=3
protocol=1
relativeMouseMoves=false
screens\1\name=
screens\10\aliasArray\size=0
screens\10\fixArray\1\fix=false
screens\10\fixArray\2\fix=false
screens\10\fixArray\3\fix=false
screens\10\fixArray\4\fix=false
screens\10\fixArray\size=4
screens\10\modifierArray\1\modifier=0
screens\10\modifierArray\2\modifier=1
screens\10\modifierArray\3\modifier=2
screens\10\modifierArray\4\modifier=3
screens\10\modifierArray\5\modifier=4
screens\10\modifierArray\6\modifier=5
screens\10\modifierArray\size=6
screens\10\name=null
screens\10\switchCornerArray\1\switchCorner=false
screens\10\switchCornerArray\2\switchCorner=false
screens\10\switchCornerArray\3\switchCorner=false
screens\10\switchCornerArray\4\switchCorner=false
screens\10\switchCornerArray\size=4
screens\10\switchCornerSize=0
screens\11\name=
screens\12\name=
screens\13\name=
screens\14\name=
screens\15\name=
screens\2\name=
screens\3\name=
screens\4\name=
screens\5\name=
screens\6\name=
screens\7\aliasArray\size=0
screens\7\fixArray\1\fix=false
screens\7\fixArray\2\fix=false
screens\7\fixArray\3\fix=false
screens\7\fixArray\4\fix=false
screens\7\fixArray\size=4
screens\7\modifierArray\1\modifier=0
screens\7\modifierArray\2\modifier=1
screens\7\modifierArray\3\modifier=2
screens\7\modifierArray\4\modifier=3
screens\7\modifierArray\5\modifier=4
screens\7\modifierArray\6\modifier=5
screens\7\modifierArray\size=6
screens\7\name=void
screens\7\switchCornerArray\1\switchCorner=false
screens\7\switchCornerArray\2\switchCorner=false
screens\7\switchCornerArray\3\switchCorner=false
screens\7\switchCornerArray\4\switchCorner=false
screens\7\switchCornerArray\size=4
screens\7\switchCornerSize=0
screens\8\aliasArray\size=0
screens\8\fixArray\1\fix=false
screens\8\fixArray\2\fix=false
screens\8\fixArray\3\fix=false
screens\8\fixArray\4\fix=false
screens\8\fixArray\size=4
screens\8\modifierArray\1\modifier=0
screens\8\modifierArray\2\modifier=1
screens\8\modifierArray\3\modifier=2
screens\8\modifierArray\4\modifier=3
screens\8\modifierArray\5\modifier=4
screens\8\modifierArray\6\modifier=5
screens\8\modifierArray\size=6
screens\8\name=chris-Precision-5570
screens\8\switchCornerArray\1\switchCorner=false
screens\8\switchCornerArray\2\switchCorner=false
screens\8\switchCornerArray\3\switchCorner=false
screens\8\switchCornerArray\4\switchCorner=false
screens\8\switchCornerArray\size=4
screens\8\switchCornerSize=0
screens\9\aliasArray\size=0
screens\9\fixArray\1\fix=false
screens\9\fixArray\2\fix=false
screens\9\fixArray\3\fix=false
screens\9\fixArray\4\fix=false
screens\9\fixArray\size=4
screens\9\modifierArray\1\modifier=0
screens\9\modifierArray\2\modifier=1
screens\9\modifierArray\3\modifier=2
screens\9\modifierArray\4\modifier=3
screens\9\modifierArray\5\modifier=4
screens\9\modifierArray\6\modifier=5
screens\9\modifierArray\size=6
screens\9\name=abyss.lan
screens\9\switchCornerArray\1\switchCorner=false
screens\9\switchCornerArray\2\switchCorner=false
screens\9\switchCornerArray\3\switchCorner=false
screens\9\switchCornerArray\4\switchCorner=false
screens\9\switchCornerArray\size=4
screens\9\switchCornerSize=0
screens\size=15
switchCornerArray\1\switchCorner=false
switchCornerArray\2\switchCorner=false
switchCornerArray\3\switchCorner=false
switchCornerArray\4\switchCorner=false
switchCornerArray\size=4
switchCornerSize=0
switchDelay=250
switchDoubleTap=250
win32KeepForeground=false
```
# Server Config
The `deskflow-server` command accepts the `-c` or `--config` option, which takes one argument,
the path to a server configuration file. When using the GUI the `internalConfig` section of the GUI settings will be exported as the server configuration.
The configuration file is plain text and case-sensitive. The file is broken into sections, and each section has the form:
```
section: ''name''
''arg'' = ''value''
end
```
Comments are introduced by ''#'' and continue to the end of the line. ''name'' must be one of the following:
* ''screens''
* ''aliases''
* ''links''
* ''options''
The file is parsed top to bottom and names cannot be used before they've been defined in the <code>screens</code> or <code>aliases</code> sections. So the <code>links</code> and <code>aliases</code> must appear after the <code>screens</code> and <code>links</code> cannot refer to aliases unless the <code>aliases</code> appear before the <code>links</code>.
### The screens section
''args'' is a list of computer names, one name per line, each followed by a colon. Names are arbitrary strings but they must be unique. The hostname of each computer is recommended. (This is the computer's network name on win32 and the name reported by the program hostname on Unix and OS X. Note that OS X may append .local to the name you gave your computer; e.g. somehost.local.) There must be a computer name for the server and each client. Each computer can specify a number of options. Options have the form name = value and are listed one per line after the computer name.
```
section: screens
moe:
larry:
halfDuplexCapsLock = true
halfDuplexNumLock = true
curly:
meta = alt
end
```
This declares three computers named ''moe'', ''larry'', and ''curly''. Computer ''larry'' has half-duplex ''Caps Lock'' and ''Num Lock'' keys (see below) and computer ''curly'' converts the ''Meta'' modifier key to the ''Alt'' modifier key.
#### screen options
A computer can have the following options:
|Option | Valid Values| Description|
|:----------|:-----------:|:-----------|
|halfDuplexCapsLock| `true` or `false` | This computer has a ''Caps Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Caps Lock'' acts strangely on all computers then you may need to set this option to true on the server. If it acts strangely on one computer then that computer may need the option set to true.|
|halfDuplexNumLock | `true` or `false` | This computer has a ''Num Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Num Lock'' acts strangely on all computers then you may need to set this option to true on the server. If it acts strangely on one computer then that computer may need the option set to true.|
|halfDuplexScrollLock| `true` or `false`| This computer has a ''Scroll Lock'' key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If ''Scroll Lock'' acts strangely on all computers then you may need to set this option to true on the server. If it acts strangely on one computer then that computer may need the option set to true.|
|xtestIsXineramaUnaware| `true` or `false`| This option works around a bug in the XTest extension when used in combination with Xinerama. It affects X11 clients only. Not all versions of the XTest extension are aware of the Xinerama extension. As a result, they do not move the mouse correctly when using multiple Xinerama screens. This option is currently ''true'' by default. If you know your XTest extension is Xinerama aware then set this option to ''false''.|
|preserveFocus| `true` or `false` | When true don't drop focus when switching computers
|switchCorners| corners |See <a href="#switch-corners">switchCorners</a> below.|
|switchCornerSize | integer | see switchCornerSize below.|
|shift | shift ctrl alt meta super none | Map the server's shift modifer to different key on a client computer|
|ctrl | shift ctrl alt meta super none | Map the server's ctrl modifer to different key on a client computer|
|alt | shift ctrl alt meta super none | Map the server's alt modifer to different key on a client computer|
|meta| shift ctrl alt meta super none | Map the server's meta modifer to different key on a client computer|
|super| shift ctrl alt meta super none | Map the server's super modifer to different key on a client computer|
### aliases section
''args'' is a list of computer names just like in the ''screens'' section except each computer is followed by a list of aliases, one per line, not followed by a colon. An ''alias'' is a computer name and must be unique. When searching for computers each alias is equivalent to the computer name it aliases. So a client can connect using its canonical computer name or any of its aliases.
```
section: aliases
larry:
larry.stooges.com
curly:
shemp
end
```
Computer ''larry'' is also known as ''larry.stooges.com'' and can connect as either name. Computer ''curly'' is also known as ''shemp'' (hey, it's just an example).
### links secion
''args'' is a list of computer names just like in the ''screens'' section except each computer is followed by a list of links, one per line. Each link has the form:
```
{left|right|up|down}[<range>] = name[<range>]
```
A link indicates which computer is adjacent in the given direction.
Each side of a link can specify a range which defines a portion of an edge. A range on the direction is the portion of edge you can leave from while a range on the computer is the portion of edge you'll enter into. Ranges are optional and default to the entire edge. All ranges on a particular direction of a particular computer must not overlap.
A ''range'' is written as <code>(start,end)</code>. Both ''start'' and ''end'' are percentages in the range 0 to 100, inclusive. The start must be less than the end. 0 is the left or top of an edge and 100 is the right or bottom.
```
section: links
moe:
right = larry
up(50,100) = curly(0,50)
larry:
left = moe
up(0,50) = curly(50,100)
curly:
down(0,50) = moe
down(50,100) = larry(0,50)
end
```
This indicates that computer ''larry'' is to the right of computer ''moe'' (so moving the cursor off the right edge of ''moe'' would make it appear at the left edge of ''larry''), the left half of curly is above the right half of ''moe'', ''moe'' is to the left of ''larry'' (edges are not necessarily symmetric so you have to provide both directions), the right half of curly is above the left half of ''larry'', all of ''moe'' is below the left half of ''curly'', and the left half of ''larry'' is below the right half of ''curly''.
Note that links do not have to be symmetrical; for instance, here the edge between ''moe'' and ''curly'' maps to different ranges depending on if you're going up or down. In fact links don't have to be bidirectional. You can configure the right of ''moe'' to go to ''larry'' without a link from the left of ''larry'' to ''moe''. It's possible to configure a computer with no outgoing links; the cursor will get stuck on that computer unless you have a hot key configured to switch off of that computer.
### options section
''args'' is a list of lines of the form <code>name = value</code>. These set the global options.
```
section: options
protocol = barrier
heartbeat = 5000
switchDelay = 500
end
```
#### List of options allowed in options section
| Options | Value Values| Description|
|:--------|:-----------:|:-----------|
|protocol | barrier or synergy| The protocol to use when saying hello to clients. Can be set to barrier or synergy. If not set barrier is used as the default |
|heartbeat| integer (N) | The server will expect each client to send a message no less than every `N` milliseconds. If no message arrives from a client within `3N` seconds the server forces that client to disconnect. If deskflow fails to detect clients disconnecting while the server is sleeping or vice versa, try using this option. |
|switchCorners | none top-left top-right bottom-left bottom-right left right top bottom all | Deskflow won't switch computers when the mouse reaches the edge of the computer if it's in a listed corner. The size of all corners is given by the `switchCornerSize` option. The first name in the list is one of the above names and defines the initial set of corners. Subsequent names are prefixed with + or - to add the corner to or remove the corner from the set, respectively. For example: `all -left +top-left` starts will all corners, removes the left corners (top and bottom) then adds the top-left back in, resulting in the top-left, bottom-left and bottom-right corners.|
|switchCornerSize | integer (N) | Sets the size of all corners in pixels. The cursor must be within `N` pixels of the corner to be considered to be in the corner.|
|switchDelay | integer| Deskflow won't switch computers when the mouse reaches edge of a computer unless it stays on the edge for `N` milliseconds. This helps prevent unintentional switching when working near an edge.|
|switchDoubleTap| integer(N) | Deskflow won't switch computers when the mouse reaches the edge of a computer unless it's moved away from the edge and then back to the edge within `N` milliseconds. With the option you have to quickly tap the edge twice to switch. This helps prevent unintentional switching when working near the edge.|
|screenSaverSync| `true` or `false`| ''Note: Removed in v1.14.1'' If set to ''false'' then Deskflow won't synchronize screen savers. Client screen savers will start according to their individual configurations. The server screen saver won't start if there is input, even if that input is directed toward a client computer.|
|relativeMouseMoves| `true` or `false`| If set to ''true'' then secondary computers move the mouse using relative rather than absolute mouse moves when and only when the cursor is locked to the computer (by ''Scroll Lock'' or a configured hot key). This is intended to make Deskflow work better with certain games. If set to ''false'' or not set then all mouse moves are absolute.|
|clipboardSharing| `true` or `false`|If set to ''true'' then clipboard sharing will be enabled and the ''clipboardSharingSize'' setting will be used. If set to false, then clipboard sharing will be disabled and the the ''clipboardSharingSize'' setting will be ignored.|
|clipboardSharingSize| integer (N)| Deskflow will send a maximum of `N` kilobytes of clipboard data to another computer when the mouse transitions to that computer.|
|win32KeepForeground | `true` or `false`| If set to ''true'' (the default), Deskflow will grab the foreground focus on a Windows server (thereby putting all other windows in the background) upon switching to a client. If set to ''false'', it will leave the currently foreground window in the foreground. Deskflow grabs the focus to avoid issues with other apps interfering with Deskflow's ability to read the hardware inputs. |
|keystroke(key) | actions | Binds the ''key'' combination key to the given ''actions''. ''key'' is an optional list of modifiers (''shift'', ''control'', ''alt'', ''meta'' or ''super'') optionally followed by a character or a key name, all separated by + (plus signs). You must have either modifiers or a character/key name or both. See below for `valid key names` and `actions`. Keyboard hot keys are handled while the cursor any computer. Separate actions can be assigned to press and release.|
|mousebutton(button) | actions| Binds the modifier and mouse button combination ''button'' to the given ''actions''. ''button'' is an optional list of modifiers (''shift'', ''control'', ''alt'', ''meta'' or ''super'') followed by a button number. The primary button (the left button for right handed users) is button 1, the middle button is 2, etc. Actions can be found below. Mouse button actions are not handled while the cursor is on the server. You cannot use these to perform an action while on the server. Separate actions can be assigned to press and release.|
You can use both the ''switchDelay'' and ''switchDoubleTap'' options at the same time. Deskflow will switch when either requirement is satisfied.
##### Actions
Actions are two lists of individual actions separated by commas. The two lists are separated by a '';'' (semicolon). Either list can be empty and if the second list is empty then the semicolon is optional. The first list lists actions to take when the condition becomes true (e.g. the hot key or mouse button is pressed) and the second lists actions to take when the condition becomes false (e.g. the hot key or button is released). The condition becoming true is called activation and becoming false is called deactivation. Allowed individual actions are:
* `keystroke(key[,computers])`
* `keyDown(key[,computers])`
* `keyUp(key[,computers])`
: Synthesizes the modifiers and key given in ''key'' which has the same form as described in the ''keystroke'' option. If given, ''computers'' lists the computer or computers to direct the event to, regardless of the active computer. If not given then the event is directed to the active computer only.
: ''keyDown'' synthesizes a key press and ''keyUp'' synthesizes a key release. ''keystroke'' synthesizes a key press on activation and a release on deactivation and is equivalent to a ''keyDown'' on activation and ''keyUp'' on deactivation.
: ''computers'' is either ''*'' (asterisk) to indicate all computers or a '':'' (colon) separated list of computer names. (Note that the computer name must have already been encountered in the configuration file so you'll probably want to put ''actions'' at the bottom of the file.)
* `mousebutton(button)`
* `mouseDown(button)`
* `mouseUp(button)`
: Synthesizes the modifiers and mouse button given in ''button'' which has the same form as described in the ''mousebutton'' option.
: ''mouseDown'' synthesizes a mouse press and ''mouseUp'' synthesizes a mouse release. ''mousebutton'' synthesizes a mouse press on activation and a release on deactivation and is equivalent to a ''mouseDown'' on activation and ''mouseUp'' on deactivation.
* `lockCursorToScreen(mode)`
: Locks the cursor to or unlocks the cursor from the active computer. ''mode'' can be ''off'' to unlock the cursor, ''on'' to lock the cursor, or ''toggle'' to toggle the current state. The default is ''toggle''. If the configuration has no ''lockCursorToScreen'' action and ''Scroll Lock'' is not used as a hot key then ''Scroll Lock'' toggles cursor locking.
* `switchToScreen(computerName)`
: Jump to computer with name or alias ''computerName''.
* `switchInDirection(dir)`
: Switch to the computer in the direction ''dir'', which may be one of ''left'', ''right'', ''up'' or ''down''.
* `switchToNextScreen()`
: Cycle to the next computer in the configuration order. If at the last computer, cycles back to the first computer.
##### Keynames
Valid key names are:
<details><summary>Valid Key Names</summary>
* AppMail
* AppMedia
* AppUser1
* AppUser2
* AudioDown
* AudioMute
* AudioNext
* AudioPlay
* AudioPrev
* AudioStop
* AudioUp
* BackSpace
* Begin
* Break
* Cancel
* CapsLock
* Clear
* Delete
* Down
* Eject
* End
* Escape
* Execute
* F1
* F2
* F3
* F4
* F5
* F6
* F7
* F8
* F9
* F10
* F11
* F12
* F13
* F14
* F15
* F16
* F17
* F18
* F19
* F20
* F21
* F22
* F23
* F24
* F25
* F26
* F27
* F28
* F29
* F30
* F31
* F32
* F33
* F34
* F35
* Find
* Help
* Home
* Insert
* KP_0
* KP_1
* KP_2
* KP_3
* KP_4
* KP_5
* KP_6
* KP_7
* KP_8
* KP_9
* KP_Add
* KP_Begin
* KP_Decimal
* KP_Delete
* KP_Divide
* KP_Down
* KP_End
* KP_Enter
* KP_Equal
* KP_F1
* KP_F2
* KP_F3
* KP_F4
* KP_Home
* KP_Insert
* KP_Left
* KP_Multiply
* KP_PageDown
* KP_PageUp
* KP_Right
* KP_Separator
* KP_Space
* KP_Subtract
* KP_Tab
* KP_Up
* Left
* LeftTab
* Linefeed
* Menu
* NumLock
* PageDown
* PageUp
* Pause
* Print
* Redo
* Return
* Right
* ScrollLock
* Select
* Sleep
* Space
* SysReq
* Tab
* Undo
* Up
* WWWBack
* WWWFavorites
* WWWForward
* WWWHome
* WWWRefresh
* WWWSearch
* WWWStop
* Space
* Exclaim
* DoubleQuote
* Number
* Dollar
* Percent
* Ampersand
* Apostrophe
* ParenthesisL
* ParenthesisR
* Asterisk
* Plus
* Comma
* Minus
* Period
* Slash
* Colon
* Semicolon
* Less
* Equal
* Greater
* Question
* At
* BracketL
* Backslash
* BracketR
* Circumflex
* Underscore
* Grave
* BraceL
* Bar
* BraceR
* Tilde
</details>
Additionally, a name of the form `\uXXXX` where ''XXXX'' is a hexadecimal number is interpreted as a unicode character code. Key and modifier names are case-insensitive. Keys that don't exist on the keyboard or in the default keyboard layout will not work.
### Example textual configuration file
This example comes from doc/deskflow-basic.conf
```
# sample deskflow configuration file
#
# comments begin with the # character and continue to the end of
# line. comments may appear anywhere the syntax permits.
# +-------+ +--------+ +---------+
# |Laptop | |Desktop1| |iMac |
# | | | | | |
# +-------+ +--------+ +---------+
section: screens
# three hosts named: Laptop, Desktop1, and iMac
# These are the nice names of the hosts to make it easy to write the config file
# The aliases section below contain the "actual" names of the hosts (their hostnames)
Laptop:
Desktop1:
iMac:
end
section: links
# iMac is to the right of Desktop1
# Laptop is to the left of Desktop1
Desktop1:
right(0,100) = iMac # the numbers in parentheses indicate the percentage of the computer's edge to be considered active for switching)
left = Laptop
shift = shift (shift, alt, super, meta can be mapped to any of the others)
# Desktop1 is to the right of Laptop
Laptop:
right = Desktop1
# Desktop1 is to the left of iMac
iMac:
left = Desktop1
end
section: aliases
# The "real" name of iMac is John-Smiths-iMac-3.local.
# If we wanted we could remove this alias and instead use John-Smiths-iMac-3.local everywhere iMac is above.
# Hopefully it should be easy to see why using an alias is nicer
iMac:
John-Smiths-iMac-3.local
end
```
#### Cursor Wrapping
The text config allows computers to be wrapped around. For example, with two machines (a server and a client), the mouse can go off the right of the server onto the left side of the client, then off the right side of the client back onto the left side of server. This config also uses ''Ctrl''+''Super''+(''left arrow''/''right arrow'') to switch between machines on keypress.
```
# Physical monitor arrangement, with machine names as used by Deskflow.
# +----------+----------+
# | syn-serv | syn-cli |
# | | |
# +----------+----------+
section: screens
syn-serv:
syn-cli:
end
section: links
syn-serv:
left = syn-cli # "wrapping" arrangement
right = syn-cli # "normal" arrangement
syn-cli:
left = syn-serv # "normal"
right = syn-serv # "wrapping"
end
section: options
keystroke(control+super+right) = switchInDirection(right) # Switch computers on keypress
<!-- keystroke(control+super+left) = switchInDirection(left) -->
end
```
### AltGr key
The following screen config allows the mapping for ''Alt'' to ''AltGr''. Although this may not work, see [https://github.com/deskflow/deskflow-core/issues/4411 bug #4411].
```
section: screens
client1:
altgr = alt # mapping to fix AltGr key not working on windows clients (e.g. @-Symbol etc.).
end
```
See also: the man page for ''deskflow-core''.
### Stacked Example
Stack one computer on top of another's.
```
# +-------+
# | curly |
# | |
# +-------+
# +-------+ +-------+
# | moe | | larry |
# | | | |
# +-------+ +-------+
section: screens
# three hosts named: moe, larry, and curly
moe:
larry:
curly:
end
section: links
# larry is to the right of moe and curly is above moe.
moe:
right = larry
up = curly
# moe is to the left of larry and curly is above larry.
larry:
left = moe
up = curly
# larry is below curly.
curly:
down = larry
end
section: aliases
# curly is also known as shemp
curly:
shemp
end
```
### Horizontal Example
Align all computers horizontally.
```
# +-------+ +-------+ +-------+
# | moe | | larry | | curly |
# | | | | | |
# +-------+ +-------+ +-------+
section: screens
# three hosts named: moe, larry, and curly
moe:
larry:
curly:
end
section: links
# curly is to the right of larry and moe is to the left of larry.
larry:
right = curly
left = moe
# larry is to the right of moe.
moe:
right = larry
# larry is to the left of curly.
curly:
left = larry
end
```
### Span Example
Span one computer across the two other computers.
```
# +-------+ +-------+
# | curly | | curly |
# | | | |
# +-------+ +-------+
# +-------+ +-------+
# | moe | | larry |
# | | | |
# +-------+ +-------+
section: screens
# three hosts named: moe, larry, and curly
moe:
larry:
curly:
end
section: links
# larry is to the right of moe and curly is above moe.
moe:
right = larry
up = curly
# moe is to the left of larry and curly is above larry.
larry:
left = moe
up = curly
# larry is below curly.
curly:
down = larry
end
```

14
docs/user/mainpage.md Normal file
View File

@ -0,0 +1,14 @@
**Deskflow** is a free and open source keyboard and mouse sharing app.
Use the keyboard, mouse, or trackpad of one computer to control nearby computers,
and work seamlessly between them.
## Configuration
Our [Configuration] page has example configurations
## More info
For more info, see our [Wiki](https://github.com/deskflow/deskflow/wiki).
[Configuration]:configuration.md