Architecture

FreeRDP is organized as a layered library stack. Application frontends such as xfreerdp and sdl-freerdp sit on top of libfreerdp (the protocol core), which in turn relies on libwinpr for OS-abstraction primitives. Virtual channel plugins extend the protocol with optional capabilities.

Major Components

libfreerdp — the protocol core

libfreerdp implements the full RDP protocol stack: negotiation, capability exchange, input/output, graphics pipeline, licensing, and channel multiplexing. Every public API lives behind the FREERDP_API visibility macro and is declared in include/freerdp/.Key internal modules (libfreerdp/core/):

Module	Responsibility
`connection.c`	Connection state machine
`nego.c`	Protocol/security negotiation
`nla.c`	Network Level Authentication (CredSSP)
`mcs.c`	MCS channel multiplexing
`fastpath.c`	Fast-path input/output
`channels.c`	Virtual channel dispatch
`codecs.c`	Codec context lifecycle
`transport.c`	TCP / TLS transport

libwinpr — WinAPI portability layer

libwinpr provides Windows API compatibility on Linux, macOS, and BSD: threading primitives (HANDLE, wThread), SSPI for NTLM/Kerberos, stream utilities (wStream), logging (wLog), and more. FreeRDP code uses WinPR types exclusively so that the same source compiles on every platform.

Virtual channel plugins

Each virtual channel is a loadable plugin that follows either the static virtual channel (SVC) or dynamic virtual channel (DVC) plugin ABI. Plugins live under channels/ and are built as separate shared libraries (e.g. libfreerdp-client-cliprdr.so). See Channels for a full list.

Client frontends

Frontends are thin wrappers that create a freerdp instance, populate settings, register callbacks, and run an event loop:

xfreerdp — X11 frontend (client/X11/)
sdl-freerdp — SDL2/SDL3 cross-platform frontend (client/SDL/)
wfreerdp — Windows native frontend (client/Windows/)
libfreerdp-client — Shared client helper library used by all frontends

Server / peer side

libfreerdp also contains a server-side peer API. A freerdp_peer struct (include/freerdp/peer.h) exposes callbacks such as Capabilities, PostConnect, Activate, and Logon that a server application implements. The shadow server (server/shadow/) is a full reference implementation.

Connection Lifecycle

The diagram below shows the sequence a client goes through from freerdp_new() to an active session.

 freerdp_new()
      │
      ▼
 freerdp_context_new()          ← allocates rdpContext, rdpSettings, rdpCodecs …
      │
      ▼
 [set settings / register callbacks]
      │
      ▼
 freerdp_connect()
      │
      ├─► TCP connect            (transport.c)
      │
      ├─► X.224 / TPKT handshake (tpkt.c / tpdu.c)
      │
      ├─► Protocol negotiation   (nego.c)
      │       RDP / TLS / NLA
      │
      ├─► TLS handshake          (transport.c + OpenSSL/MbedTLS)
      │
      ├─► NLA / CredSSP          (nla.c)  [if negotiated]
      │       NTLM or Kerberos SPNEGO
      │
      ├─► MCS Connect / GCC      (mcs.c / gcc.c)
      │       client ↔ server capability data blocks
      │
      ├─► Capability exchange    (capabilities.c)
      │
      ├─► License                (license.c)
      │
      ├─► PreConnect callback    (instance->PreConnect)
      │
      ├─► Channel initialization (channels.c)
      │       LoadChannels callback
      │
      ├─► PostConnect callback   (instance->PostConnect)
      │
      └─► Active session  ◄──────────────────────────────────┐
               │                                              │
               ├─ freerdp_check_event_handles()  ─────── Input/Update loop
               ├─ instance->ReceiveChannelData()
               └─ instance->SendChannelData()

TCP connect

freerdp_connect() resolves the hostname from FreeRDP_ServerHostname and opens a TCP connection to FreeRDP_ServerPort (default 3389).

Protocol negotiation

nego.c sends a Connection Request with the requested security protocol (PROTOCOL_TLS, PROTOCOL_HYBRID for NLA, etc.) and waits for the server’s Connection Confirm.

TLS handshake

The raw TCP socket is upgraded to TLS. Certificate verification fires the VerifyCertificateEx or VerifyX509Certificate callback.

NLA / CredSSP

When NLA is negotiated, nla.c performs a CredSSP handshake carrying SPNEGO tokens (NTLM or Kerberos). The AuthenticateEx callback supplies credentials.

Capability exchange

MCS and GCC data blocks carry client/server capability sets. FreeRDP creates three rdpSettings instances: initial config, remote peer settings, and merged settings.

Active session

After PostConnect returns TRUE, the connection is active. The client drives the event loop with freerdp_check_event_handles() and queries connection state with freerdp_get_state() / freerdp_is_active_state().

The `rdpContext` Structure

rdpContext (include/freerdp/freerdp.h) is the central hub that ties every subsystem together. It is allocated by freerdp_context_new() and lives for the duration of the connection.

struct rdp_context
{
    freerdp*         instance;    /* back-link to the freerdp instance        */
    freerdp_peer*    peer;        /* set on the server side only              */
    BOOL             ServerMode;  /* TRUE when acting as a server             */
    UINT32           LastError;   /* last error code                          */

    /* --- protocol subsystems (all owned by rdpRdp) --- */
    rdpRdp*          rdp;         /* core RDP state machine                   */
    rdpGdi*          gdi;         /* software GDI rendering surface           */
    rdpCache*        cache;       /* bitmap / glyph / brush cache             */
    rdpChannels*     channels;    /* virtual channel manager                  */
    rdpGraphics*     graphics;    /* graphics orders / bitmaps                */
    rdpInput*        input;       /* keyboard + pointer input                 */
    rdpUpdate*       update;      /* display update callbacks                 */
    rdpSettings*     settings;    /* merged connection settings               */
    rdpMetrics*      metrics;     /* bandwidth / round-trip metrics           */
    rdpCodecs*       codecs;      /* codec contexts (RFX, H.264, …)           */
    rdpAutoDetect*   autodetect;  /* bandwidth auto-detection                 */

    wLog*            log;         /* per-context WLog logger                  */
};

Client applications typically extend rdpContext by setting instance->ContextSize to sizeof(MyClientContext), where MyClientContext embeds rdpContext as its first field:

typedef struct
{
    rdpContext context;   /* MUST be first */
    /* ... application-specific fields ... */
    MyWindow*  window;
    SDL_Renderer* renderer;
} MyClientContext;

The `rdp_freerdp` Instance

The freerdp typedef (struct rdp_freerdp) is the top-level handle passed to every public API. It carries:

Field	Description
`context`	Pointer to `rdpContext`
`ContextSize`	Size used by `freerdp_context_new()` for the context allocation
`ContextNew` / `ContextFree`	Lifecycle callbacks for context allocation
`PreConnect` / `PostConnect`	Connection phase callbacks
`Authenticate` / `AuthenticateEx`	Credential supply callbacks
`VerifyCertificateEx`	Certificate acceptance callback
`VerifyX509Certificate`	Full PEM certificate verification callback
`LoadChannels`	Called to configure channel plugins (possibly multiple times on redirect)
`SendChannelData` / `ReceiveChannelData`	Low-level channel I/O

Client Frontend Pattern

All bundled frontends follow the same pattern.

/* 1. Allocate the instance */
freerdp* instance = freerdp_new();

/* 2. Register custom context size */
instance->ContextSize = sizeof(MyClientContext);
instance->ContextNew  = my_context_new;   /* pContextNew callback */
instance->ContextFree = my_context_free;  /* pContextFree callback */

/* 3. Register connection callbacks */
instance->PreConnect  = my_pre_connect;
instance->PostConnect = my_post_connect;
instance->AuthenticateEx        = my_authenticate;
instance->VerifyCertificateEx   = my_verify_certificate;

/* 4. Allocate context (fires ContextNew) */
freerdp_context_new(instance);

/* 5. Configure settings */
rdpSettings* s = instance->context->settings;
freerdp_settings_set_string(s, FreeRDP_ServerHostname, "rdp.example.com");
freerdp_settings_set_uint32(s, FreeRDP_ServerPort, 3389);

/* 6. Connect */
if (!freerdp_connect(instance))
    /* handle error */;

/* 7. Event loop */
while (!freerdp_shall_disconnect_context(instance->context))
{
    DWORD status = WaitForMultipleObjects(nCount, events, FALSE, 100);
    freerdp_check_event_handles(instance->context);
}

/* 8. Teardown */
freerdp_disconnect(instance);
freerdp_context_free(instance);
freerdp_free(instance);

The RDP_CLIENT_ENTRY_POINTS struct (include/freerdp/client.h) provides an alternative entry-point mechanism used by the client helper library (libfreerdp-client). Frontends that use RdpClientEntry get GlobalInit, ClientNew, ClientStart, and ClientStop callbacks managed automatically.

Getting Started

Building from Source

Client Applications

Core Concepts

Server & Proxy

Guides

WinPR

Major Components

Connection Lifecycle

The `rdpContext` Structure

The `rdp_freerdp` Instance

Client Frontend Pattern

Getting Started

Building from Source

Client Applications

Core Concepts

Server & Proxy

Guides

WinPR

​Major Components

​Connection Lifecycle

​The rdpContext Structure

​The rdp_freerdp Instance

​Client Frontend Pattern

Major Components

Connection Lifecycle

The `rdpContext` Structure

The `rdp_freerdp` Instance

Client Frontend Pattern