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 MTPexpedat manually and paste a URL into the Server field.
The easiest way to create an expedat:// URL is to run MTPexpedat, 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.
You can also create URLs by using the form below. Fill in the form much like you would in MTPexpedat. 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.
Create an ExpeDat link just like you would any other URL, but instead of "http://" or "ftp://", you will use "expedat://".
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:
The formal syntax is as follows:
Here is a working example which, if you have a working copy of MTPexpedat, will download the file "test5mb.dat" from the folder "tst" on the server "florida.mtpip.net", with encryption enabled:
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 Mac OS X.
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 Mac OS X systems, expedat:// URLs are handled by the MTPexpedat client. See the Client Integration section for more about preparing clients for use with expedat:// URLs.
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.
If a username is supplied, the user will be prompted to enter their password:
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:
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.
If no path is specified, the user will be taken to the applicable home directory.
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:
To reference the server root directory, use a tripple slash:
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:
Send a File or Folder
To Upload files or folders to the server, specify the destination path and the action parameter "a=s":
The MTPexpedat client will prompt the user to select the files or folders to upload, then send them to the indicated path on the server.
Create a Folder
To create a folder on the server, specify the path of the new folder and the action parameter "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":
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":
The MTPexpedat client will prompt the user to enter a new name.
Instead of specifying a single file to download or folder to receive a single 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), include a single "t=" key with the maximum number of files to be uploaded. For example:
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".
After completion of a URL operation, control and status can be returned to a web page by specifying a properly escaped return URL using the "r" or "s" query key. For example,
The URL value 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,
Upon completion of the requested transaction, the return URL will be invoked after appending "n1=name&r1=result", where "name" is the name of the file target and "result" is the number of bytes transferred successfully or a negative 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.
If an error occurs before any file are accessed, a single "n0=&r0=" key 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:
If the user cancelled the username prompt during the above URL, the return would be:
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:
If Limit UI is enabled, the MTPexpedat window will be hidden after the return URL is invoked.
Normally, information from the URL is copied into the Server, User, Pass, and Remote Path fields of MTPexpedat 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,
This is most useful when combined with a Return URL, allowing user interaction to be entirely controlled by web pages.
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.|
|c=||Compression enabled or disabled. If this key is present with a non-zero numerical value for a file download, then compression will be used for that download. Note that the compression checkbox will not be changed even though compression is being used for given download.|
|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 MTPexpedat user interface, thereby limiting the user's ability to interact with the server. If a Return URL is given, the MTPexpedat window will be hidden after the URL has completed.|
|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=||Append a status result to the given Return URL, which will be opened upon the success or failure of the URL transaction.|
|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. 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.