Back to index

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

The tmTransactionService shares packets of information (transactions) with other Gecko based applications interested in the same namespace and domain. More...

#include <tmTransactionService.h>

Inheritance diagram for tmTransactionService:
Inheritance graph
[legend]
Collaboration diagram for tmTransactionService:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 tmTransactionService ()
virtual ~tmTransactionService ()
 Reclaim all the memory allocated: PL_hashtable, tmVectors.
void init (in ACString aNamespace)
 Connects the application to the transaction manager, defines the namespace and initializes internal storage.
void attach (in ACString aDomainName, in ipcITransactionObserver aObserver, in PRBool aLockingCall)
 Links the observer passed in with the domain specified.
void detach (in ACString aDomainName)
 Sends a detach message to the Transaction Manager to unlink the observer associated with the domain passed in.
void flush (in ACString aDomainName, in PRBool aLockingCall)
 Sends a flush message to the Transaction Manager to remove all transactions for the domain.
void postTransaction (in ACString aDomainName,[array, const, size_is(aDataLen)] in octet aData, in unsigned long aDataLen)
 Send the data to the Transaction Manager to be broadcast to any applications that have registered as observers of this particular namespace/domain pairing.
void onMessageAvailable (in unsigned long aSenderID, in nsIDRef aTarget,[array, const, size_is(aDataLen)] in octet aData, in unsigned long aDataLen)

Protected Member Functions

void SendMessage (tmTransaction *aTrans, PRBool aSync)
 Pulls the raw message out of the transaction and sends it to the IPC service to be delivered to the TM.
void OnAttachReply (tmTransaction *aTrans)
 Pulls the queueID out of the ATTACH_REPLY message and stores it in the proper tm_queue_mapping object.
void OnDetachReply (tmTransaction *aTrans)
 Removes the tm_queue_mapping object and calls the OnDetachReply() method on the observer of the queue detached.
void OnFlushReply (tmTransaction *aTrans)
 Calls the OnFlushReply method of the observer of the queue.
void OnPost (tmTransaction *aTrans)
 Calls the OnPost method of the observer of the queue.
void DispatchStoredMessages (tm_queue_mapping *aQMapping)
 Cycle through the collection of transactions waiting to go out and send any that are waiting on an ATTACH_REPLY from the queue specified by the tm_queue_mapping passed in.
PRInt32 GetQueueID (const nsACString &aDomainName)
char * GetJoinedQueueName (PRUint32 aQueueID)
char * GetJoinedQueueName (const nsACString &aDomainName)
tm_queue_mappingGetQueueMap (PRUint32 aQueueID)
nsresult SendDetachOrFlush (PRUint32 aQueueID, PRUint32 aAction, PRBool aSync)
 Helper method for Detach and Flush requests.

Protected Attributes

nsCString mNamespace
PLHashTablemObservers
tmVector mQueueMaps
tmVector mWaitingMessages
nsCOMPtr< ipcILockServicelockService

Detailed Description

The tmTransactionService shares packets of information (transactions) with other Gecko based applications interested in the same namespace and domain.

An application registers with the Transaction Service for a particular namespace and domain and then can post transactions to the service and receive transactions from the service.

For applications using the Transaction Service to share changes in state that get reflected in files on disk there are certain pattersn to follow to ensure data loss does not occur.

Startup: XXX docs needed

Shutdown/writing to disk: XXX docs needed

Definition at line 70 of file tmTransactionService.h.


Constructor & Destructor Documentation

Definition at line 78 of file tmTransactionService.h.

: mObservers(0) {};

Reclaim all the memory allocated: PL_hashtable, tmVectors.

Definition at line 79 of file tmTransactionService.cpp.

                                            {

  // just destroy this, it contains 2 pointers it doesn't own.
  if (mObservers)
    PL_HashTableDestroy(mObservers);

  PRUint32 index = 0;
  PRUint32 size = mWaitingMessages.Size();
  tm_waiting_msg *msg = nsnull;
  for ( ; index < size; index ++) {
    msg = (tm_waiting_msg*) mWaitingMessages[index];
    delete msg;
  }

  size = mQueueMaps.Size();
  tm_queue_mapping *qmap = nsnull;
  for (index = 0; index < size; index++) {
    qmap = (tm_queue_mapping*) mQueueMaps[index];
    if (qmap)
      delete qmap;
  }
}

Here is the call graph for this function:


Member Function Documentation

void ipcITransactionService::attach ( in ACString  aDomainName,
in ipcITransactionObserver  aObserver,
in PRBool  aLockingCall 
) [inherited]

Links the observer passed in with the domain specified.

This will allow the observer to post transactions dealing with this domain as well as receive transactions posted by other applications observing this domain.

Return codes for this method confer information about the success of this call, not of the actual attaching of the observer to the domain. (except the TM_ERROR code - which means the observer can not attach) If the attach is successful the observer will have its OnAttachReply method called before this method returns.

Note: This call is synchronous and will not return until the call to OnAttachReply is made.

Parameters:
aDomainNamethe name of the domain, in the current namespace, to listen for transactions from. i.e. cookies
aObserverthis will be used to notify the application when transactions and messages come in.
aLockingCallHave the Transaction Sevice acquire a lock based on the domain before attaching. This should be used when persistant storage is being used to prevent data corruption.
Returns:
NS_OK if the attach message was sent to the Transaction Manager.
an NS_ERROR_<foo> code specific to the failure otherwise
TM_ERROR_QUEUE_EXISTS if the queue already exists which means someone has already attached to it.
void ipcITransactionService::detach ( in ACString  aDomainName) [inherited]

Sends a detach message to the Transaction Manager to unlink the observer associated with the domain passed in.

As in attach, return codes do not indicate success of detachment. The observer will have it's OnDetach method called if it is successfully detached.

Note: This call is an asynchronous call.

Parameters:
aDomainNamethe domain, in the current namespace, from which the client should be removed.
Returns:
NS_OK if the detach message is sent to the Transaction Manager
NS_ERROR_FAILURE is something goes wrong
NS_ERRROR_UNEXPECTD if the domain does not have an observer attached

Cycle through the collection of transactions waiting to go out and send any that are waiting on an ATTACH_REPLY from the queue specified by the tm_queue_mapping passed in.

Definition at line 412 of file tmTransactionService.cpp.

                                                                        {

  PRUint32 size = mWaitingMessages.Size();
  tm_waiting_msg *msg = nsnull;
  for (PRUint32 index = 0; index < size; index ++) {
    msg = (tm_waiting_msg*) mWaitingMessages[index];
    // if the message is waiting on the queue passed in
    if (msg && strcmp(aQMapping->domainName, msg->domainName) == 0) {

      // found a match, send it and remove
      msg->trans.SetQueueID(aQMapping->queueID);
      SendMessage(&(msg->trans), PR_FALSE);

      // clean up
      mWaitingMessages.Remove(msg);
      delete msg;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void ipcITransactionService::flush ( in ACString  aDomainName,
in PRBool  aLockingCall 
) [inherited]

Sends a flush message to the Transaction Manager to remove all transactions for the domain.

After this call there will be no transactions in the Transaction Manager for the namespace/domain pairing. It is up to the application to coordinate the flushing of the Transaction Manager with the writing of data to files, if needed.

Note: This call is synchronous and will not return until the call to OnFlushReply is made.

Parameters:
aDomainNameThe domain, in the current namespace, to flush.
aLockingCallHave the Transaction Sevice acquire a lock based on the domain before flushing. This should be used when persistant storage is being used to prevent data corruption.
Returns:
NS_OK if the flush message is sent to the Transaction Manager
NS_ERROR_FAILURE is something goes wrong
NS_ERRROR_UNEXPECTD if the domain does not have an observer attached
char * tmTransactionService::GetJoinedQueueName ( PRUint32  aQueueID) [protected]
Returns:
the joined queue name - namespace + domain (prefs, cookies etc) corresponding to the ID passed in.
nsnull if the ID is not found.

Definition at line 447 of file tmTransactionService.cpp.

                                                          {

  PRUint32 size = mQueueMaps.Size();
  tm_queue_mapping *qmap = nsnull;
  for (PRUint32 index = 0; index < size; index++) {
    qmap = (tm_queue_mapping*) mQueueMaps[index];
    if (qmap && qmap->queueID == aQueueID)
      return qmap->joinedQueueName;
  }
  return nsnull;
}

Here is the call graph for this function:

Here is the caller graph for this function:

char * tmTransactionService::GetJoinedQueueName ( const nsACString &  aDomainName) [protected]
Returns:
the joined queue name - namespace + domain (prefs, cookies etc) corresponding to the ID passed in.
nsnull if the ID is not found.

Definition at line 460 of file tmTransactionService.cpp.

                                                                       {

  PRUint32 size = mQueueMaps.Size();
  tm_queue_mapping *qmap = nsnull;
  for (PRUint32 index = 0; index < size; index++) {
    qmap = (tm_queue_mapping*) mQueueMaps[index];
    if (qmap && aDomainName.Equals(qmap->domainName))
      return qmap->joinedQueueName;
  }
  return nsnull;
}

Here is the call graph for this function:

PRInt32 tmTransactionService::GetQueueID ( const nsACString &  aDomainName) [protected]
Returns:
the ID corresponding to the domain name passed in
TM_NO_ID if the name is not found.

Definition at line 434 of file tmTransactionService.cpp.

                                                               {

  PRUint32 size = mQueueMaps.Size();
  tm_queue_mapping *qmap = nsnull;
  for (PRUint32 index = 0; index < size; index++) {
    qmap = (tm_queue_mapping*) mQueueMaps[index];
    if (qmap && aDomainName.Equals(qmap->domainName))
      return qmap->queueID;
  }
  return TM_NO_ID;
}

Here is the call graph for this function:

Returns:
the tm_queue_mapping object that contains the ID passed in.
nsnull if the ID is not found.

Definition at line 473 of file tmTransactionService.cpp.

                                                   {

  PRUint32 size = mQueueMaps.Size();
  tm_queue_mapping *qmap = nsnull;
  for (PRUint32 index = 0; index < size; index++) {
    qmap = (tm_queue_mapping*) mQueueMaps[index];
    if (qmap && qmap->queueID == aQueueID)
      return qmap;
  }
  return nsnull;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void ipcITransactionService::init ( in ACString  aNamespace) [inherited]

Connects the application to the transaction manager, defines the namespace and initializes internal storage.

Parameters:
aNamespaceA string defining the scope of the transaction domains. It is used internally to seperate process listening to the same domain (ie. preferences) but for two different namespaces (ie. profile1 vs profile2).
Returns:
NS_OK if all memory allocated properly and the IPC service was reached and attached to successfully.
an NS_ERROR_<foo> code specific to the failure otherwise

Pulls the queueID out of the ATTACH_REPLY message and stores it in the proper tm_queue_mapping object.

Calls DispatchStoredMessages() to make sure we send any messages that have been waiting on the ATTACH_REPLY. Also calls the OnAttachReply() method for the observer of the queue.

Definition at line 334 of file tmTransactionService.cpp.

                                                         {

  // if we attached, store the queue's ID
  if (aTrans->GetStatus() >= 0) {

    PRUint32 size = mQueueMaps.Size();
    tm_queue_mapping *qmap = nsnull;
    for (PRUint32 index = 0; index < size; index++) {
      qmap = (tm_queue_mapping*) mQueueMaps[index];
      if (qmap && 
          PL_strcmp(qmap->joinedQueueName, (char*) aTrans->GetMessage()) == 0) {

        // set the ID in the mapping
        qmap->queueID = aTrans->GetQueueID();
        // send any stored messges to the queue
        DispatchStoredMessages(qmap);
      }
    }
  }

  // notify the observer we have attached (or didn't)
  ipcITransactionObserver *observer = 
    (ipcITransactionObserver *)PL_HashTableLookup(mObservers, 
                                                 (char*)aTrans->GetMessage());
  if (observer)
    observer->OnAttachReply(aTrans->GetQueueID(), aTrans->GetStatus());
}

Here is the call graph for this function:

Removes the tm_queue_mapping object and calls the OnDetachReply() method on the observer of the queue detached.

Definition at line 363 of file tmTransactionService.cpp.

                                                         {

  tm_queue_mapping *qmap = GetQueueMap(aTrans->GetQueueID());

  // get the observer before we release the hashtable entry
  ipcITransactionObserver *observer = 
    (ipcITransactionObserver *)PL_HashTableLookup(mObservers, 
                                                 qmap->joinedQueueName);

  // if it was removed, clean up
  if (aTrans->GetStatus() >= 0) {

    // remove the link between observer and queue
    PL_HashTableRemove(mObservers, qmap->joinedQueueName);

    // remove the mapping of queue names and id
    mQueueMaps.Remove(qmap);
    delete qmap;
  }


  // notify the observer -- could be didn't detach
  if (observer)
    observer->OnDetachReply(aTrans->GetQueueID(), aTrans->GetStatus());
}

Here is the call graph for this function:

Calls the OnFlushReply method of the observer of the queue.

Definition at line 390 of file tmTransactionService.cpp.

                                                        {

  ipcITransactionObserver *observer = 
    (ipcITransactionObserver *)PL_HashTableLookup(mObservers, 
                              GetJoinedQueueName(aTrans->GetQueueID()));
  if (observer)
    observer->OnFlushReply(aTrans->GetQueueID(), aTrans->GetStatus());
}

Here is the call graph for this function:

void ipcIMessageObserver::onMessageAvailable ( in unsigned long  aSenderID,
in nsIDRef  aTarget,
[array, const, size_is(aDataLen)] in octet  aData,
in unsigned long  aDataLen 
) [inherited]
Parameters:
aSenderIDthe client id of the sender of this message. if sent by the daemon (or a deamon module), then this will have a value of 0.
aTargetthe target of the message, corresponding to the target this observer was registered under. this parameter is passed to allow an observer instance to receive messages for more than one target.
aDatathe data of the message.
aDataLenthe data length of the message.
void tmTransactionService::OnPost ( tmTransaction aTrans) [protected]

Calls the OnPost method of the observer of the queue.

Definition at line 400 of file tmTransactionService.cpp.

                                                  {

  ipcITransactionObserver *observer = 
    (ipcITransactionObserver*) PL_HashTableLookup(mObservers, 
                              GetJoinedQueueName(aTrans->GetQueueID()));
  if (observer)
    observer->OnTransactionAvailable(aTrans->GetQueueID(), 
                                     aTrans->GetMessage(), 
                                     aTrans->GetMessageLength());
}

Here is the call graph for this function:

void ipcITransactionService::postTransaction ( in ACString  aDomainName,
[array, const, size_is(aDataLen)] in octet  aData,
in unsigned long  aDataLen 
) [inherited]

Send the data to the Transaction Manager to be broadcast to any applications that have registered as observers of this particular namespace/domain pairing.

If this domain is not being observed (attach has not been called for this domain) the message is queued until the attach is made and then the message is sent to the Transaction Manager with the proper domain information.

XXXjg - this may not be necessary with the synch attach call.

Note: This call is an asynchronous call.

Parameters:
aDomainNamethe domain, in the current namespace, to which the data will be sent.
aDataThe actual data to be sent.
aDataLenThe length of the data argument
nsresult tmTransactionService::SendDetachOrFlush ( PRUint32  aQueueID,
PRUint32  aAction,
PRBool  aSync 
) [protected]

Helper method for Detach and Flush requests.

Definition at line 486 of file tmTransactionService.cpp.

                                                      {

  // if the queue isn't attached to, just return
  if (aQueueID == TM_NO_ID)
    return NS_ERROR_UNEXPECTED;

  tmTransaction trans;
  if (NS_SUCCEEDED(trans.Init(0,         // no IPC client
                              aQueueID,  // qID to detach from
                              aAction,   // action
                              NS_OK,     // default status
                              nsnull,    // no message
                              0))) {      // no message
    // send it
    SendMessage(&trans, aSync);
    return NS_OK;
  }
  return NS_ERROR_FAILURE;
}

Here is the call graph for this function:

void tmTransactionService::SendMessage ( tmTransaction aTrans,
PRBool  aSync 
) [protected]

Pulls the raw message out of the transaction and sends it to the IPC service to be delivered to the TM.

Parameters:
aTransThe transaction to send to the TM
aSyncIf TRUE, calling thread will be blocked until a reply is received.

Definition at line 322 of file tmTransactionService.cpp.

                                                                     {

  NS_ASSERTION(aTrans, "tmTransactionService::SendMessage called with null transaction");

  IPC_SendMessage(0, kTransModuleID, 
                  aTrans->GetRawMessage(), 
                  aTrans->GetRawMessageLength());
  if (aSync)
    IPC_WaitMessage(0, kTransModuleID, nsnull, PR_INTERVAL_NO_TIMEOUT);
}

Here is the call graph for this function:

Here is the caller graph for this function:


Member Data Documentation

Definition at line 190 of file tmTransactionService.h.

Definition at line 184 of file tmTransactionService.h.

Definition at line 185 of file tmTransactionService.h.

Definition at line 187 of file tmTransactionService.h.

Definition at line 188 of file tmTransactionService.h.


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