RetroZilla/ipc/ipcd/extensions/transmngr/common/tmTransaction.h

235 lines
8.7 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 _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