tmTransaction.h

/* ***** 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 */00069struct 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. */00112class tmTransaction
{
public:
////////////////////////////////////////////////////////////////////////////// Constructor(s) & DestructortmTransaction(): 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 */00170const PRUint8* GetMessage() const { return (PRUint8*)(mHeader + 1); }
/** * @returns the length of the message */00175 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. */00185const PRUint8* GetRawMessage() const { return (PRUint8*) mHeader; }
/** * @returns the length of the flags and message combined */00190 PRUint32 GetRawMessageLength() const { return mRawMessageLength; }
/** * @returns the id of the destination or sending queue, depending on the * direction of the transaction. */00196 PRInt32 GetQueueID() const { return mHeader->queueID; }
/** * @returns the action represented by this transaction */00201 PRUint32 GetAction() const { return mHeader->action; }
/** * @returns the success state, if applicable of the action leading * up to this message */00207 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. */00213 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. */00221voidSetQueueID(PRInt32 aID) { mHeader->queueID = aID; }
protected:
////////////////////////////////////////////////////////////////////////////// Protected Member VariablestmHeader* 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