expedat:// URLs

At the heart of ExpeDat Web Integration is the custom URL scheme "expedat://".  This standards compliant mechanism allows ExpeDat functionality to be embedded anywhere you can place a link without any dependencies on plug-ins, Java, or external services.  When activated, the link automatically launches the ExpeDat Client and performs the action specified in the link.  You can also launch ExpeDat Desktop manually and paste a URL into the Server field.

The web based Server File Browser and User Links pages both work by creating and activating expedat:// URLs.  The links are simple enough to be created by hand, but you can create them programatically with the included DEI.js JavaScript library, or automatically by clicking the Bookmark button in ExpeDat Desktop.

Try It

The easiest way to create an expedat:// URL is to run ExpeDat Desktop, browse to the desired remote location and click the Bookmark button.  This will generate an expedat:// URL, display it in the message box, and copy it to the system clipboard.

A simple way to save and distribute URLs is to create a desktop shortcut.  In Windows, right-click on the desktop and select "New" followed by "Shortcut".  Then paste the URL, click "Next", give it a name, and click "Finish".  In macOS, paste the URL into a TextEdit file, then highlight the URL and drag it to your desktop.

You can also create URLs by using the form below.  Fill in the form much like you would in ExpeDat Desktop.  If you want to download a specific file, include its name in the Remote Path field.  If you leave Pass blank, the user will be prompted for a password.  If you leave the Remote Path blank or end it with a forward slash, the path will be treated like a folder and the contents will be shown to the user.

Server User Pass Encrypt   Create URL
Compress
  Handler Remote Path
 You must enable JavaScript to use this form.

Fill in the form above then click Go to create a URL here.

For a more complete example of the form above, look at "EXP.html" in the "Web" folder of the ExpeDat distribution package.  Continue reading to learn how to more precisely control what ExpeDat links can do.

Syntax

Create an ExpeDat link just like you would any other URL, but instead of "http://" or "ftp://", you will use "expedat://".

expedat://server:port/path/file

Additional features can be activated using the GET query string format, allowing you to specify encryption, compression, user credentials, and other actions such as uploading files or creating a folder.  For example, to direct a new user to their ExpeDat home directory, you could use a link like this:

expedat://example.com//path/myfiles/?u=username

The formal syntax is as follows:

expedat://server[:port]/[/]path/file[/][?key=value&key=value...]

Here is a working example which, if you have a working copy of ExpeDat Desktop, will download the file "test5mb.dat" from the folder "tst" on the server "demo.mtpip.net", with encryption enabled:

expedat://demo.mtpip.net/test5mb.dat?e=1

A complete list of available options is given at the bottom of this page.

Using a Link

An end-user only needs to click on an embedded link to activate it.  Users can also paste or type ExpeDat links into their web-browser, or save them as bookmarks.  Links can be activated from the command line by typing "start expedat://..." in windows or "open expedat://..." in macOS.

When expedat:// links appear in plain text, such as in the body of an email, some software may not follow web standards when handling the link.  For example, Gmail will display the link correctly but when clicked Gmail replaces "expedat" with "http", causing the link to fail.  When sending links to end-users, consider ExpeDat User Links.

On Windows and macOS systems, expedat:// URLs are handled by the ExpeDat Desktop client.  See the Client Integration section for more about preparing clients for use with expedat:// URLs.

Authentication

ExpeDat links which do not specify a username or password value will access the server anonymously.  If the server does not support anonymous users, the transaction will fail.

Specifying a "u" or "p" key with no value will cause the client to prompt the user to enter their username and password.  This is the best practice for security.

expedat://demo.mtpip.net/test5mb.dat?u=

If a username is supplied, the user will be prompted to enter their password:

expedat://demo.mtpip.net/test5mb.dat?u=joe

If both a username and password are supplied in the link, then the user will not be prompted.  Clients will not display passwords provided in this way, but users may still see the password if the URL is visible.

Getting a File

The default action is to download the file at the given path.  This is done by either as shown above, or by specifying a "Get" action using the "a=g" parameter.  The two links below do the same thing:

expedat://demo.mtpip.net/test5mb.dat expedat://demo.mtpip.net/test5mb.dat?a=g

To download multiple files with a single URL, see Multiple Targets.

Downloads will be placed in the client's default folder unless the "b" option is given to prompt the user for a destination.

Listing a Folder

Instead of transferring a file, a link can simply simply take a user to a specific folder.  This is accomplished by specifying the folder path and ending it with a forward slash.

expedat://demo.mtpip.net/tst/

If no path is specified, the user will be taken to the applicable home directory.

expedat://demo.mtpip.net/

Authenticated users who are not restricted to their home directory can be directed to absolute paths by placing an extra forward slash at the start of the path:

expedat://demo.mtpip.net//absolute_path/

To reference the server root directory, use a tripple slash:

expedat://demo.mtpip.net///

Getting a Folder

The contents of a folder can be downloaded by specifying the folder path as you would for Listing, but with the "a=f" parameter:

expedat://demo.mtpip.net/tst/?a=f

Downloads will be placed in the client's default folder unless the "b" option is given to prompt the user for a destination.

Sending a File or Folder

To Upload files or folders to the server, specify the destination folder path and the action parameter "a=s":

expedat://demo.mtpip.net/tst/?a=s

The ExpeDat Desktop client will prompt the user to select the files or folders to upload, then send them to the indicated path on the server.

To allow the user to upload multiple files with a single URL, see Multiple Targets.  To upload a single file to a specific file name, use the options "a=s&t=1".  For example,

expedat://demo.mtpip.net/tst/destination.txt?a=s&t=1

Create a Folder

To create a folder on the server, specify the path of the new folder and the action parameter "a=n":

expedat://demo.mtpip.net/tst/newfolder/?a=n

The parent folder ("tst" in this example) must already exist.

Delete a File

To create delete a file or an empty folder on the server, specify the path of the deletion target and the action parameter "a=x":

expedat://demo.mtpip.net/tst/test5mb.dat?a=x

Mass deletion of folder contents is not currently supported: a folder must be empty to be deleted.

Rename a File

To rename a file or folder on the server, specify the path of the rename target and the action parameter "a=r":

expedat://demo.mtpip.net/tst?a=r

The ExpeDat Desktop client will prompt the user to enter a new name.

Multiple Targets

Instead of specifying a single file to download or upload, a URL may request up to 32 download or upload targets.  In both cases, the URL path must be that of an accessible folder.  For downloads (Gets), add multiple "t=" keys each with the relative path of a file to be downloaded.  For uploads (Sends), use a single "t=" key with the maximum number of files to be uploaded to the target folder.  For example:

expedat://expedat.example.com/?a=g&t=Celia.png&t=tst/testA.dat expedat://expedat.example.com/tst/?a=s&t=4

When a Return URL with status results is requested, status will be provided for each target.

At this time, the "t=" key may only be used with individual Gets or Sends.  It may not target folders and may not be used with actions other than "g" and "s".

Return URL

After completion of a URL operation, control and status can be returned to a web page by specifying a properly escaped return URL using either the "r" or "s" query key. For example,

expedat://expedat.example.com/Celia.png?a=g&r=https://www.example.com/%3Fid=123

or

expedat://expedat.example.com/Celia.png?a=g&s=https://www.example.com/%3Fid=123>

The URL given will be invoked when the requested transaction ends, whether by success or error.  It may include its own query string to specify a session id or other parameters.

If the "s" key is used, status information about the transaction will be appended to the return URL.  For example,

https://www.example.com/%3Fid=123&n1=name&r1=result&n2=name&r2=result

Status information is a sequence of "nX" and "rX" key/value pairs, each giving a target name and its result code.  A non-negative result indicates success and the number of bytes transferred, while a negative result is an error code from the movedat exit code list.  The number of name/result pairs depends on the number of targets and whether the URL was valid in the first place.  Because these result strings always begin with an ampersand, the base return URL should contain a question mark and at least one other query key for proper query string syntax.

If an error occurs before any file are accessed, a single "&n0=&r0=X" string will be reported with a negative movedat exit code value for r0.  Common errors are -32 if the user cancelled the operation and -18 if the URL was not properly formatted.  For example:

expedat://example.com/?a=g&u=&t=test100mb.dat&l=1&s=http://example.com/result.php/?id=X

If the user cancelled the username prompt during the above URL, the return would be:

http://example.com/result.php/?id=X&n0=&r=-32

If the URL is successfully started, then results will be reported for each target.  Each target name will be reported with keys starting at "n1=" up to "n32=" and each result will be reported with keys starting at "r1=" up to "r32=".  Success results are reported with a non-negative number of bytes transferred while error results are reported as a negative movedat exit code. For example:

http://example.com/result.php/?id=X&n1=Celia.png&r1=2824910&n2=test100mb.dat&r2=-32

If Limit UI is enabled, the ExpeDat Desktop window will be hidden after the return URL is invoked.

Limit UI

Normally, information from the URL is copied into the Server, User, Pass, and Remote Path fields of ExpeDat Desktop to allow the user to interact with the server beyond the scope of the requested transction.  You may disable such copying, and thereby limiting user interaction with the server, by include a "l=1" parameter in the query string.  For example,

expedat://expedat.example.com/Celia.png?a=g&l=1

This is most useful when combined with a Return URL, allowing user interaction to be entirely controlled by web pages.

Parameter Summary

As shown in the examples above, the following URL query keys can be used to in expedat:// URLs.  Remember to use proper URL encoding (such as %20 for spaces), especially for usernames or passwords which may contain special characters.

a= Action to perform: g, f, s, n, d, r.  If no action is specified, g will be assumed.  If an unrecognized action is specified, the URL will be discarded with an error.
b= Prior to getting a file or getting a folder, the presence of this key with a non-zero numerical value will cause the client to prompt the user to select a destination.  Otherwise, downloads will be placed into the client's default local folder.
c= Compression enabled or disabled.  If this key is present with a non-zero numerical value for a file transfer, then compression will be used for that transfer.  Note that the compression checkbox will not be changed even though compression is being used.
e= Encryption enabled or disabled.  When "e=1" is present in a URL, that operation will be encrypted and the Encryption checkbox will become checked so that subsequent operations will be encrypted.  When "e=0" is present, encryption for the operation will be disabled only if the Encryption checkbox is already disabled and the Encryption checkbox will not be changed.  If "e=" is omitted, the state of the Encryption checkbox determines whether encryption is used.  In other words, a URL can force encryption on, but a URL cannot force encryption off.
h=   Object Handler to use with this transaction.  If given, the server will use the specified handler instead of the filesystem.  Compression and folder streaming are disabled when using handlers.  If the Handler menu is enabled, a matching handler exists, and this is a request to list a remote folder, then that handler will be selected in the menu.  Otherwise, the specified handler will only apply to this URL.
l=   Limit the user interface.  When given a non-zero value, information from the URL will not be copied into the ExpeDat Desktop user interface, thereby limiting the user's ability to interact with the server.  If a Return URL is given, the ExpeDat Desktop window will be hidden after the URL has completed.
m= Create parent directories as needed (MkDirs).  When non-zero and uploading a file or creating a directory, the server will attempt to create any missing parent directories in the target path.  This task is automatically performed when sending a folder.  Implementation by Object Handlers, such as CloudDat S3, may vary.
u= Username given or prompted.  If this key is present with no value, then the user will be prompted to enter a username.  If a username is given, but not a password, the user will be prompted to enter a password.
p= Password given or prompted.  If this key is present with no value, then the user will be prompted to enter a password.  If a password is given, but not a username, the user will be prompted to enter a username.  For the best security, you should not place passwords in URLs.
r= Specify a Return URL, which will be opened upon the success or failure of the URL transaction.
s= Specify a Return URL, which will be opened upon the success or failure of the URL transaction, and append a status result.  Overrides "r=".
t= Target multiple Get or Send actions.  For a Get, you may specify up to 32 "t=" key/value pairs with each value providing a pathname relative to the folder given in the URL.  For a Send, a single t= value specifies the maximum number of files the user may upload to the given folder, but no more than 32.  As a special case, "a=s&t=1" allows the target URL to specify the name of the uploading file instead of just the folder. When a Return URL with status results is requested, status will be provided for each target.

Unrecognized keys will cause a warning to be displayed, and the URL will be processed as though the unrecognized key and its value were not present.  New keys may be introduced in future versions.  If a key is specified multiple times, the last value will be used and all earlier values in the string will be ignored.