f78b12e570284aa8291f4ca1add24937fd107403vboxsync/* ***** BEGIN LICENSE BLOCK *****
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Version: MPL 1.1/GPL 2.0/LGPL 2.1
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The contents of this file are subject to the Mozilla Public License Version
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * 1.1 (the "License"); you may not use this file except in compliance with
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the License. You may obtain a copy of the License at
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Software distributed under the License is distributed on an "AS IS" basis,
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * for the specific language governing rights and limitations under the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The Original Code is Mozilla Transaction Manager.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The Initial Developer of the Original Code is
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Netscape Communications Corp.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Portions created by the Initial Developer are Copyright (C) 2003
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the Initial Developer. All Rights Reserved.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Contributor(s):
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * John Gaunt <jgaunt@netscape.com>
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Alternatively, the contents of this file may be used under the terms of
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * either the GNU General Public License Version 2 or later (the "GPL"), or
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * in which case the provisions of the GPL or the LGPL are applicable instead
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * of those above. If you wish to allow use of your version of this file only
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * under the terms of either the GPL or the LGPL, and not to allow others to
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * use your version of this file under the terms of the MPL, indicate your
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * decision by deleting the provisions above and replace them with the notice
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * and other provisions required by the GPL or the LGPL. If you do not delete
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the provisions above, a recipient may use your version of this file under
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the terms of any one of the MPL, the GPL or the LGPL.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * ***** END LICENSE BLOCK ***** */
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * This class isn't so much a queue as it is storage for transactions. It
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * is set up to recieve and store transactions in a growing collection
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * (using tmVectors). Different messages can be recieved from the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Transaction Manager(TM) the queue belongs to which can add and remove
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * listeners, empty the queue (flush), and add messages to the queue.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * See the documentation in tmTransactionService.h for details on the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * messages you can send to and recieve from the queues in the TM
f78b12e570284aa8291f4ca1add24937fd107403vboxsync ////////////////////////////////////////////////////////////////////////////
f78b12e570284aa8291f4ca1add24937fd107403vboxsync // Constructor & Destructor
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Set the internal state to default values. Init() must be called
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * after construction to allocate the storage and set the name and ID.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Reclaim the memory allocated in Init(). Destroys the transactions in
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * the transaction storage and the ids in the listener storage
f78b12e570284aa8291f4ca1add24937fd107403vboxsync ////////////////////////////////////////////////////////////////////////////
f78b12e570284aa8291f4ca1add24937fd107403vboxsync // Public Member Functions
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Initialize internal storage vectors and set the name of the queue
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * and the pointer to the TM container.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns NS_OK if everything succeeds
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns -1 if initialization fails
f78b12e570284aa8291f4ca1add24937fd107403vboxsync PRInt32 Init(const char* aName, PRUint32 aID, tmTransactionManager *aTM);
f78b12e570284aa8291f4ca1add24937fd107403vboxsync // Queue Operations
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Adds the clientID to the list of queue listeners. A reply is created
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * and sent to the client. The reply contains both the name of the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * queue and the id, so the client can match the id to the name and
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * then use the id in all further communications to the queue. All
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * current transactions in the queue are then sent to the client.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * If the client was already attached the reply is sent, but not the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * outstanding transactions, the assumption being made that all
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * transactions have already been sent to the client.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The reply is sent for all cases, with the return value in the status
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns >= 0 if the client was attached successfully
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns -1 if the client was not attached
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns -2 if the client was already attached
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Removes the client from the list of queue listeners. A reply is created
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * and sent to the client to indicate the success of the removal.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The reply is sent for all cases, with the status field set to either
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * -1 or NS_OK.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns NS_OK on success
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns -1 if client is not attached to this queue
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns TM_SUCCESS_DELETE_QUEUE if there are no more listeners,
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * instructing the Transaction Mangaer to delete the queue.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Removes all the transactions being held in the queue.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * A reply is created and sent to the client to indicate the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * completion of the operation.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * Places the transaction passed in on the queue. Takes ownership of the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * transaction, deletes it in the destructor. A reply is created and
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * sent to the client to indicate the success of the posting of the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * transaction.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * The reply is sent for all cases, with the status field containing the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * return value.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns >= 0 if the message was posted properly.
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * @returns -1 if the client posting is not attached to this queue,
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * if the transaction has been posted to the wrong queue or
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * if an error occured when trying to add the post to the
f78b12e570284aa8291f4ca1add24937fd107403vboxsync * internal storage.