/image/public/imgIDecoderObserver.idl

  1/** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2 *
  3 * ***** BEGIN LICENSE BLOCK *****
  4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5 *
  6 * The contents of this file are subject to the Mozilla Public License Version
  7 * 1.1 (the "License"); you may not use this file except in compliance with
  8 * the License. You may obtain a copy of the License at
  9 * http://www.mozilla.org/MPL/
 10 *
 11 * Software distributed under the License is distributed on an "AS IS" basis,
 12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 13 * for the specific language governing rights and limitations under the
 14 * License.
 15 *
 16 * The Original Code is mozilla.org code.
 17 *
 18 * The Initial Developer of the Original Code is
 19 * Netscape Communications Corporation.
 20 * Portions created by the Initial Developer are Copyright (C) 2001
 21 * the Initial Developer. All Rights Reserved.
 22 *
 23 * Contributor(s):
 24 *   Stuart Parmenter <pavlov@netscape.com>
 25 *   Bobby Holley <bobbyholley@gmail.com>
 26 *
 27 * Alternatively, the contents of this file may be used under the terms of
 28 * either the GNU General Public License Version 2 or later (the "GPL"), or
 29 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 30 * in which case the provisions of the GPL or the LGPL are applicable instead
 31 * of those above. If you wish to allow use of your version of this file only
 32 * under the terms of either the GPL or the LGPL, and not to allow others to
 33 * use your version of this file under the terms of the MPL, indicate your
 34 * decision by deleting the provisions above and replace them with the notice
 35 * and other provisions required by the GPL or the LGPL. If you do not delete
 36 * the provisions above, a recipient may use your version of this file under
 37 * the terms of any one of the MPL, the GPL or the LGPL.
 38 *
 39 * ***** END LICENSE BLOCK ***** */
 40
 41#include "imgIContainerObserver.idl"
 42
 43interface imgIRequest;
 44interface imgIContainer;
 45
 46%{C++
 47#include "nsRect.h"
 48%}
 49
 50/**
 51 * imgIDecoderObserver interface
 52 *
 53 * This interface is used both for observing imgIDecoder objects and for
 54 * observing imgIRequest objects.  In the former case, aRequest is
 55 * always null.
 56 *
 57 * We make the distinction here between "load" and "decode" notifications. Load
 58 * notifications are fired as the image is loaded from the network or
 59 * filesystem. Decode notifications are fired as the image is decoded. If an
 60 * image is decoded on load and not visibly discarded, decode notifications are
 61 * nested logically inside load notifications as one might expect. However, with
 62 * decode-on-draw, the set of decode notifications can imgRcome completely _after_
 63 * the load notifications, and can come multiple times if the image is
 64 * discardable. Moreover, they can be interleaved in various ways. In general,
 65 * any presumed ordering between load and decode notifications should not be
 66 * relied upon.
 67 *
 68 * Decode notifications may or may not be synchronous, depending on the
 69 * situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that
 70 * triggers a decode, all notifications that can be generated from the currently
 71 * loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed,
 72 * all, some, or none of the notifications may fire before the call returns.
 73 *
 74 * This interface will be cleaned up in bug 505385.
 75 *
 76 * @author Stuart Parmenter <pavlov@netscape.com>
 77 * @version 0.1
 78 * @see imagelib2
 79 */
 80[scriptable, uuid(5ca71b89-1a2f-475f-881d-d76c1531c4c8)]
 81interface imgIDecoderObserver : imgIContainerObserver
 82{
 83  /**
 84   * Load notification.
 85   *
 86   * called at the same time that nsIRequestObserver::onStartRequest would be
 87   * (used only for observers of imgIRequest objects, which are nsIRequests,
 88   * not imgIDecoder objects)
 89   */
 90  void onStartRequest(in imgIRequest aRequest);
 91
 92  /**
 93   * Decode notification.
 94   *
 95   * Called as soon as the image begins getting decoded. This does not include
 96   * "header-only" decodes used by decode-on-draw to parse the width/height
 97   * out of the image. Thus, it is a decode notification only.
 98   */
 99  void onStartDecode(in imgIRequest aRequest);
100
101  /**
102   * Load notification.
103   *
104   * Called once enough data has been loaded from the network that we were able
105   * to parse the width/height from the image. By the time this callback is been
106   * called, the size has been set on the container and STATUS_SIZE_AVAILABLE
107   * has been set on the associated imgRequest.
108   */
109  void onStartContainer(in imgIRequest aRequest, in imgIContainer aContainer);
110
111  /**
112   * Decode notification.
113   *
114   * called when each frame is created.
115   */
116  void onStartFrame(in imgIRequest aRequest, in unsigned long aFrame);
117
118  /**
119   * Decode notification.
120   *
121   * called when there is more to paint.
122   */
123  [noscript] void onDataAvailable(in imgIRequest aRequest, in boolean aCurrentFrame, [const] in nsIntRect aRect);
124
125  /**
126   * Decode notification.
127   *
128   * called when a frame is finished decoding.
129   */
130  void onStopFrame(in imgIRequest aRequest, in unsigned long aFrame);
131
132  /**
133   * Do not implement this. It is useless and going away.
134   */
135  void onStopContainer(in imgIRequest aRequest, in imgIContainer aContainer);
136
137  /**
138   * Notification for when an image is known to be animated. This should be
139   * fired at the earliest possible time.
140   */
141  void onImageIsAnimated(in imgIRequest aRequest);
142
143  /**
144   * In theory a decode notification, but currently a load notification.
145   *
146   * Ideally this would be called when the decode is complete. Unfortunately,
147   * this is currently the only way to signal decoding errors to consumers,
148   * and the only decoding errors that consumers care about (indeed, the only
149   * ones that they're prepared to hear about) are failures to instantiate the
150   * decoder (<img src="foo.html"> for example). Thus, currently this is just
151   * a companion to onStopDecode to signal success or failure. This will be
152   * revisited in bug 505385. If you're thinking of doing something new with
153   * this, please talk to bholley first.
154   */
155  void onStopDecode(in imgIRequest aRequest, in nsresult status,
156                    in wstring statusArg);
157
158  /**
159   * Load notification.
160   *
161   * called at the same time that nsIRequestObserver::onStopRequest would be
162   * (used only for observers of imgIRequest objects, which are nsIRequests,
163   * not imgIDecoder objects)
164   */
165  void onStopRequest(in imgIRequest aRequest, in boolean aIsLastPart);
166
167  /**
168   * Called when the decoded image data is discarded. This means that the frames
169   * no longer exist in decoded form, and any attempt to access or draw the
170   * image will initiate a new series of progressive decode notifications.
171   */
172  void onDiscard(in imgIRequest aRequest);
173
174};