netwerk/streamconv/nsIStreamConverterService.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsIChannel;
   9 interface nsIInputStream;
  10 interface nsIStreamListener;
  11
  12 %{C++
  13 #define NS_ISTREAMCONVERTER_KEY         "@mozilla.org/streamconv;1"
  14 %}
  15
  16 /**
  17  * The nsIStreamConverterService is a higher level stream converter factory
  18  * responsible for locating and creating stream converters
  19  * (nsIStreamConverter).
  20  *
  21  * This service retrieves an interface that can convert data from a particular
  22  * MIME type, to a particular MIME type. It is responsible for any intermediary
  23  * conversion required in order to get from X to Z, assuming direct conversion
  24  * is not possible.
  25  *
  26  * @author Jud Valeski
  27  * @see nsIStreamConverter
  28  */
  29 [scriptable, uuid(f2b1ab53-f0bd-4adb-9365-e59b1701a258)]
  30 interface nsIStreamConverterService : nsISupports {
  31     /**
  32      * Tests whether conversion between the two specified types is possible.
  33      * This is cheaper than calling convert()/asyncConvertData(); it is not
  34      * necessary to call this function before calling one of those, though.
  35      */
  36     boolean canConvert(in string aFromType, in string aToType);
  37
  38     /**
  39      * Returns the content type that will be returned from a converter
  40      * created with aFromType and  * /*.
  41      * Can fail if no converters support this conversion, or if the
  42      * output type isn't known in advance.
  43      */
  44     ACString convertedType(in ACString aFromType, in nsIChannel aChannel);
  45
  46     /**
  47      * <b>SYNCHRONOUS VERSION</b>
  48      * Converts a stream of one type, to a stream of another type.
  49      *
  50      * Use this method when you have a stream you want to convert.
  51      *
  52      * @param aFromStream   The stream representing the original/raw data.
  53      * @param aFromType     The MIME type of aFromStream.
  54      * @param aToType       The MIME type of the returned stream.
  55      * @param aContext      Either an opaque context, or a converter specific
  56      *                      context (implementation specific).
  57      * @return              The converted stream. NOTE: The returned stream
  58      *                      may not already be converted. An efficient stream
  59      *                      converter implementation will convert data on
  60      *                      demand rather than buffering the converted data
  61      *                      until it is used.
  62      */
  63     nsIInputStream convert(in nsIInputStream aFromStream,
  64                            in string aFromType,
  65                            in string aToType,
  66                            in nsISupports aContext);
  67
  68     /**
  69      * <b>ASYNCHRONOUS VERSION</b>
  70      * Retrieves a nsIStreamListener that receives the original/raw data via its
  71      * nsIStreamListener::OnDataAvailable() callback, then converts and pushes
  72      * the data to aListener.
  73      *
  74      * Use this method when you want to proxy (and convert) nsIStreamListener
  75      * callbacks asynchronously.
  76      *
  77      * @param aFromType     The MIME type of the original/raw data.
  78      * @param aToType       The MIME type of the converted data.
  79      * @param aListener     The listener that receives the converted data.
  80      * @param aCtxt         Either an opaque context, or a converter specific
  81      *                      context (implementation specific).
  82      * @return              A nsIStreamListener that receives data via its
  83      *                      OnDataAvailable() method.
  84      */
  85     nsIStreamListener asyncConvertData(in string aFromType,
  86                                        in string aToType,
  87                                        in nsIStreamListener aListener,
  88                                        in nsISupports aContext);
  89 };