Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Protected Attributes
tmTransaction Class Reference

Using tmTransaction: More...

#include <tmTransaction.h>

Collaboration diagram for tmTransaction:
Collaboration graph

List of all members.

Public Member Functions

 tmTransaction ()
virtual ~tmTransaction ()
nsresult Init (PRUint32 aOwnerID, PRInt32 aQueueID, PRUint32 aAction, PRInt32 aStatus, const PRUint8 *aMessage, PRUint32 aLength)
 Sets up the internal data of the transaction.
const PRUint8GetMessage () const
PRUint32 GetMessageLength () const
const PRUint8GetRawMessage () const
PRUint32 GetRawMessageLength () const
PRInt32 GetQueueID () const
PRUint32 GetAction () const
PRInt32 GetStatus () const
PRUint32 GetOwnerID () const
void SetQueueID (PRInt32 aID)
 Sets the ID of the destination or source queue.

Protected Attributes

PRUint32 mRawMessageLength
PRUint32 mOwnerID

Detailed Description

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.

Definition at line 112 of file tmTransaction.h.

Constructor & Destructor Documentation

Definition at line 120 of file tmTransaction.h.

Definition at line 44 of file tmTransaction.cpp.

  if (mHeader)

Member Function Documentation

PRUint32 tmTransaction::GetAction ( ) const [inline]
the action represented by this transaction

Definition at line 201 of file tmTransaction.h.

{ return mHeader->action; }

Here is the caller graph for this function:

a const byte pointer to the message

Definition at line 170 of file tmTransaction.h.

{ return (PRUint8*)(mHeader + 1); }

Here is the caller graph for this function:

the length of the message

Definition at line 175 of file tmTransaction.h.

    return (mRawMessageLength > sizeof(tmHeader)) ?
      (mRawMessageLength - sizeof(tmHeader)) : 0;

Here is the caller graph for this function:

PRUint32 tmTransaction::GetOwnerID ( ) const [inline]
the client ID (in IPC daemon terms) of the client who initiated the exchange that generated this transaction.

Definition at line 213 of file tmTransaction.h.

{ return mOwnerID; }

Here is the caller graph for this function:

PRInt32 tmTransaction::GetQueueID ( ) const [inline]
the id of the destination or sending queue, depending on the direction of the transaction.

Definition at line 196 of file tmTransaction.h.

{ return mHeader->queueID; }

Here is the caller graph for this function:

a const pointer to the memory containing the flag information followed immediately by the message data.

Definition at line 185 of file tmTransaction.h.

{ return (PRUint8*) mHeader; }

Here is the caller graph for this function:

the length of the flags and message combined

Definition at line 190 of file tmTransaction.h.

{ return mRawMessageLength; }

Here is the caller graph for this function:

PRInt32 tmTransaction::GetStatus ( ) const [inline]
the success state, if applicable of the action leading up to this message

Definition at line 207 of file tmTransaction.h.

{ return mHeader->status; }

Here is the caller graph for this function:

nsresult tmTransaction::Init ( PRUint32  aOwnerID,
PRInt32  aQueueID,
PRUint32  aAction,
PRInt32  aStatus,
const PRUint8 aMessage,
PRUint32  aLength 

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.

aOwnerIDis 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.
aQueueIDis the either the destination queue, or the queue from where this transaction is eminating
aActionis the action that occured to generate this transaction
aStatusis the success state of the action.
aMessagecan 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.
aLengthis the length of the message. If there is a null terminated string in the message make sure the length includes the null termination.
NS_OK if everything was successful
NS_ERROR_OUT_OF_MEMORY if allocation of space for the copy of the message fails.

Definition at line 52 of file tmTransaction.cpp.

  nsresult rv = NS_OK;
  tmHeader *header = nsnull;

  // indicates the message is the entire raw message
  if (aQueueID == TM_INVALID_ID) {
    header = (tmHeader*) malloc(aLength);
    if (header) {
      mRawMessageLength = aLength;
      memcpy(header, aMessage, aLength);
  else {   // need to create the tmHeader and concat the message
    header = (tmHeader*) malloc (sizeof(tmHeader) + aLength);
    if (header) {
      mRawMessageLength = sizeof(tmHeader) + aLength;
      header->action = aAction;
      header->queueID = aQueueID;
      header->status = aStatus;
      header->reserved = 0x00000000;
      if (aLength > 0)     // add the message if it exists
        memcpy((header + 1), aMessage, aLength);

  if (NS_SUCCEEDED(rv)) {
    mOwnerID = aOwnerID;
    mHeader = header;

  return rv;

Here is the call graph for this function:

Here is the caller graph for this function:

Sets the ID of the destination or source queue.

Init should have been called before the call to this function.

Definition at line 221 of file tmTransaction.h.

{ mHeader->queueID = aID; }

Here is the caller graph for this function:

Member Data Documentation

Definition at line 228 of file tmTransaction.h.

Definition at line 230 of file tmTransaction.h.

Definition at line 229 of file tmTransaction.h.

The documentation for this class was generated from the following files: