expedat:// URLs
Web based ExpeDat transactions are described using a custom URL scheme "expedat://". This can be used to communicate document locations to other ExpeDat users, or to programmatically control ExpeDat clients. The URLs can be embedded into documents, passed privately into WebDat or ExpeDat Desktop via the HTTP API, or pasted into the ExpeDat Desktop Server field. When an expedat:// URL is activated as a link, ExpeDat Desktop will launch automatically and perform the transaction. When a webpage uses the HTTP API to execute a URL, the webpage is able to monitor the transaction and provide its own user interface.
The form below will let you manually create simple URLs. You can also create a URL in ExpeDat Desktop by selecting a remote location or item and clicking the 
button. Webpages can generate URLs using the EXP.js JavaScript library. The WebDat Reference UI, Web File Browser and Landing Page provide examples of creating and using expedat:// URLs.
Try It
The easiest way to create an expedat:// URL is to run ExpeDat Desktop, browse to the desired remote location and click the 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.
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 transaction. 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 may be used for that transfer. Note that the ExpeDat Desktop compression checkbox will not be changed even when compression is being used. |
| e= | Content encryption enabled (1) or disabled (0). ExpeDat Desktop defaults to the state shown by the Encryption checkbox. If ExpeDat Desktop executes a URL with e=1, the checkbox will be forced on. WebDat defaults to encryption on. WebDat will only disable content encryption for a specific transaction if e=0 is specified. |
| 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 ExpeDat Desktop 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 ExpeDat Desktop will open upon the success or failure of the URL transaction. |
| s= | Specify a Return URL, which ExpeDat Desktop will open upon the success or failure of the URL transaction, appending 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.