RetroZilla/ipc/ipcd/extensions/transmngr/module/tmQueue.h

187 lines
6.6 KiB
C
Raw Normal View History

2015-10-21 05:03:22 +02:00
/* ***** 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 _tmQueue_H_
#define _tmQueue_H_
#include "tmUtils.h"
#include "tmVector.h"
class tmClient;
class tmTransaction;
class tmTransactionManager;
/**
* This class isn't so much a queue as it is storage for transactions. It
* is set up to recieve and store transactions in a growing collection
* (using tmVectors). Different messages can be recieved from the
* Transaction Manager(TM) the queue belongs to which can add and remove
* listeners, empty the queue (flush), and add messages to the queue.
*
* See the documentation in tmTransactionService.h for details on the
* messages you can send to and recieve from the queues in the TM
*/
class tmQueue
{
public:
////////////////////////////////////////////////////////////////////////////
// Constructor & Destructor
/**
* Set the internal state to default values. Init() must be called
* after construction to allocate the storage and set the name and ID.
*/
tmQueue(): mID(0), mName(nsnull), mTM(nsnull) { }
/**
* Reclaim the memory allocated in Init(). Destroys the transactions in
* the transaction storage and the ids in the listener storage
*/
virtual ~tmQueue();
////////////////////////////////////////////////////////////////////////////
// Public Member Functions
/**
* Initialize internal storage vectors and set the name of the queue
* and the pointer to the TM container.
*
* @returns NS_OK if everything succeeds
* @returns -1 if initialization fails
*/
PRInt32 Init(const char* aName, PRUint32 aID, tmTransactionManager *aTM);
// Queue Operations
/**
* Adds the clientID to the list of queue listeners. A reply is created
* and sent to the client. The reply contains both the name of the
* queue and the id, so the client can match the id to the name and
* then use the id in all further communications to the queue. All
* current transactions in the queue are then sent to the client.
*
* If the client was already attached the reply is sent, but not the
* outstanding transactions, the assumption being made that all
* transactions have already been sent to the client.
*
* The reply is sent for all cases, with the return value in the status
* field.
*
* @returns >= 0 if the client was attached successfully
* @returns -1 if the client was not attached
* @returns -2 if the client was already attached
*/
PRInt32 AttachClient(PRUint32 aClientID);
/**
* Removes the client from the list of queue listeners. A reply is created
* and sent to the client to indicate the success of the removal.
*
* The reply is sent for all cases, with the status field set to either
* -1 or NS_OK.
*
* @returns NS_OK on success
* @returns -1 if client is not attached to this queue
* @returns TM_SUCCESS_DELETE_QUEUE if there are no more listeners,
* instructing the Transaction Mangaer to delete the queue.
*/
PRInt32 DetachClient(PRUint32 aClientID);
/**
* Removes all the transactions being held in the queue.
* A reply is created and sent to the client to indicate the
* completion of the operation.
*/
void FlushQueue(PRUint32 aClientID);
/**
* Places the transaction passed in on the queue. Takes ownership of the
* transaction, deletes it in the destructor. A reply is created and
* sent to the client to indicate the success of the posting of the
* transaction.
*
* The reply is sent for all cases, with the status field containing the
* return value.
*
* @returns >= 0 if the message was posted properly.
* @returns -1 if the client posting is not attached to this queue,
* if the transaction has been posted to the wrong queue or
* if an error occured when trying to add the post to the
* internal storage.
*/
PRInt32 PostTransaction(tmTransaction *aTrans);
// Accessors
/**
* @returns the ID of the queue
*/
PRUint32 GetID() const { return mID; }
/**
* @returns the name of the queue
*/
const char* GetName() const { return mName; }
protected:
/**
* Helper method to determine if the client has already attached.
*
* @returns PR_TRUE if the client is attached to the queue.
* @returns PR_FALSE if the client is not attached to the queue.
*/
PRBool IsAttached(PRUint32 aClientID);
////////////////////////////////////////////////////////////////////////////
// Protected Member Variables
// storage
tmVector mTransactions; // transactions that have been posted
tmVector mListeners; // programs listening to this queue
// bookkeeping
PRUint32 mID; // a number linked to the name in the mTM
char *mName; // format: [namespace][domainname(ie prefs)]
tmTransactionManager *mTM; // the container that holds the queue
};
#endif