thunderbird-dev 11.0.1+build1-0ubuntu2 / usr / share / idl / thunderbird-11.0.1 / nsIAutoSyncManager.idl

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is the Mozilla Foundation.
 * Portions created by the Initial Developer are Copyright (C) 2008
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *  Emre Birol  <ebirol@gmail.com> (Original Author)
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */
 
#include "nsISupports.idl"

interface nsIAutoSyncMsgStrategy;
interface nsIAutoSyncFolderStrategy;
interface nsIMsgDBHdr;
interface nsIAutoSyncState;
interface nsIAutoSyncMgrListener;
interface nsIMsgFolder;
interface nsIMsgAccount;

[scriptable, uuid(41ec36a7-1a53-4ca3-b698-dca6452a8761)] 
interface nsIAutoSyncMgrListener : nsISupports {

  /**
   * Queue types
   */
  const long PriorityQueue = 1;
  const long UpdateQueue = 2;
  const long DiscoveryQueue = 3;

  /**
   * It is called on the listener when a new folder is added into
   * the queue
   *
   * @param aQType type of the queue
   * @param aFolder folder that is added into the queue
   */
  void onFolderAddedIntoQ(in long aQType, in nsIMsgFolder aFolder);
  
  /**
   * It is called on the listener when a folder is removed from
   * the queue
   *
   * @param aQType type of the queue
   * @param aFolder folder that is removed from the queue
   */
  void onFolderRemovedFromQ(in long aQType, in nsIMsgFolder aFolder);
  
  /**
   * It is called on the listener when a message download is successfully started
   *
   * @param aFolder folder in which the download is started 
   * @param aNumberOfMessages number of the messages that will be downloaded 
   * @param aTotalPending  total number of messages waiting to be downloaded 
   */
  void onDownloadStarted(in nsIMsgFolder aFolder, in unsigned long aNumberOfMessages, 
                         in unsigned long aTotalPending);
  /**
   * It is called on the listener when a message download on the given folder 
   * is completed
   */
  void onDownloadCompleted(in nsIMsgFolder aFolder);
  
  /**
   * It is called on the listener when an error occurs during the message download
   */
  void onDownloadError(in nsIMsgFolder aFolder);
  
  /*
   * Auto-Sync manager is running or waiting for idle 
   */
  void onStateChanged(in boolean aRunning);
  
  /**
   * It is called on the listener after the auto-sync manager starts to process 
   * existing headers of the given folder to find missing message bodies
   * (mostly for debugging purposes)
   */
  void onDiscoveryQProcessed(in nsIMsgFolder aFolder, in unsigned long aNumberOfHdrsProcessed, 
                             in unsigned long aLeftToProcess);
  
  /**
   * It is called on the listener after the auto-sync manager updates the given folder 
   * (mostly for debugging purposes)
   */
  void onAutoSyncInitiated(in nsIMsgFolder aFolder);
};


[scriptable, uuid(7fe0b48e-f5d8-4747-beb7-888c9cced3a5)]
interface nsIAutoSyncManager : nsISupports {

  /** 
   * Download models
   */
  const long dmParallel = 0;
  const long dmChained = 1;

  /**
   * Suggested minimum grouping size in bytes for message downloads.
   * Setting this attribute to 0 resets its value to the 
   * hardcoded default.
   */
  attribute unsigned long groupSize;

  /**
   * Active strategy function to prioritize
   * messages in the download queue
   */
  attribute nsIAutoSyncMsgStrategy msgStrategy;

  /**
   * Active strategy function to prioritize
   * folders in the download queue
   */
  attribute nsIAutoSyncFolderStrategy folderStrategy;

  /**
   * Adds a listener to notify about auto-sync events
   */
  void addListener(in nsIAutoSyncMgrListener aListener);
  
  /**
   * Removes the listener from notification list
   */
  void removeListener(in nsIAutoSyncMgrListener aListener);
    
  /**
   * Tests the given message to make sure that whether 
   * it fits the download criteria or not
   */
  boolean doesMsgFitDownloadCriteria(in nsIMsgDBHdr aMsgHdr);
  
  /**
   * Called by the nsAutoSyncState object when the download
   * queue is changed. Given interface is already addref'd.
   */
  void onDownloadQChanged(in nsIAutoSyncState aAutoSyncStateObj);
  
  /**
   * Called by the nsAutoSyncState object when the download
   * is started. Given interface is already addref'd.
   */
  void onDownloadStarted(in nsIAutoSyncState aAutoSyncStateObj, in nsresult aStartCode);
  
  /**
   * Called by the nsAutoSyncState object when the download
   * completed. Given interface is already addref'd.
   */
  void onDownloadCompleted(in nsIAutoSyncState aAutoSyncStateObj, in nsresult aExitCode);
  
  /**
   * Number of elements in the discovery queue.
   * @see nsAutoSyncManager.h for details
   */
  readonly attribute unsigned long discoveryQLength;
  
  /**
   * Number of elements in the update queue.
   * @see nsAutoSyncManager.h for details
   */
  readonly attribute unsigned long updateQLength;
  
  /**
   * Number of elements in the download queue (a.k.a priority queue).
   * @see nsAutoSyncManager.h for details
   */
  readonly attribute unsigned long downloadQLength;

  /**
   * Active download model; Chained (serial), or Parallel
   */
  attribute long downloadModel;

  /**
   * The imap folder corresponding to aAutoSyncState has had a message
   * added to it. Autosync may want to add this folder to the update q.
   *
   * @param aAutoSyncState state obj for folder needing updating
   */
  void onFolderHasPendingMsgs(in nsIAutoSyncState aAutoSyncState);

  /// Pause autosync (e.g., we're downloading for offline).
  void pause();
  
  /// Resume normal autosync activities (e.g., we've come back online).
  void resume();
};

%{C++
#define NS_AUTOSYNCMANAGER_CID  \
{ /* C358C568-47B2-42b2-8146-3C0F8D1FAD6E */  \
  0xc358c568, 0x47b2, 0x42b2,                 \
  { 0x81, 0x46, 0x3c, 0xf, 0x8d, 0x1f, 0xad, 0x6e }}
#define NS_AUTOSYNCMANAGER_CLASSNAME \
  "Auto-Sync Manager"
#define NS_AUTOSYNCMANAGER_CONTRACTID \
  "@mozilla.org/imap/autosyncmgr;1"
%}