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 /
osascriptprovides 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 authenticationpassword— password for a one-offconnectrequest; it requires an accountport— server port for a one-offconnectrequestresolution— desktop size inWidthxHeightform, for example"1920x1080"fullscreen— whether to open full screenclipboard— whether clipboard sharing is enabledsound— 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.