| 1 | /* ***** BEGIN LICENSE BLOCK *****
|
|---|
| 2 | * Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|---|
| 3 | *
|
|---|
| 4 | * The contents of this file are subject to the Mozilla Public License Version
|
|---|
| 5 | * 1.1 (the "License"); you may not use this file except in compliance with
|
|---|
| 6 | * the License. You may obtain a copy of the License at
|
|---|
| 7 | * http://www.mozilla.org/MPL/
|
|---|
| 8 | *
|
|---|
| 9 | * Software distributed under the License is distributed on an "AS IS" basis,
|
|---|
| 10 | * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|---|
| 11 | * for the specific language governing rights and limitations under the
|
|---|
| 12 | * License.
|
|---|
| 13 | *
|
|---|
| 14 | * The Original Code is Mozilla Transaction Manager.
|
|---|
| 15 | *
|
|---|
| 16 | * The Initial Developer of the Original Code is
|
|---|
| 17 | * Netscape Communications Corp.
|
|---|
| 18 | * Portions created by the Initial Developer are Copyright (C) 2003
|
|---|
| 19 | * the Initial Developer. All Rights Reserved.
|
|---|
| 20 | *
|
|---|
| 21 | * Contributor(s):
|
|---|
| 22 | * John Gaunt <[email protected]>
|
|---|
| 23 | *
|
|---|
| 24 | * Alternatively, the contents of this file may be used under the terms of
|
|---|
| 25 | * either the GNU General Public License Version 2 or later (the "GPL"), or
|
|---|
| 26 | * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|---|
| 27 | * in which case the provisions of the GPL or the LGPL are applicable instead
|
|---|
| 28 | * of those above. If you wish to allow use of your version of this file only
|
|---|
| 29 | * under the terms of either the GPL or the LGPL, and not to allow others to
|
|---|
| 30 | * use your version of this file under the terms of the MPL, indicate your
|
|---|
| 31 | * decision by deleting the provisions above and replace them with the notice
|
|---|
| 32 | * and other provisions required by the GPL or the LGPL. If you do not delete
|
|---|
| 33 | * the provisions above, a recipient may use your version of this file under
|
|---|
| 34 | * the terms of any one of the MPL, the GPL or the LGPL.
|
|---|
| 35 | *
|
|---|
| 36 | * ***** END LICENSE BLOCK ***** */
|
|---|
| 37 |
|
|---|
| 38 | #ifndef _tmTransaction_H_
|
|---|
| 39 | #define _tmTransaction_H_
|
|---|
| 40 |
|
|---|
| 41 | #include "tmUtils.h"
|
|---|
| 42 |
|
|---|
| 43 | //////////////////////////////////////////////////////////////////////////////
|
|---|
| 44 | //
|
|---|
| 45 | // Message format
|
|---|
| 46 | //
|
|---|
| 47 | // |------------------------------------|--
|
|---|
| 48 | // |QueueID | |
|
|---|
| 49 | // |------------------------------------| |
|
|---|
| 50 | // | Action - Post/Flush/Attach etc | |- this is the tmHeader struct
|
|---|
| 51 | // |------------------------------------| |
|
|---|
| 52 | // |Status | |
|
|---|
| 53 | // |------------------------------------| |
|
|---|
| 54 | // |Padding | |
|
|---|
| 55 | // |------------------------------------|--
|
|---|
| 56 | // |Message Data (payload) |
|
|---|
| 57 | // |------------------------------------|
|
|---|
| 58 | //
|
|---|
| 59 | // The Attach call is a special case in that it doesn't have a QueueID yet. A
|
|---|
| 60 | // QueueID will be 0's. The message Data will be the Queue Name String which
|
|---|
| 61 | // will be the profile name with a domain attached, a domain being
|
|---|
| 62 | // [prefs|cookies|etc]
|
|---|
| 63 | //
|
|---|
| 64 | //////////////////////////////////////////////////////////////////////////////
|
|---|
| 65 |
|
|---|
| 66 | /**
|
|---|
| 67 | * tmHeader contains various flags identifying
|
|---|
| 68 | */
|
|---|
| 69 | struct tmHeader {
|
|---|
| 70 | PRInt32 queueID; // will be the index of the queue in the TM, can be < 0
|
|---|
| 71 | PRUint32 action; // defined by tmUtils.h will be > 0
|
|---|
| 72 | PRInt32 status; // return values from methods, could be < 0
|
|---|
| 73 | PRUint32 reserved; // not currently used, maintaining word alignment
|
|---|
| 74 | };
|
|---|
| 75 |
|
|---|
| 76 | /**
|
|---|
| 77 | * Using tmTransaction:
|
|---|
| 78 | *
|
|---|
| 79 | * After creating a tmTransaction either through new or as a member
|
|---|
| 80 | * or local variable a process must call Init() with the proper set of
|
|---|
| 81 | * arguements to initialize the state of the transaction. tmTransaction is
|
|---|
| 82 | * set up to accept 3 types of initialization.
|
|---|
| 83 | *
|
|---|
| 84 | * 1) Raw message - All data is carried in the byte pointer aMessage,
|
|---|
| 85 | * args 2,3,4 should be set to TM_NO_ID and aLength
|
|---|
| 86 | * must be set to the full length of aMessage, including null
|
|---|
| 87 | * termination if the payload is a null-term string and the size of the
|
|---|
| 88 | * tmHeader struct preceeding the message. Currently this
|
|---|
| 89 | * format is used at the IPC boundary, where we receive a byte pointer
|
|---|
| 90 | * from the IPC Daemon.
|
|---|
| 91 | *
|
|---|
| 92 | * 2) Flags only - aQueueID, aAction and aStatus are all set. aMessage
|
|---|
| 93 | * should be set to nsnull and aLength to 0. This format is used when
|
|---|
| 94 | * sending reply messages (except for ATTACH_REPLY) and when the TS
|
|---|
| 95 | * Transaction Service is sending "control" messages to the Manager -
|
|---|
| 96 | * flush, detach, etc...
|
|---|
| 97 | *
|
|---|
| 98 | * 3) Flags and message - All arguements are set. The aMessage is only
|
|---|
| 99 | * the message for the client app. aLength should be set to the length
|
|---|
| 100 | * of aMessage and not include the length of the tmHeader struct.
|
|---|
| 101 | *
|
|---|
| 102 | * The only data member you can set post initialization is the QueueID.
|
|---|
| 103 | * You should only call Init() once in the lifetime of a tmTransaction
|
|---|
| 104 | * as it doesn't clean up the exisiting data before assigning the new
|
|---|
| 105 | * data. Therefore it would leak most heinously if Init() were to be
|
|---|
| 106 | * called twice.
|
|---|
| 107 | *
|
|---|
| 108 | * mOwnerID only has relevance on the IPC daemon side of things. The
|
|---|
| 109 | * Transaction Service has no knowledge of this ID and makes no use
|
|---|
| 110 | * of it.
|
|---|
| 111 | */
|
|---|
| 112 | class tmTransaction
|
|---|
| 113 | {
|
|---|
| 114 |
|
|---|
| 115 | public:
|
|---|
| 116 |
|
|---|
| 117 | ////////////////////////////////////////////////////////////////////////////
|
|---|
| 118 | // Constructor(s) & Destructor
|
|---|
| 119 |
|
|---|
| 120 | tmTransaction(): mHeader(nsnull), mRawMessageLength(0), mOwnerID(0) { }
|
|---|
| 121 |
|
|---|
| 122 | virtual ~tmTransaction();
|
|---|
| 123 |
|
|---|
| 124 | ////////////////////////////////////////////////////////////////////////////
|
|---|
| 125 | // Public Member Functions
|
|---|
| 126 |
|
|---|
| 127 | // Initializer ////////////
|
|---|
| 128 |
|
|---|
| 129 | /**
|
|---|
| 130 | * Sets up the internal data of the transaction. Allows for 3 basic ways
|
|---|
| 131 | * to call this function: No flags and just one big raw message, Just
|
|---|
| 132 | * flags and no message, and finally flags and message. If the message
|
|---|
| 133 | * exists it is copied into the transaction.
|
|---|
| 134 | *
|
|---|
| 135 | * @param aOwnerID is given to us by the IPC Daemon and is specific
|
|---|
| 136 | * to that transport layer. It is only set when transactions
|
|---|
| 137 | * are sent from the TM to the TS.
|
|---|
| 138 | *
|
|---|
| 139 | * @param aQueueID is the either the destination queue, or the queue from
|
|---|
| 140 | * where this transaction is eminating
|
|---|
| 141 | *
|
|---|
| 142 | * @param aAction is the action that occured to generate this transaction
|
|---|
| 143 | *
|
|---|
| 144 | * @param aStatus is the success state of the action.
|
|---|
| 145 | *
|
|---|
| 146 | * @param aMessage can be a raw message including the 3 flags above or it
|
|---|
| 147 | * can be just the "payload" of the transaction that the destination
|
|---|
| 148 | * process is going deal with.
|
|---|
| 149 | *
|
|---|
| 150 | * @param aLength is the length of the message. If there is a null
|
|---|
| 151 | * terminated string in the message make sure the length includes
|
|---|
| 152 | * the null termination.
|
|---|
| 153 | *
|
|---|
| 154 | * @returns NS_OK if everything was successful
|
|---|
| 155 | * @returns NS_ERROR_OUT_OF_MEMORY if allocation of space for the
|
|---|
| 156 | * copy of the message fails.
|
|---|
| 157 | */
|
|---|
| 158 | nsresult Init(PRUint32 aOwnerID,
|
|---|
| 159 | PRInt32 aQueueID,
|
|---|
| 160 | PRUint32 aAction,
|
|---|
| 161 | PRInt32 aStatus,
|
|---|
| 162 | const PRUint8 *aMessage,
|
|---|
| 163 | PRUint32 aLength);
|
|---|
| 164 |
|
|---|
| 165 | // Data Accessors /////////
|
|---|
| 166 |
|
|---|
| 167 | /**
|
|---|
| 168 | * @returns a const byte pointer to the message
|
|---|
| 169 | */
|
|---|
| 170 | const PRUint8* GetMessage() const { return (PRUint8*)(mHeader + 1); }
|
|---|
| 171 |
|
|---|
| 172 | /**
|
|---|
| 173 | * @returns the length of the message
|
|---|
| 174 | */
|
|---|
| 175 | PRUint32 GetMessageLength() const {
|
|---|
| 176 | return (mRawMessageLength > sizeof(tmHeader)) ?
|
|---|
| 177 | (mRawMessageLength - sizeof(tmHeader)) : 0;
|
|---|
| 178 | }
|
|---|
| 179 |
|
|---|
| 180 | /**
|
|---|
| 181 | * @returns a const pointer to the memory containing the
|
|---|
| 182 | * flag information followed immediately by the message
|
|---|
| 183 | * data.
|
|---|
| 184 | */
|
|---|
| 185 | const PRUint8* GetRawMessage() const { return (PRUint8*) mHeader; }
|
|---|
| 186 |
|
|---|
| 187 | /**
|
|---|
| 188 | * @returns the length of the flags and message combined
|
|---|
| 189 | */
|
|---|
| 190 | PRUint32 GetRawMessageLength() const { return mRawMessageLength; }
|
|---|
| 191 |
|
|---|
| 192 | /**
|
|---|
| 193 | * @returns the id of the destination or sending queue, depending on the
|
|---|
| 194 | * direction of the transaction.
|
|---|
| 195 | */
|
|---|
| 196 | PRInt32 GetQueueID() const { return mHeader->queueID; }
|
|---|
| 197 |
|
|---|
| 198 | /**
|
|---|
| 199 | * @returns the action represented by this transaction
|
|---|
| 200 | */
|
|---|
| 201 | PRUint32 GetAction() const { return mHeader->action; }
|
|---|
| 202 |
|
|---|
| 203 | /**
|
|---|
| 204 | * @returns the success state, if applicable of the action leading
|
|---|
| 205 | * up to this message
|
|---|
| 206 | */
|
|---|
| 207 | PRInt32 GetStatus() const { return mHeader->status; }
|
|---|
| 208 |
|
|---|
| 209 | /**
|
|---|
| 210 | * @returns the client ID (in IPC daemon terms) of the client who initiated
|
|---|
| 211 | * the exchange that generated this transaction.
|
|---|
| 212 | */
|
|---|
| 213 | PRUint32 GetOwnerID() const { return mOwnerID; }
|
|---|
| 214 |
|
|---|
| 215 | // Data Mutator ///////////
|
|---|
| 216 |
|
|---|
| 217 | /**
|
|---|
| 218 | * Sets the ID of the destination or source queue. Init should have been
|
|---|
| 219 | * called before the call to this function.
|
|---|
| 220 | */
|
|---|
| 221 | void SetQueueID(PRInt32 aID) { mHeader->queueID = aID; }
|
|---|
| 222 |
|
|---|
| 223 | protected:
|
|---|
| 224 |
|
|---|
| 225 | ////////////////////////////////////////////////////////////////////////////
|
|---|
| 226 | // Protected Member Variables
|
|---|
| 227 |
|
|---|
| 228 | tmHeader* mHeader; // points to beginning of entire message
|
|---|
| 229 | PRUint32 mRawMessageLength; // length of entire message, incl tmHeader
|
|---|
| 230 | PRUint32 mOwnerID; // client who sent this trans. - a IPC ClientID
|
|---|
| 231 |
|
|---|
| 232 | };
|
|---|
| 233 |
|
|---|
| 234 | #endif
|
|---|
