text: /* ***** 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 Transaction Manager.
   *
   * The Initial Developer of the Original Code is
   * Netscape Communications Corp.
   * Portions created by the Initial Developer are Copyright (C) 2003
   * the Initial Developer. All Rights Reserved.
   *
   * Contributor(s):
   *   John Gaunt <jgaunt@netscape.com>
   *
   * 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 ***** */
  
  #ifndef _tmTransactionService_H_
  #define _tmTransactionService_H_
  
  #include "ipcdclient.h"
  #include "ipcILockService.h"
  #include "ipcIMessageObserver.h"
  #include "ipcITransactionService.h"
  #include "nsString.h"
  #include "nsVoidArray.h"
  #include "plhash.h"
  #include "tmTransaction.h"
  #include "tmVector.h"
  
  struct tm_queue_mapping;
  
  /**
    * The tmTransactionService shares packets of information
    *   (transactions) with other Gecko based applications interested in the same
    *   namespace and domain. An application registers with the Transaction Service
    *   for a particular namespace and domain and then can post transactions to the
    *   service and receive transactions from the service. 
    *
    * For applications using the Transaction Service to share changes in state that
    *   get reflected in files on disk there are certain pattersn to follow to ensure
    *   data loss does not occur. 
    *
    *   Startup: XXX docs needed
    *
    *   Shutdown/writing to disk: XXX docs needed
    *
    *
    */
  class tmTransactionService : public ipcITransactionService,
                               public ipcIMessageObserver
  {
  
  public:
  
    ////////////////////////////////////////////////////////////////////////////
    // Constructor & Destructor
    tmTransactionService() : mObservers(0) {};
  
    /**
      * Reclaim all the memory allocated: PL_hashtable, tmVectors
      */
    virtual ~tmTransactionService();
  
    ////////////////////////////////////////////////////////////////////////////
    // Interface Declarations
  
    // for API docs, see the respective *.idl files
    NS_DECL_ISUPPORTS
    NS_DECL_IPCITRANSACTIONSERVICE
    NS_DECL_IPCIMESSAGEOBSERVER
  
  protected:
  
    ////////////////////////////////////////////////////////////////////////////
    // Protected Member Functions
  
    /**
      * Pulls the raw message out of the transaction and sends it to the IPC
      *   service to be delivered to the TM.
      *
      * @param aTrans
      *        The transaction to send to the TM
      *
      * @param aSync 
      *        If TRUE, calling thread will be blocked until a reply is
      *        received.
      */
    void SendMessage(tmTransaction *aTrans, PRBool aSync);
  
    // handlers for reply messages from TransactionManager
  
    /**
      * Pulls the queueID out of the ATTACH_REPLY message and stores it in the
      *   proper tm_queue_mapping object. Calls DispatchStoredMessages() to make
      *   sure we send any messages that have been waiting on the ATTACH_REPLY.
      *   Also calls the OnAttachReply() method for the observer of the queue.
      */
    void OnAttachReply(tmTransaction *aTrans);
  
    /**
      * Removes the tm_queue_mapping object and calls the OnDetachReply() method
      *   on the observer of the queue detached.
      */
    void OnDetachReply(tmTransaction *aTrans);
  
    /**
      * Calls the OnFlushReply method of the observer of the queue.
      */
    void OnFlushReply(tmTransaction *aTrans);
  
    /**
      * Calls the OnPost method of the observer of the queue.
      */
    void OnPost(tmTransaction *aTrans);
  
    // other helper functions
  
    /**
      * Cycle through the collection of transactions waiting to go out and
      *   send any that are waiting on an ATTACH_REPLY from the queue
      *   specified by the tm_queue_mapping passed in.
      */
    void DispatchStoredMessages(tm_queue_mapping *aQMapping);
  
    // helper methods for accessing the void arrays
  
    /**
      * @returns the ID corresponding to the domain name passed in
      * @returns TM_NO_ID if the name is not found.
      */
    PRInt32 GetQueueID(const nsACString & aDomainName);
  
    /**
      * @returns the joined queue name - namespace + domain 
      *          (prefs, cookies etc) corresponding to the ID passed in.
      * @returns nsnull if the ID is not found.
      */
    char* GetJoinedQueueName(PRUint32 aQueueID);
  
    /**
      * @returns the joined queue name - namespace + domain 
      *          (prefs, cookies etc) corresponding to the ID passed in.
      * @returns nsnull if the ID is not found.
      */
    char* GetJoinedQueueName(const nsACString & aDomainName);
  
    /**
      * @returns the tm_queue_mapping object that contains the ID passed in.
      * @returns nsnull if the ID is not found.
      */
    tm_queue_mapping* GetQueueMap(PRUint32 aQueueID);
  
    /**
      * Helper method for Detach and Flush requests.
      */
    nsresult SendDetachOrFlush(PRUint32 aQueueID,
                               PRUint32 aAction,
                               PRBool aSync);
  
    ////////////////////////////////////////////////////////////////////////////
    // Protected Member Variables
  
    nsCString mNamespace;               // limit domains to the namespace
    PLHashTable *mObservers;            // maps qName -> ipcITransactionObserver
  
    tmVector mQueueMaps;                // queue - name - domain mappings
    tmVector mWaitingMessages;          // messages sent before ATTACH_REPLY
  
    nsCOMPtr<ipcILockService> lockService;  // cache the lock service
  
  private:
  
  };
  
  #endif
  