User:Jminta/Steel

Below is a proposal for a FUEL-like set of interfaces to facilitate Thunderbird extension development. STEEL is the Scriptable Thunderbird Easy Extension Library.

Motivations

In my view, the starting point for a FUEL-like library needs to be the intersections between significant numbers of existing Thunderbird extensions. These extensions are solving acknowledged problems for users, and where many of them follow similar patterns, we should streamline the process to encourage further innovation. Common extension patterns are

• Sync - various extensions sync data within thunderbird to external sources (address book, preferences, calendar)
• Message management - extensions allow new annotations or make it easier to add existing annotations to messages
• XXX- add more

Implementation Plan

Because of the size of this project (and the mess of the mailnews interfaces) these interfaces should be implemented in stages. The following is a proposed implementation strategy.

STEEL 0.1 (basic mail operations)

steelIAccount interface - basic implementation

• Implement the all/has/get accessors
• Full support for accessing folders,

steelIFolder interface - full implementation

steelIMessage interface - basic implementation

• Limited support for tags
• Limited support for altering message text

May just return email addresses instead of steelIPersons at this stage

This stage should include enough to allow for a non-RDF rewrite of the account pane, along with many other RDF-driven UI elements

STEEL 0.2 (basic thunderbird functions)

all relevant FUEL interfaces

STEEL 0.3 (more thunderbird features)

steelIAddressBook interface - full implementation

• This likely depends on the switch to mozStorage

steelIPerson interface - full implemenation

• see above

steelIAddressBooks interface - full implementation

steelIAccount interface

• Full support for adding/modifying/deleting accounts

steelIMessage interface

• Full support for tags

STEEL 0.4 (still more thunderbird functions)

steelISearchTerms interface - full implementation

implement the Application's search() function

steelIAccounts interface - full implementation

• implement add() and delete() functions

Interfaces

steelIListener

/**
 * Many mail-news operations are asynchronous.  When accessing information that
 * requires an asynchronous result to be returned, you should pass that method a
 * steelIListener. (These methods will all return an id of to allow you to track
 * requests.)  Reports from the asynchronous methods will be returned through
 * this listener.
 */
[scriptable, uuid(edb2e41c-9ba7-489e-ba2a-1ff3312ca915)]
interface steelIListener : nsISupports {
  /**
   * Called when one or more results to your request are available.
   *
   * @param requestId  the id of the original request
   * @param result     an array of results of the appropriate type
   */
  void onGetResult(in AString requestId, in nsIVariant result);

  /**
   * Called when all results to your request have been passed to onGetResult.
   *
   * @param requestId  the id of the original request
   * @param allResults an array of all results that were passed to onGetResult
   *
   * @note You can omit the onGetResult function if you simply with to handle
   *       all results at once via this method.
   */
  void onOperationComplete(in AString requestId, in nsIVariant allResults);
};

steelIApplication

/**
 * The core STEEL object, available in the global scope
 */
[scriptable, uuid(f265021a-7f1d-4b4b-bdc6-9aedca4d8f13)]
interface steelIApplication : nsISupports {
  /**
   * The steelIAccounts object
   */
  readonly attribute steelIAccounts accounts;
  /**
   * The steelIAddressBooks object
   */
  readonly attribute steelIAddressBooks addressBooks;

  /**
   * The steelIPreferences object
   */
  readonly attribute steelIPreferences preferences;

  /**
   * The steelIExtensions object
   */
  readonly attribute steelIExtensions extensions;

  /**
   * Will return all messages matching the search terms to the listener.
   *
   * @param terms  an array of the steelISearchTerms object for this search
   * @param listener  the listener to return results to
   *
   * @returns  an ID for this request
   *
   * @note multiple steelISearchTerms will be combined with an (inclusive) OR 
   * operator.  Call "add" multiple times on the same steelISearchTerms to use
   * the AND operator.
   */ 
  AString search([array] in steelISearchTerms terms, 
                 in steelIListener listener);

  /**
   * Returns a new steelISearchTerms object
   */
  steelISearchTerms getNewSearchTerms();

  /**
   * Adds an event listener to the appropriate event.  Note that we will fire a
   * lot of additional events here, including:
   *    onAccountCreated
   *    onAccountDeleted
   *    onAccountModified
   *    onNewMail
   *    onMessageShow
   *    xxx-what else?
   *
   * @param event    the name of the event to listen for
   * @param listener the steelIEventListener to call when the event happens
   */
   void  addListener(in AString event, in steelIEventListener listener);
};

steelIAccounts

[scriptable, uuid(db57aa8f-d9d9-47f8-8a4f-865d0a3661a8)]
interface steelIAccounts : nsISupports {
  /**
   * An array of all steelIAccounts for this Thunderbird profile
   */
  readonly attribute nsIVariant all;

  /**
   * Gets the specified steelIAccount
   *
   * XXX- what is the unique feature of account? We may just need to create our
   * own ids on the front-side here
   * 
   * @param id  the id for the address book
   */
  steelIAccount get(in AString id);

  /**
   * Returns true if the specified account exists
   *
   * @param id  the id for the account
   */
  boolean has(in AString id);

  /**
   * Adds this account to Thunderbird
   *
   * @param account  the steelIAccount for the new account to add
   */
   void add(in steelIAccount account);

  /**
   * Deletes this account from Thunderbird
   *
   * @param account  the steelIAccount to delete
   */
  void delete(in steelIAccount account);
};

steelIAccount

/**
 * A simplified view of a mail account.
 */
[scriptable, uuid(42d33892-36e5-439b-8e57-7c473599b9a9)]
interface steelIAccount : nsISupports {
  /**
   * The (outgoing) address associated with this account
   */
  readonly attribute AString address;

  /**
   * The display name for this account
   */
  readonly attribute AString displayName;

  /**
   * An array of steelIFolder objects for the top-level folders of this account
   *
   * XXX- can we do this in a sync way?  May need a getFolders() method with a
   * listener
   */
  readonly attribute nsIVariant folders;

  /**
   * A constant corresponding to the type of the account
   */
  readonly attribute interger type;

  const unsigned long ACCOUNT_TYPE_IMAP = 1;
  const unsigned long ACCOUNT_TYPE_POP = 2;

  /**
   * Returns a blank message that can be sent from this account.
   */
  steelIMessage newMessage();
};

steelIFolder

/**
 * Interface representing a folder in a particular account
 */
[scriptable, uuid(65b542cf-d984-414c-955d-58367d834b2f)]
interface steelIFolder : nsISupports {
  /**
   * An array of steelIMessages for all of the unread messages in this folder
   */
  readonly attribute nsIVariant unreadMsgs;

  /**
   * An array of steelIMessages for *all* messages in this folder
   */
  readonly attribute nsIVariant allMsgs;

  /**
   * Determines if a message exists in this folder
   */
  boolean has(in AString msgID);

  /**
   * Returns the steelIMessage for the given ID (if it exists).
   */
  steelIMessage get(in AString msgID);

  /**
   * An array of steelIFolders for all subfolders of this folder.
   */
  readonly attribute nsIVariant subfolders;

  /**
   * Compacts this folder on the server.
   */
  void compact();

  /**
   * Marks all messages in the folder as read
   */
  void markAsRead();
};

steelIMessage

/**
 * Interface representing a folder in a particular account
 */
[scriptable, uuid(cad7b25c-f59f-409c-8b43-0972afc5e6ce)]
interface steelIMessage : nsISupports {
  /**
   * A unique id for this message
   */
   readonly attribute AString id;

  /**
   * Some messages cannot have their attributes edited.  For instance, if the
   * message has been received, trying to alter the from address would be 
   * non-sensical.  This attribute 
  readonly attribute boolean isMutable;

  /**
   * If you want to work from a new copy of this message, you can clone it. This
   * message will initially be mutable.
   */
  steelIMessage clone();

  /**
   * Get a new steelIMessage for replying to this message.  It will have the to,
   * from, and account fields already set.  The body attribute will be the
   * quoted text of this current message;
   *
   * @param replyToAll  If true, all recipients will be added to the "to" field
   *                    for the message.
   */
  steelIMessage reply(in boolean replyToAll);

  /**
   * Get a new steelIMessage for forwarding this message.  The "to" field will
   * be blank and will need to be set before you send the message.
   */
  steelIMessage forward();

  /**
   * Actually send this message
   */
  void send();

  /**
   * Deletes the message from the server
   */
   void delete();

  /**
   * A steelIPerson object corresponding to the sender of this message
   */
  attribute steelIPerson from;

  /**
   * An array of steelIPersons that the message is directed to
   */
  attribute nsIVariant to;

  /**
   * The subject of this message
   */
  attribute AString subject;

  /**
   * The text of this message.  Note that in the case this is an html message,
   * this will be the actual HTML source.
   */
  attribute AString body;

  /**
   * Whether or not the message has been marked read.
   */
  attribute boolean read;

  /**
   * An integer priority for this message
   * xxx-range?
   */
   attribute integer priority;

  /**
   * Whether or not the message has been flagged for follow-up
   */
   attribute boolean flagged;

  /**
   * Array of strings for the tags for this message
   */
   readonly attribute nsIVariant tags;

   /**
    * Adds an additional tag to this message
    */
   void addTag(in steelITag tag);

   /**
    * Removes a particular tag from this message
    */
   void removeTag(in steelITag tag);
};

steelIPerson

[scriptable, uuid(b1052725-4531-449c-becf-7b16b26b8f23)]
interface steelIPerson : nsISupports {
  /**
   * The default (primary) email address for this person.  You should get other
   * addresses via the get() method.
   */
  attribute AString defaultAddress;

  /**
   * The display name for this person.  You can get and set the first/last name
   * properties via the appropriate methods.
   */
  attribute AString displayName;

  /**
   * Gets a particular property of this person, e.g. phone, website, etc
   *
   * @param property  the name of the property to get
   */
  nsIVariant get(in AString property);

  /**
   * Returns true if there is some value set for this property, false otherwise
   *
   * @param property  the name of the property to check
   */
  boolean has(in AString property);

  /**
   * Sets a particular property for this person.
   *
   * @param property  the name of the property to set
   * @param value     the value of the property
   *
   * @note  If this person is not in an address book, setting a property will
   *        only alter the current session.  If the person is in a book, setting
   *        it will alter that person's entry in the book.
   */
  void set(in AString property, in nsIVariant value);

  /**
   * The address book this card is a part of.  Null if the person is not in any
   * book.
   */
  attribute steelIAddressBook addressbook;
};

steelIAddressBooks

[scriptable, uuid(3c964f9d-d7e8-4967-bbdf-e481aaffcf6e)]
interface steelIAddressBooks : nsISupports {
  /**
   * An array of all steelIAcddressBooks for this Thunderbird profile
   */
  readonly attribute nsIVariant all;

  /**
   * Gets the specified steelIAddressBook
   *
   * XXX- what is the unique feature of a-book? We may just need to create our
   * own ids on the front-side here
   * 
   * @param id  the id for the address book
   */
  steelIAddressBook get(in AString id);

  /**
   * Returns true if the specified addressBook exists
   *
   * @param id  the id for the addressBook
   */
  boolean has(in AString id);

  /**
   * Adds this addressBook to Thunderbird
   *
   * @param account  the steelIAddressBook for the new account to add
   */
   void add(in steelIAddressBook addressBook);

  /**
   * Deletes this addressBook from Thunderbird
   *
   * @param addressBook  the steelIAddressBook to delete
   */
  void delete(in steelIAddressBook addressBook);
};

steelIAddressBook

[scriptable, uuid(0f5f5f51-5f6d-4853-ba61-a2f734d78e18)]
interface steelIAddressBook : nsISupports {
  /**
   * An array of steelIPersons (and steelIAddressBooks) for all cards in this
   * address book.  steelIAddressBooks will be returned for mailing lists. You
   * should use the instanceof operator, or the QueryInterface method to check
   * that you have the people.
   */
  readonly attribute nsIVariant cards;

  /**
   * Adds a person (or mailing list) to this address book.
   *
   * @param card  the steelIPerson or steelIAddressBook to add
   */
  void add(in nsIVariant card);

  /**
   * Deletes a person (or mailing list) to this address book.
   *
   * @param card  the steelIPerson or steelIAddressBook to delete
   */  
  void delete(in nsIVariant card);

  /**
   * Returns true if this person (or mailing list) is in this address book
   *
   * @param card  the steelIPerson or steelIAddressBook to check
   */ 
  boolean has(in steelIPerson);

  /**
   * Returns a steelIPerson object for the given email address
   *
   * @param email  the email address of the person to get.
  steelIPerson get(in AString email);
};

steelISearchTerms

[scriptable, uuid(2c2f46f7-c22e-4406-aba4-6f995f23c317)]
interface steelISearchTerms : nsISupports {
  /**
   * Adds an additional query term to the search.
   *
   * @param field    the field of messages to search
   * @param value    the value to locate in the field
   *
   * @note Multiple calls to "add" will be combined with an AND operator
   */
  void add(in AString field, in AString value);
  void clear();
  attribute boolean isNegative;
};

FUEL Interfaces

The following interfaces can be copied straight over from FUEL:

• steelIConsole
• steelIExtensions
• steelIExtension
• steelIPreference
• steelIPreferenceBranch
• steelIEvents
• steelIEventListener
• steelIEventItem