8 FreeRDP3 migration notes

akallabeth edited this page 2024-10-12 08:22:54 +02:00

Unescape Escape

Table of Contents

• Deprecation macros
• Deprecated fields
• In rdpSettings
• In rdpContext
• In rdpRdp
• In POINTER_COLOR_UPDATE
• Const correct API
• Keyboard Input
• Client Common
• Migrate existing clients

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This page collects migration notes to port your code from FreeRDP 2 to FreeRDP 3.

Deprecation macros

The following CMake options are available to control compiling in deprecated functionality:

• WITH_FREERDP_DEPRECATED
• WITH_FREERDP_DEPRECATED_COMMANDLINE
• WITH_WINPR_DEPRECATED

They default to OFF but for compatibility with older software building on FreeRDP it might be useful to turn (some) to ON

Deprecated fields

In rdpSettings

• After #8046 replace your usage of RdpKeyFile And RdpKeyContent by PrivateKeyFile and PrivateKeyContent

In rdpContext

In rdpRdp

In POINTER_COLOR_UPDATE

xPos has been renamed to hotSpotX and yPos has been renamed to hotSpotY;

Const correct API

We´ve corrected the const correctness of most function arguments, so some local variables might need adjustment accordingly

Keyboard Input

KEYCODE_TYPE_EVDEV has been renamed to KEYCODE_TYPE_XKB, as it previously actually handled XKB keycodes, instead of evdev keycodes.

If you use GetVirtualKeyCodeFromKeycode() or GetKeycodeFromVirtualKeyCode() in your FreeRDP2 code and used KEYCODE_TYPE_EVDEV for translation between virtual keycodes and XKB keycodes and wish to do that further, change the used keyboard type from KEYCODE_TYPE_EVDEV to KEYCODE_TYPE_XKB.

Additionally, FreeRDP3 now supports actual translation between evdev keycodes and virtual keycodes. If you want to use that translation, use the keyboard type KEYCODE_TYPE_EVDEV.

Client Common

• rdpSettings* settings get copied during connection sequence and reset before redirect/reconnect now, so all settings that should survice a reconnect must be set in PreConnect
• Channel loading has been moved from PreConnect to LoadChannels. This has a default implementation in client/common and only step required is removing calls to freerdp_client_load_addins
• channel loading and common client related tasks have now a default implementation in include/freerdp/client.h this allows deprecating lots of setup code that was previously required for this the client should create a context containing rdpClientContext with a ClientNew implementation
• A new AuthenticateEx callback unifies all possible authentication related callbacks replacing and extending the older ones.
• Removed context related pointers from freerdp* instance, like rdpSettings* settings, rdpInput* input, ...
• Removed async-input and related settings

Migrate existing clients

Much common client code has been moved to a client common module. For existing clients, you should:

1. base your custom struct fields on rdpClientContext instead of rdpContext
2. use the freerdp_client_context_new and freerdp_client_context_free which already set up client common context internally
3. call freerdp_client_OnChannelConnectedEventHandler and freerdp_client_OnChannelDisconnectedEventHandler for channels you don´t handle in your client yourself.
4. Remove channel setup code for channels handled in freerdp_client_OnChannelConnectedEventHandler in your own handler

https://github.com/FreeRDP/FreeRDP.wiki.git