diff options
Diffstat (limited to 'src/libs/xpcom18a4/ipc/ipcd/extensions/transmngr/common/tmTransaction.h')
| -rw-r--r-- | src/libs/xpcom18a4/ipc/ipcd/extensions/transmngr/common/tmTransaction.h | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/src/libs/xpcom18a4/ipc/ipcd/extensions/transmngr/common/tmTransaction.h b/src/libs/xpcom18a4/ipc/ipcd/extensions/transmngr/common/tmTransaction.h new file mode 100644 index 00000000..b86f20f0 --- /dev/null +++ b/src/libs/xpcom18a4/ipc/ipcd/extensions/transmngr/common/tmTransaction.h @@ -0,0 +1,234 @@ +/* ***** 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 _tmTransaction_H_ +#define _tmTransaction_H_ + +#include "tmUtils.h" + +////////////////////////////////////////////////////////////////////////////// +// +// Message format +// +// |------------------------------------|-- +// |QueueID | | +// |------------------------------------| | +// | Action - Post/Flush/Attach etc | |- this is the tmHeader struct +// |------------------------------------| | +// |Status | | +// |------------------------------------| | +// |Padding | | +// |------------------------------------|-- +// |Message Data (payload) | +// |------------------------------------| +// +// The Attach call is a special case in that it doesn't have a QueueID yet. A +// QueueID will be 0's. The message Data will be the Queue Name String which +// will be the profile name with a domain attached, a domain being +// [prefs|cookies|etc] +// +////////////////////////////////////////////////////////////////////////////// + +/** + * tmHeader contains various flags identifying + */ +struct tmHeader { + PRInt32 queueID; // will be the index of the queue in the TM, can be < 0 + PRUint32 action; // defined by tmUtils.h will be > 0 + PRInt32 status; // return values from methods, could be < 0 + PRUint32 reserved; // not currently used, maintaining word alignment +}; + +/** + * Using tmTransaction: + * + * After creating a tmTransaction either through new or as a member + * or local variable a process must call Init() with the proper set of + * arguements to initialize the state of the transaction. tmTransaction is + * set up to accept 3 types of initialization. + * + * 1) Raw message - All data is carried in the byte pointer aMessage, + * args 2,3,4 should be set to TM_NO_ID and aLength + * must be set to the full length of aMessage, including null + * termination if the payload is a null-term string and the size of the + * tmHeader struct preceeding the message. Currently this + * format is used at the IPC boundary, where we receive a byte pointer + * from the IPC Daemon. + * + * 2) Flags only - aQueueID, aAction and aStatus are all set. aMessage + * should be set to nsnull and aLength to 0. This format is used when + * sending reply messages (except for ATTACH_REPLY) and when the TS + * Transaction Service is sending "control" messages to the Manager - + * flush, detach, etc... + * + * 3) Flags and message - All arguements are set. The aMessage is only + * the message for the client app. aLength should be set to the length + * of aMessage and not include the length of the tmHeader struct. + * + * The only data member you can set post initialization is the QueueID. + * You should only call Init() once in the lifetime of a tmTransaction + * as it doesn't clean up the exisiting data before assigning the new + * data. Therefore it would leak most heinously if Init() were to be + * called twice. + * + * mOwnerID only has relevance on the IPC daemon side of things. The + * Transaction Service has no knowledge of this ID and makes no use + * of it. + */ +class tmTransaction +{ + +public: + + //////////////////////////////////////////////////////////////////////////// + // Constructor(s) & Destructor + + tmTransaction(): mHeader(nsnull), mRawMessageLength(0), mOwnerID(0) { } + + virtual ~tmTransaction(); + + //////////////////////////////////////////////////////////////////////////// + // Public Member Functions + + // Initializer //////////// + + /** + * Sets up the internal data of the transaction. Allows for 3 basic ways + * to call this function: No flags and just one big raw message, Just + * flags and no message, and finally flags and message. If the message + * exists it is copied into the transaction. + * + * @param aOwnerID is given to us by the IPC Daemon and is specific + * to that transport layer. It is only set when transactions + * are sent from the TM to the TS. + * + * @param aQueueID is the either the destination queue, or the queue from + * where this transaction is eminating + * + * @param aAction is the action that occured to generate this transaction + * + * @param aStatus is the success state of the action. + * + * @param aMessage can be a raw message including the 3 flags above or it + * can be just the "payload" of the transaction that the destination + * process is going deal with. + * + * @param aLength is the length of the message. If there is a null + * terminated string in the message make sure the length includes + * the null termination. + * + * @returns NS_OK if everything was successful + * @returns NS_ERROR_OUT_OF_MEMORY if allocation of space for the + * copy of the message fails. + */ + nsresult Init(PRUint32 aOwnerID, + PRInt32 aQueueID, + PRUint32 aAction, + PRInt32 aStatus, + const PRUint8 *aMessage, + PRUint32 aLength); + + // Data Accessors ///////// + + /** + * @returns a const byte pointer to the message + */ + const PRUint8* GetMessage() const { return (PRUint8*)(mHeader + 1); } + + /** + * @returns the length of the message + */ + PRUint32 GetMessageLength() const { + return (mRawMessageLength > sizeof(tmHeader)) ? + (mRawMessageLength - sizeof(tmHeader)) : 0; + } + + /** + * @returns a const pointer to the memory containing the + * flag information followed immediately by the message + * data. + */ + const PRUint8* GetRawMessage() const { return (PRUint8*) mHeader; } + + /** + * @returns the length of the flags and message combined + */ + PRUint32 GetRawMessageLength() const { return mRawMessageLength; } + + /** + * @returns the id of the destination or sending queue, depending on the + * direction of the transaction. + */ + PRInt32 GetQueueID() const { return mHeader->queueID; } + + /** + * @returns the action represented by this transaction + */ + PRUint32 GetAction() const { return mHeader->action; } + + /** + * @returns the success state, if applicable of the action leading + * up to this message + */ + PRInt32 GetStatus() const { return mHeader->status; } + + /** + * @returns the client ID (in IPC daemon terms) of the client who initiated + * the exchange that generated this transaction. + */ + PRUint32 GetOwnerID() const { return mOwnerID; } + + // Data Mutator /////////// + + /** + * Sets the ID of the destination or source queue. Init should have been + * called before the call to this function. + */ + void SetQueueID(PRInt32 aID) { mHeader->queueID = aID; } + +protected: + + //////////////////////////////////////////////////////////////////////////// + // Protected Member Variables + + tmHeader* mHeader; // points to beginning of entire message + PRUint32 mRawMessageLength; // length of entire message, incl tmHeader + PRUint32 mOwnerID; // client who sent this trans. - a IPC ClientID + +}; + +#endif |