Blob API

The 'Blob' object is a general-purpose way to reference binary data in web applications.

Contents

  1. Overview
  2. Blob class

Overview

JavaScript has a built-in data type for text strings, but nothing for binary data. The Blob object attempts to address this limitation.

A Blob is a reference to an opaque block of binary data.

Blobs are a general-purpose interchange format. They can be passed into, and returned by, a variety of Gears methods. Blobs are, in many ways, parallel to Strings. Most APIs that accept a 'String' could be updated to accept 'String-or-Blob'.

Blobs are immutable. The binary data referenced by a Blob cannot be modified directly. (This guarantees Blobs will have predictable behavior when passed to asynchronous APIs.) In practice, this is not a limitation; APIs can accept Blobs and return new Blobs. Note that JavaScript strings are also immutable; they behave the same way.

Throwing exceptions

Any operation involving a Blob may throw an exception. This includes:

Callers should be prepared to handle exceptions in all these cases.

Exceptions can occur because Blobs may be backed by user files. If such a file changes, the Blob referencing it is no longer valid.

It is somewhat uncommon for files to change while they are being referenced. But web applications that want to be completely robust should handle this scenario.

Permission

The Blob API does not require user permission.

Blob class

readonly attribute int length
int[] getBytes([offset, length])
Blob slice(offset, [length])

Attributes

Attribute Type Description
length readonly attribute int The length of the Blob, in bytes.

Methods

int[] getBytes([offset, length])
Summary: Returns the bytes (as integers in the range 0-255) of a slice of the Blob.
Parameters: offset - Optional. The position of the first byte to return. The default value is zero.
length - Optional. The number of bytes to return. The default value means to the end of the Blob.
Return value: An integer array containing the Blob's bytes.
Blob slice(offset, [length])
Summary: Extracts a subset of the current Blob and returns it as a new Blob.
Parameters: offset - The position of the first byte to extract.
length - Optional. The number of bytes to extract. The default value means to the end of the Blob.
Return value: A new Blob containing the specified subset.