Programmatic interface

RDPlenty can be asked to open connections by other applications, scripts, launchers, and automation tools. There are two interfaces for doing this:

  • URLs are convenient when you only need to launch a connection. Opening an x-rdplenty: URL hands the request to RDPlenty and does not return a result to the caller.

  • AppleScript / osascript provides the same basic operations, but reports invalid arguments and whether RDPlenty accepted the request.

Both interfaces can either start an existing saved connection or create a one-off connection to a server.

URLs

RDPlenty handles URLs of the form:

x-rdplenty://connect?...

To start a saved connection, specify its name:

x-rdplenty://connect?name=Office%20PC

To connect directly to a server, specify its address:

x-rdplenty://connect?address=server.example.com

A non-default port can be supplied as well:

x-rdplenty://connect?address=server.example.com&port=3390

Account and password, when needed for a one-off connection, are supplied as URL user information:

x-rdplenty://alice:secret@connect?address=server.example.com

As with any URL, characters that are not valid literally in a URL must be percent-encoded. This is especially relevant to connection names, account names, passwords, and other values containing spaces or special characters.

Connection options

The following query parameters can be used with either a saved connection or a one-off connection:

resolution=1920x1080
fullscreen=true
clipboard=false
sound=false

For Boolean options, true, yes, on, and 1 mean enabled; false, no, off, and 0 mean disabled. Values are case-insensitive. A Boolean parameter with no value enables that option, for example:

x-rdplenty://connect?name=Office%20PC&fullscreen

When name is used, the saved connection supplies the server address, port, and other settings. The options above override the corresponding settings for this launch only; they do not modify the saved connection.

URL requests are fire-and-forget: macOS does not provide a result from an application launched through a URL. Invalid or unusable parameters are therefore ignored rather than reported back to the application that opened the URL. Any related warnings or errors are written to the application logs; see Logs. Use the scripting interface when the caller needs error reporting.

AppleScript and osascript

RDPlenty exposes two scripting commands corresponding to the same two operations.

To start a saved connection:

tell application "RDPlenty"
    start connection "Office PC"
end tell

Optional settings can be overridden for that launch:

tell application "RDPlenty"
    start connection "Office PC" resolution "1920x1080" fullscreen true clipboard false
end tell

To make a one-off connection directly to a server:

tell application "RDPlenty"
    connect to "server.example.com"
end tell

The direct connection form also accepts a port and credentials:

tell application "RDPlenty"
    connect to "server.example.com" port 3390 account "alice" password "secret"
end tell

The available optional settings are:

  • account — account used for authentication

  • password — password for a one-off connect request; it requires an account

  • port — server port for a one-off connect request

  • resolution — desktop size in WidthxHeight form, for example "1920x1080"

  • fullscreen — whether to open full screen

  • clipboard — whether clipboard sharing is enabled

  • sound — whether remote sound is played

port must be between 1 and 65535. The Boolean options use normal AppleScript Boolean values, true and false.

The same commands can be invoked from the shell with osascript. For example:

osascript -e 'tell application "RDPlenty" to start connection "Office PC"'

or:

osascript -e 'tell application "RDPlenty" to connect to "server.example.com" account "alice"'

Unlike URLs, scripting commands report argument errors to the caller and return a Boolean result indicating whether the request was accepted. A successful result means that RDPlenty was able to start processing the requested connection; it does not mean that the remote login itself ultimately succeeded.