Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed formatting and broken API links
Contents

...

Table of Contents

...

maxLevel5
minLevel2

Overview

A stream is a data type used to serially read and write bytes. The term "Stream", used generically, refers to a data type which implements a particular interface consisting of the methods that you would expect from a stream-like object, namely read(), write(), close(), isWritable(), and isReadable(). The Titanium Mobile SDK, starting with version 1.7.0, defines four types which implement this interface:

...

One use-case might be if you want to prepare a message in its entirety before opening a socket and sending the message. You can use a BufferStream to assemble the message in a buffer in memory, then later pass that buffer to a socket write operation.

BufferStream

...

examples

Here's a simple example of writing strings to a BufferStream and then reading them back.

Code Block
titleex01-bufferstream-create.js
linenumberstrue
languagejs
langjavascript

// Create the buffer & stream
var paragraph = Titanium.createBuffer({length: 1024});
var stream = Titanium.Stream.createStream({
  mode: Titanium.Stream.MODE_WRITE, // There is also MODE_APPEND for writing
  source: paragraph
});
Code Block
titleex02-bufferstream-write.js
linenumberstrue
languagejs
langjavascript

// Write to stream in chunks, filling up "paragraph" buffer.
// Each chunk will be an encoded UTF-8 string because we
// don't specify otherwise.
var length = 0;
length += stream.write(Titanium.createBuffer({
  value: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
}));
length += stream.write(Titanium.createBuffer({
  value: "Morbi vel mi in nunc bibendum congue at a ligula. Nunc at mauris dui, ac posuere ligula. "
}));
length += stream.write(Titanium.createBuffer({
  value: " Curabitur posuere cursus orci, id convallis metus venenatis sed."
}));

// Close the stream. The buffer still has the data in it.
stream.close();
Code Block
titleex03-bufferstream-resetlength.js
languagejs
langjavascript

// Set the buffer length to the actual bytes written.
paragraph.length = length;
Code Block
titleex04-bufferstream-create2.js
linenumberstrue
languagejs
langjavascript

// Read back the buffer in chunks.
// Create the read stream & buffer.
var CHUNK_SIZE = 10;
var read_buffer = Titanium.createBuffer({length: 1024});
stream = Titanium.Stream.createStream({
  mode: Titanium.Stream.MODE_READ,
  source: paragraph
});
Code Block
titleex05-bufferstream-readchunks.js
linenumberstrue
languagejs
langjavascript

// Read until end.
length = 0;
var bytes_read = 0;
while ((length = stream.read(read_buffer, bytes_read, CHUNK_SIZE)) > 0) {
  bytes_read += length;
};
Code Block
titleex07-bufferstream-decode.js
linenumberstrue
languagejs
langjavascript

// Get the read_buffer contents into a string.
var lorem = Ti.Codec.decodeString({
  source: read_buffer,
  charset: Ti.Codec.CHARSET_UTF8,
  length: bytes_read,
  position: 0
});

// Cleanup
stream.close();

...

There are two ways to get a FileStream instance. If you already have a File object, you can open a stream for it by using the new open method of Titanium.Filesystem.File. Alternatively, you can skip getting the File object if you have no other use for it and instead get a stream directly with the new Titanium.Filesystem.openStream method.

The supported modes are Titanium.Filesystem.MODE_READ, Titanium.Filesytem.MODE_WRITE and Titanium.Filesytem.MODE_APPEND.

FileStream

...

examples

This simple example reads and writes a file in 1K chunks rather than loading up the entirety of the file in memory. In this example we get streams by first getting <code>File</code> objects then calling their open() methods. However, in the case of the output file, we show the alternative openStream(...) method as well in a commented line.

Code Block
titleex01-filestream-getfile.js
linenumberstrue
languagejs
langjavascript

// Get the source file (this one is in Resources).
var infile = Titanium.Filesystem.getFile('emmy.jpg');
if (!infile.exists()) {
  Ti.API.error("File not exists()");
  return;
}
Code Block
titleex02-filestream-openread.js
languagejs
langjavascript

// Open for reading.
var instream = infile.open(Titanium.Filesystem.MODE_READ);
Code Block
titleex03-filestream-getoutfile.js
languagejs
langjavascript

// Get a file descriptor for output file. (Doesn't need to exist.)
var outfile =
  Titanium.Filesystem.getFile(Titanium.Filesystem.applicationDataDirectory, 'emmy_out.jpg');
Code Block
titleex04-filestream-openwrite.js
languagejs
langjavascript

// Open for writing.
var outstream = outfile.open(Titanium.Filesystem.MODE_WRITE);
Code Block
titleex04a-filestream-openstream.js
languagejs
langjavascript

// The last two steps could have been combined into one using this code:
//var outstream =
// Titanium.Filesystem.openStream(Titanium.Filesystem.MODE_WRITE, Titanium.Filesystem.applicationDataDirectory, 'emmy_out.jpg');
Code Block
titleex05-filestream-buffer.js
languagejs
langjavascript

// Create a 1K buffer for reading chunks.
var buffer = Titanium.createBuffer({length: 1024});
Code Block
titleex06-filestream-loopreadwrite.js
linenumberstrue
languagejs
langjavascript

// Read and write chunks.
var size = 0;
while ((size = instream.read(buffer)) > -1) {
  outstream.write(buffer);
  Titanium.API.info('Wrote ' + size + ' bytes');
}
Code Block
titleex07-filestream-cleanup.js
languagejs
langjavascript

// Cleanup.
instream.close();
outstream.close();

...

The BlobStream is a read-only stream that provides you with the ability to read blobs in chunks rather than load them up completely in memory. Blobs appear in a few places throughout the Titanium API, such as in Titanium.Media when dealing with images from the camera and photo gallery. You read from a BlobStream in the same manner you would for a BufferStream or a FileStream.

BlobStream

...

examples

In this example, we use Titanium.Media.showCamera to take a photo and stream its bytes to a file.

Code Block
titleex01-blobstream-full.js
linenumberstrue
languagejs
langjavascript

Ti.Media.showCamera({
  success: function(e) {
    // Open stream on blob.
    var instream = Titanium.Stream.createStream({
      mode: Titanium.Stream.MODE_READ,
      source: e.media // e.media is a Blob
    });
    // Open an output stream for a file
    // to hold the blob data.
    var f =
      Titanium.Filesystem.getFile(
          Titanium.Filesystem.applicationDataDirectory, "out.jpg");
    var outstream = f.open(Titanium.Filesystem.MODE_WRITE);
    // Create a buffer for chunking the data.
    var buffer = Ti.createBuffer({length: 1024});
    // Read and write chunks.
    var read_bytes = 0;
    while ((read_bytes = instream.read(buffer)) > 0) {
      outstream.write(buffer, 0, read_bytes);
    }
    // Cleanup.
    instream.close();
    outstream.close();
  }
});