зеркало из https://github.com/mozilla/pjs.git
235 строки
8.7 KiB
C++
235 строки
8.7 KiB
C++
/* ***** 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
|