JavaScript API

Included in the "Web" folder of the ExpeDat distribution package is a JavaScript library and sample HTML for automating the creation and execution of expedat:// URLs.

EXP.js JavaScript library implementing the functions described below.
EXP.html  Simple HTML example showing how EXP.js can be used.

The functions below can be used to create and activate an "expedat://" URL, allowing JavaScript developers to dynamically create ExpeDat links and trigger actions.  These functions only construct URLs, they do not interpret them.  See the expedat:// URLs chapter for information about meaning and function.

EXP_IsURL()

This function simply tests whether the given string starts with "expedat://".

function EXP_IsURL( string /* The string to test */ )

Returns true if the string matches, false if it does not.  No other validation is performed.

EXP_FormParse()

Extract exp_ values from the given form DOM object and return them in a mutable object suitable for input to EXP_MakeURLObj().

function EXP_FormParse( thisform /* The form object containing the exp_ parameters */ )

The following form elements are supported.  See EXP_MakeURLObj() detailed semantics.

exp_server The DNS name or IP address of the ExpeDat server.
exp_path The remote path to target on the ExpeDat server.
exp_anonymous If present and non-zero, exp_username and exp_password will be ignored.
exp_username Username for authentication.
exp_password Password for authentication
exp_encrypt Encryption enabled value or checkbox.
exp_compress Compression enabled value or checkbox.
exp_handler Server object handler
exp_action The type of transaction to perform.
exp_limitui True if ExpeDat Desktop should not copy URL data to its UI.
exp_targets Multitarget parameters
exp_filter File selection filter
exp_options ExpeDat transaction options.

Additional exp_ elements may be supported in the future.

EXP_MakeURLObj()

Converts a JSON object structure into an expedat:// URL.

function EXP_MakeURLObj( args /* Values for the URL */ )

The output of EXP_FormParse is suitable as an input.  The following fields are supported.  Unsupported fields are quietly ignored.  Support for new fields may be added in the future.

server The DNS name or IP address of the ExpeDat server, followed by a colon and the server's UDP port number (e.g. "example.com:8080").
path The path to the targeted file or folder on the ExpeDat server.
username If non-null, a "u=" key will be included with this value.  Use an empty string "" to prompt the user, or null to omit the "u=" key entirely.
password If non-null, a "p=" key will be included with this value.
encrypt If non-null and non-empty, an "e=" key will be included with this value.  A non-zero numerical value will force encryption for this transaction.  Any other value, or null, will use the encryption state currently set in the client.
compress If non-null and non-empty, a "c=" key will be included with this value.  A non-zero numerical value will enable compression for this transaction.  A zero value will disable compression for this transaction.  null, will use the compression state currently set in the client.
handler If non-null, an "h=" key will be included with this value.  When non-empty, the server will be requested to use the specified Object Handler to process this request.  If the request appears to be a listing of a remote folder and the specified handler exists in the ExpeDat Desktop Handlers menu, then that handler will be selected for future requests.  Otherwise the Handlers menu will not be changed by this action.
action If non-null, an "a=" key will be included with this value.  Must be one of g, f, s, n, d, or rnull will omit the 'a=' key which is currently equivalent to a value of 'g'.
limitui If non-null and non-empty, a "l=" key will be included with this value.
prompt If non-null and non-empty, a "b=" key will be included with this value.  Non-zero forces ExpeDat Desktop to prompt for a download location before a Get operation.
mkdirs If non-null and non-empty, an "m=" key will be included with this value.  Non-zero instructs the server to create missing parent directories during a Send operation.
targets If non-null and non-empty, an "t=" key will be included with this value.  This allows you to specify multiple targets for a Get or Send operation.
returnurl If non-null and non-empty, an "r=" key will be included with this URL.  ExpeDat Desktop will invoke this Return URL upon completion of the operation.
statusurl If non-null and non-empty, an "s=" key will be included with this URL.  Upon completion of the operation, ExpeDat Desktop will invoke this Return URL, with target status information appended.

On success, a valid expedat:// URL is returned.  Use EXP_IsURL() to test this.  On failure, a string describing the error is returned.

EXP_DoURL()

This function executes the given expedat:// URL by setting this.location.  It calls EXP_IsURL() but performs no other validation.  Note that the browser will not inform us of whether the URL itself was successful.  All further user interaction is handled by the web browser and ExpeDat client.

function EXP_DoURL( url /* The URL to activate */ )

Returns null if the string was passed to this.location, or an error message if EXP_IsURL() returned false.

EXP_FormAction()

Given a form DOM object, this function extracts the EXP_MakeURL() parameters to construct and optionally activate an expedat:// URL.  It may be used in a form "onsubmit" event attribute or a similar form validation function.  The EXP.html example file illustrates the use of this interface.

/* exp_server DNS or IP, and port, of ExpeDat server [REQUIRED] ** exp_path Path prefix. A '/' will be appended ** exp_anonymous Ignore username and password ** exp_username Username text, if present but blank ExpeDat Desktop will prompt ** exp_password Password text, if present but blank ExpeDat Desktop will prompt ** exp_encrypt Encrypt value or a checkbox ** exp_compress Compress value or a checkbox ** exp_handler Server Object Handler text, if present ** exp_action One of g, f, s, n, x, r ** exp_urlonly If present and true, the URL will not be activated ** exp_limitui Non-zero if URL data should not be copied to the UI */ function EXP_FormAction( thisform, /* The form object containing the above parameters */ urlid, /* Optional id to receive the URL as .innerText */ errid /* Optional id to receive error message as .innerText */ )

The parameters for this function consist of DOM objects.

thisform The HTML form containing inputs for each parameter of EXP_MakeURL().  The name of each input should start with "exp_" followed by the name of the corresponding parameter.  For example, "exp_server".  One additional parameter, "exp_urlonly" may be provided.  If this is present and true, then the URL will be constructed but not activated.
urlid The id of a .innerText object which will receive the constructed expedat:// URL.  May be null.
errid The id of a .innerText object which will receive an error message, if one is generated.  If null, errors will be sent to console.debug.

The form inputs may be text fields, selection menus, or checkboxes.  Other input types which place their value in the ".value" field will work as well.

On success, the generated URL will be copied to urlid.innerText (if urlid is valid), and errid.innerText will be set to the empty string (if errid is valid).

If an error occurs, urlid.innerText will be set to the empty string (if urlid is valid), and an error message will be written to errid.innerText (if errid is valid) or console.debug (if errid is null).

This function always returns false.  An "onsubmit" form event attribute must return false to prevent the browser from trying to submit the form via HTTP.

Below is an example of a simple FORM declaration.  See EXP.html for a functional example.

<FORM onsubmit="return EXP_Get_Form(this,'exp_url','exp_error');" action="">

EXP_MakeURL() - Deprecated - Use EXP_MakeURLObj() instead

An expedat:// URL string is created and returned based on the given parameters.

function EXP_MakeURL( server, /* DNS or IP, and port, of ExpeDat server [REQUIRED] */ path, /* Path to the targeted ExpeDat file or folder */ username, /* Username, null for anonymous, blank to prompt */ password, /* Password, null for anonymous, blank to prompt */ encrypt, /* True if content must be encrypted, null to omit */ compress, /* True of content should be compressed, null to omit */ handler, /* Server Object Handler, null to omit */ action, /* Action to perform: g, f, s, n, x, r */ limitui /* True if URL data should not be copied to the UI */ )

On success, a valid expedat:// URL is returned.  Use EXP_IsURL() to test this.  On failure, a string describing the error is returned.

server The DNS name or IP address of the ExpeDat server, followed by a colon and the server's UDP port number (e.g. "example.com:8080").
path The path to the targeted file or folder on the ExpeDat server.
username If non-null, a "u=" key will be included with this value.  Use an empty string "" to prompt the user, or null to omit the "u=" key entirely.
password If non-null, a "p=" key will be included with this value.
encrypt If non-null and non-empty, an "e=" key will be included with this value.  A non-zero numerical value will force encryption for this transaction.  Any other value, or null, will use the encryption state currently set in the client.
compress If non-null and non-empty, a "c=" key will be included with this value.  A non-zero numerical value will enable compression for this transaction.  A zero value will disable compression for this transaction.  null, will use the compression state currently set in the client.
handler If non-null, an "h=" key will be included with this value.  When non-empty, the server will be requested to use the specified Object Handler to process this request.  If the request appears to be a listing of a remote folder and the specified handler exists in the ExpeDat Desktop Handlers menu, then that handler will be selected for future requests.  Otherwise the Handlers menu will not be changed by this action.
action If non-null, an "a=" key will be included with this value.  Must be one of g, f, s, n, d, or rnull will omit the 'a=' key which is currently equivalent to a value of 'g'.
limitui If non-null and non-empty, a "l=" key will be included with this value.

Only the server parameter is required to have a value.  All other parameters may be null.

Due their variable nature, Return URLs and Multiple Targets are not directly supported by this function.  Instead, use EXP_MakeURL() to create the base URL, then append "r=", "s=", or "t=" keys as needed.

EXP_DoAction() - Deprecated - Use EXP_MakeURLObj() and EXP_DoURL() instead

Combines EXP_MakeURL() and EXP_DoURL() to execute an ExpeDat action based on the given parameters.

function EXP_DoAction( server, /* DNS or IP of ExpeDat server [REQUIRED] */ path, /* Path to the targeted ExpeDat file or folder */ username, /* Username, null for anonymous, blank to prompt */ password, /* Password, null for anonymous, blank to prompt */ encrypt, /* True if content must be encrypted */ compress, /* True of content should be compressed */ handler, /* Server Object Handler, null to omit */ action, /* Action to perform: g, f, s, n, x, r */ limitui /* True if URL data should not be copied to the UI */ )

See EXP_MakeURL() for parameter descriptions.  See EXP_DoURL() for return description.