File interface

A JavaScript object implementing the File interface represents a file stored and managed by the platform’s file store.

Construction

Use O.file().

Interface

property digest

The digest of the file, as a hex encoded String.

property fileSize

The size of the file, in bytes, as a number.

property mimeType

The MIME type of the file, as set by the browser when the file was originally uploaded. Note that some MIME types are standardised as browsers tend to be a bit inconsistent.

property filename

The filename of the file, as set by the browser when the file was originally uploaded.

Note that if a file is uploaded again, it’s still only stored once, and the original filename isn’t changed. Users can use a different filename by using a FileIdentifier.

property basename

The filename of the file, without the file extension.

property createdAt

The Date when the file was originally uploaded for the first time.

function identifier()

Create a new FileIdentifier which refers to this file, with a random trackingId.

function secret

The file’s secret, as a String. You must always check the secret with the checkSecret() function.

function checkSecret(secret)

Compare the given secret with the file’s secret using a timing-attack resistant comparison algorithm. If the secret does not match, an exception is thrown.

function readAsString(charsetName)

Read the contents of the file, interpreted as a string in the given character set, eg "UTF-8".

Use this function with care, checking the fileSize property before calling it, as it is very easy to accidentally run out of memory.

property properties

A JavaScript Object, as a dictionary, containing additional properties of the file. These may not be available either because the file has not been processed yet, processing encountered an error, or the properties are not applicable to that file type.

numberOfPages: Number of pages in the file.

dimensions: Physical dimensions of the document represented by the file, with keys width, height and units.

thumbnail: The size of the thumbnail, if available, with keys width, height and mimeType.

function url(options)

Return a URL which can be used to download this file. See below for the optional options argument.

function toHTML(options)

Return some HTML which can be included in a web page. See below for the optional options argument.

Options

Property	Description	Default
`transform`	Transform to be applied to the file	`null`
`asFullURL`	Whether to include the hostname in the URL	`false`
`authenticationSignature`	Sign the URL to bypass the usual file download authentication. Note that this signature is only valid for the current user session.	`false`
`authenticationSignatureValidForSeconds`
	Sign the URL to bypass the usual file download authentication. The signature doesn’t need a user session, but is only valid for the specified number of seconds.	`null`
`linkToDownload`	When generating HTML, include a link to download the file.	`false`
`forceDownload`	Set the Content-Disposition to attachment to force the browser to download the file, rather than displaying it.	`false`

property thumbnailFile

A BinaryData object of the thumbnail image for this file, if available. Use the properties of the File to determine the existence, width and height of the image.

property tags

An Object-like dictionary of short String to String key value pairs, intended for storing additional properties about the file such as extended file information captured by external file preservation systems.

function changeTags(changes)

Modify the tags property. Call with an Object dictionary of String to String key value pairs. If a value is null or undefined, the tag is deleted.

Changing tags is performed atomically without race conditions for multiple concurrent modifications to tag.

An exception will be thrown if keys or values are not Strings.