Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#include "nsISupports.idl"
#include "nsIArray.idl"
#include "nsISupportsPrimitives.idl"
#include "MailNewsTypes2.idl"
interface nsIMsgDBHdr;
interface nsIRequest;
interface nsIStreamListener;
interface nsIMsgIncomingServer;
interface nsIInputStream;
interface nsIMsgCopyServiceListener;
interface nsIURI;
interface nsIUrlListener;
// Forward declarations of callback classes defined later in this file.
interface IEwsFolderCallbacks;
interface IEwsFolderCreateCallbacks;
interface IEwsFolderDeleteCallbacks;
interface IEwsFolderUpdateCallbacks;
interface IEwsMessageCallbacks;
interface IEwsItemMoveCallbacks;
interface IEwsMessageCreateCallbacks;
interface IEwsMessageDeleteCallbacks;
interface IEwsMessageFetchCallbacks;
/**
* A client for communicating with a Microsoft Exchange server via Exchange Web
* Services.
*
* This interface is intended to provide an abstraction of EWS operations to
* bridge the foreign function interface between the components of a Thunderbird
* mail protocol implementation and a single implementation of those EWS ops.
*
* With the exception of initialization, all client operations are intended to
* be asynchronous, with implementations of the callback interfaces used to
* handle the results of the operations or handle errors.
*/
[scriptable, uuid(4a117361-653b-48a5-9ddb-588482ef9dbb)]
interface IEwsClient : nsISupports
{
/**
* Initializes a new client with the necessary host address and authentication
* details to communicate with an Exchange server.
*
* @param endpoint - The HTTP(S) address of an Exchange server's EWS endpoint.
* @param server - An incoming server entity corresponding to an EWS-capable
* account.
*/
void initialize(in AUTF8String endpoint, in nsIMsgIncomingServer server);
cenum Error : 8 {
EWS_ERR_AUTHENTICATION_FAILED,
EWS_ERR_UNEXPECTED,
};
/**
* Checks that the current client configuration is able to connect and
* authenticate against an EWS server.
*
* EWS does not have a dedicated endpoint that can be queried for this, so
* instead we test this by attempting to look up the account's root mail
* folder, since it results in a fairly small request and represents the first
* operation performed when adding the account to Thunderbird.
*
* @param callbacks - Callbacks to communicate the success or failure of the
* check.
* @returns The client's EWS endpoint's URL.
*/
nsIURI checkConnectivity(in nsIUrlListener listener);
/**
* Synchronizes the local folder listing with changes made on the remote
* Exchange server.
*
* @param callbacks - Callbacks for updating the local folder listing and the
* recorded synchronization state.
* @param syncState - A synchronization state token provided by a prior sync
* request, or an empty string to indicate that this is the initial sync.
*/
void syncFolderHierarchy(in IEwsFolderCallbacks callbacks, in AUTF8String syncStateToken);
/**
* Creates a new folder on the Exchange server as a child of the specified
* parent.
*
* @param parentId The EWS ID of the folder under which to create the new
* folder.
* @param name The name to use for the new folder.
* @param callbacks Callbacks to indicate the success or failure of the
* folder creation operation.
*/
void createFolder(in AUTF8String parentId, in AUTF8String name, in IEwsFolderCreateCallbacks callbacks);
void syncMessagesForFolder(in IEwsMessageCallbacks callbacks, in AUTF8String folderId, in AUTF8String syncStateToken);
void getMessage(in AUTF8String id, in IEwsMessageFetchCallbacks callbacks);
void changeReadStatus(in Array<AUTF8String> messageIds, in boolean readStatus);
/**
* Creates a new message on the server using the data read from the stream.
*
* @param folderId - The EWS ID of the folder.
* @param isDraft - Whether the message being created is an unsent draft.
* @param isRead - Whether the message has already been read.
* @param messageStream - The input stream to read the message from.
* @param callbacks - Callbacks for indicating operation state and status.
*/
void createMessage(in AUTF8String folderId,
in boolean isDraft,
in boolean isRead,
in nsIInputStream messageStream,
in IEwsMessageCreateCallbacks callbacks);
void deleteMessages(in Array<AUTF8String> messageEwsIds, in IEwsMessageDeleteCallbacks callbacks);
/**
* Deletes a folder on the Exchange server.
*
* @param callbacks - Callbacks to indicate the success or failure of the
* folder deletion operation.
* @param folderId - The EWS ID of the folder to delete.
*/
void deleteFolder(in IEwsFolderDeleteCallbacks callbacks, in AUTF8String folderId);
/**
* Renames a folder on the Exchange server.
*
* @param callbacks - Callbacks to indicate the success or failure of the
* folder update operation to rename the folder.
* @param folderId - The EWS ID of the folder to rename.
*/
void updateFolder(in IEwsFolderUpdateCallbacks callbacks, in AUTF8String folderId, in AUTF8String folderName);
/**
* Moves items on the Exchange server.
*
* @param callbacks - Callbacks to indicate the success of failure of the move operation.
* @param destinationFolderId - The EWS ID of the destination folder.
* @param itemIds - A list of the EWS IDs of the items to be moved.
*/
void moveItems(in IEwsItemMoveCallbacks callbacks, in AUTF8String destinationFolderId, in Array<AUTF8String> itemIds);
};
[scriptable, uuid(5dacc994-30e0-42f7-94c8-52756638add5)]
interface IEwsFolderCallbacks : nsISupports
{
void recordRootFolder(in AUTF8String id);
void create(in AUTF8String id, in AUTF8String parentId, in AUTF8String name, in unsigned long flags);
void update(in AUTF8String id, in AUTF8String parentId, in AUTF8String name);
void delete(in AUTF8String id);
/** Called after all sync items have been processed. */
void updateSyncState(in AUTF8String syncStateToken);
void onSuccess();
void onError(in IEwsClient_Error err, in AUTF8String desc);
};
/**
* Callbacks for communicating the results of creating a folder on the remote
* Exchange server.
*/
[scriptable, uuid(db950950-0824-4a8c-bace-871a950ace28)]
interface IEwsFolderCreateCallbacks : nsISupports
{
/**
* Called if a remote folder was successfully created.
*
* @param id - The EWS ID of the newly-created folder.
*/
void onSuccess(in AUTF8String id);
/**
* Called if remote folder creation failed.
*
* @param err - The type of error encountered.
* @param desc - A human-readable description of the error.
*/
void onError(in IEwsClient_Error err, in AUTF8String desc);
};
[scriptable, uuid(a439c288-7cee-422a-96ab-6aa69259827c)]
interface IEwsFolderDeleteCallbacks : nsISupports
{
/**
* Called if a folder was successfully deleted on the server.
*/
void onRemoteDeleteFolderSuccessful();
};
[scriptable, uuid(27337b4d-a40d-4034-9dc3-52abdd09b64c)]
interface IEwsFolderUpdateCallbacks : nsISupports
{
/**
* Called if a folder was successfully updated on the server.
*/
void onRemoteFolderUpdateSuccessful();
};
/**
* Callbacks used when interacting with an EWS server via an `IEwsClient` in the
* context of synchronizing changes to the message list.
*
* These callbacks allow the `IEwsClient` instance to perform local operation on
* the folder that is being synchronized.
*/
[scriptable, uuid(dec2ddd5-b5a2-4724-bfc7-e5de31840f76)]
interface IEwsMessageCallbacks : nsISupports
{
/**
* Creates and returns a database entry for the given EWS ID.
*
* If a database entry with this ID already exists, throws
* `NS_ERROR_ILLEGAL_VALUE`.
*
* @param ewsId - The EWS ID to associate with the database entry upon
* creation.
* @returns The newly created database entry.
*/
nsIMsgDBHdr createNewHeaderForItem(in AUTF8String ewsId);
void deleteHeaderFromDB(in AUTF8String ewsId);
/**
* Retrieves an existing database entry for the given EWS ID.
*
* If no database entry exists with this ID, throws `NS_ERROR_NOT_AVAILABLE`.
*
* @param ewsId - The EWS ID to use when looking up a database entry.
* @returns The existing database entry.
*/
nsIMsgDBHdr getHeaderForItem(in AUTF8String ewsId);
/**
* Deletes the locally-stored message content associated with the given
* database entry, if any.
*
* If no content has been stored for this message locally, this is a no-op.
*
* @param hdr - The database entry associated with the message content to
* remove.
*/
void maybeDeleteMessageFromStore(in nsIMsgDBHdr hdr);
/**
* Adds the given detached database entry to the current folder's database.
*
* @param hdr - The database entry to add.
*/
void saveNewHeader(in nsIMsgDBHdr hdr);
/**
* Commits any change to non-detached database entries in the current folder's
* database.
*/
void commitChanges();
/**
* Updates the stored sync state token for the current folder.
*
* @param syncStateToken - The new token to store.
*/
void updateSyncState(in AUTF8String syncStateToken);
/**
* Update the read flag for the message with the given EWS ID.
* When a message is marked as read/unread on the EWS server, the EWS server
* will represent this either as an `Update` element or `ReadFlagChange`
* element when syncing the message list.
*
* If a `ReadFlagChange` element is returned, then this method updates the
* read/unread status of the existing message in the current folder's database.
*/
void updateReadStatus(in AUTF8String ewsId, in boolean readStatus);
/**
* Signals that an error has happened during the current operation.
*
* @param err - The machine-readable error code.
* @param desc - A human-readable description of the error.
*/
void onError(in IEwsClient_Error err, in AUTF8String desc);
};
/**
* A set of callbacks called during the creation of a new message on an Exchange
* server.
*/
[scriptable, uuid(ff45569f-d618-4bb0-9686-6cb24b92b02b)]
interface IEwsMessageCreateCallbacks : nsISupports
{
/**
* Inform consumers that the message creation has finished, both on the server
* and the relevant local database and message store, with the provided
* status.
*/
void onStopCreate(in nsresult status);
/**
* Inform consumers of the key for the newly-created message in the local
* message database.
*/
void setMessageKey(in nsMsgKey aKey);
/**
* Signals that the message was correctly created on the server.
*
* Returns the header object to update with the message's metadata and to
* commit to the message database.
*
* `nsIMsgDBHdr` is a type quite strongly associated with the message database
* and storage, and, going forwards, we'll want to decouple these interfaces
* from local storage management. We use currently use it because we don't
* have a better way to represent structured headers over the XPCOM boundary,
* and parsing RFC822 messages is easier in Rust than using the C++ message
* parser. We should revisit our use of `nsIMsgDBHdr` in client code the
* situation improves.
*/
nsIMsgDBHdr onRemoteCreateSuccessful(in AUTF8String ewsId);
/**
* Writes the provided message entry to the database.
*/
void commitHeader(in nsIMsgDBHdr hdr);
};
[scriptable, uuid(98d7d1a9-d099-4b58-b4f7-6b476c6e4b90)]
interface IEwsItemMoveCallbacks : nsISupports
{
/**
* Signal that a remove move operation was successful.
*
* The `syncRequired` parameter indicates whether a full folder sync for the
* move destination is required. If `syncRequired` is false, then `newIds`
* will contain a list of the newly created EWS IDs in the destination folder
* that need to be created and downloaded. The order of `newIds` will
* correspond to the order of the EWS IDs provided to `IEwsClient::moveItems`.
*/
void onRemoteMoveSuccessful(in boolean syncRequired, in Array<AUTF8String> newIds);
/**
* Signal that an error occurred during a remove move operation.
*
* The type of error will be contained in the `err` parameter, and a
* description will be provided in the `description` parameter.
*/
void onError(in IEwsClient_Error err, in AUTF8String description);
};
[scriptable, uuid(2bd557ee-a1ce-4563-aaf3-653914256452)]
interface IEwsMessageDeleteCallbacks : nsISupports
{
void onRemoteDeleteSuccessful();
void onError(in IEwsClient_Error err, in AUTF8String desc);
};
/**
* A listener used when downloading message content.
*
* Its shape is loosely based on `nsIStreamListener`, which cannot be used in
* this instance because we don't always have a request/channel that can be used
* in method calls when fetching a message's content (and using `nullptr`
* everywhere is quite ugly and potentially unsafe).
*/
[scriptable, uuid(027150b1-d127-41a9-8945-18f9374755b3)]
interface IEwsMessageFetchCallbacks : nsISupports
{
void onFetchStart();
void onFetchedDataAvailable(in nsIInputStream inputStream, in unsigned long count);
void onFetchStop(in nsresult status);
};