nsIStreamConverter

Suppose you had code that converted plain text into HTML. You could implement this interface to allow everyone else to use your conversion logic using a standard api.

Stream converter users

There are currently two ways to use a stream converter:

1. Synchronous: Stream to Stream. You can supply the service with a stream of type X and it will convert it to your desired output type and return a converted (blocking) stream to you.
2. Asynchronous: nsIStreamListener to nsIStreamListener. You can supply data directly to the converter by calling it's nsIStreamListener.OnDataAvailable() method. It will then convert that data from type X to your desired output type and return converted data to you via the nsIStreamListener you passed in by calling its nsIStreamListener.OnDataAvailable() method.

Stream converter suppliers

Registering a stream converter: Stream converter registration is a two step process. First of all the stream converter implementation must register itself with the component manager using a contractid in the format below. Second, the stream converter must add the contractid to the registry.

Stream converter contractid format (the stream converter root key is defined in this file):

@mozilla.org/streamconv;1?from=FROM_MIME_TYPE&to=TO_MIME_TYPE

Method overview

Methods

asyncConvertData()

Asynchronous version: Converts data arriving via the converter's nsIStreamListener.OnDataAvailable() method from one type to another, pushing the converted data out to the caller via aListener::OnDataAvailable().

Use this method when you want to proxy (and convert) nsIStreamListener callbacks asynchronously.

void asyncConvertData(
  in string aFromType,
  in string aToType,
  in nsIStreamListener aListener,
  in nsISupports aCtxt
);

Parameters

aFromType

The MIME type of the original/raw data.

aToType

The MIME type of the converted data.

aListener

The listener who receives the converted data.

aCtxt

Either an opaque context, or a converter specific context (implementation specific).

convert()

Synchronous version: Converts a stream of one type, to a stream of another type.

Use this method when you have a stream you want to convert.

nsIInputStream convert(
  in nsIInputStream aFromStream,
  in string aFromType,
  in string aToType,
  in nsISupports aCtxt
);

Parameters

aFromStream

The stream representing the original/raw data.

aFromType

The MIME type of aFromStream.

aToType

The MIME type of the returned stream.

aCtxt

Either an opaque context, or a converter specific context (implementation specific).

Return value

The converted stream.