Back to index

lightning-sunbird  0.9+nobinonly
Classes | Defines | Functions
ipcdclient.h File Reference
#include "nscore.h"
#include "nsID.h"
#include "nsError.h"
#include "ipcIMessageObserver.h"
#include "ipcIClientObserver.h"
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  ipcDisableMessageObserverForScope
 This class can be used to temporarily disable the default message observer defined for a particular message target. More...

Defines

#define IPC_METHOD   NS_HIDDEN_(nsresult)
#define IPC_SENDER_ANY   PR_UINT32_MAX
#define IPC_WAIT_NEXT_MESSAGE   NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_GENERAL, 10)
#define IPC_ERROR_WOULD_BLOCK   NS_BASE_STREAM_WOULD_BLOCK
#define IPC_DISABLE_MESSAGE_OBSERVER_FOR_SCOPE(_t)   ipcDisableMessageObserverForScope ipc_dmo_for_scope##_t(_t)

Functions

IPC_METHOD IPC_Init ()
 Connects this process to the IPC daemon and initializes it for use as a client of the IPC daemon.
IPC_METHOD IPC_Shutdown ()
 Disconnects this process from the IPC daemon.
IPC_METHOD IPC_DefineTarget (const nsID &aTarget, ipcIMessageObserver *aObserver, PRBool aOnCurrentThread=PR_TRUE)
 Call this method to define a message target.
IPC_METHOD IPC_DisableMessageObserver (const nsID &aTarget)
 Call this method to temporarily disable the message observer configured for a message target.
IPC_METHOD IPC_EnableMessageObserver (const nsID &aTarget)
 Call this method to re-enable the message observer configured for a message target.
IPC_METHOD IPC_SendMessage (PRUint32 aReceiverID, const nsID &aTarget, const PRUint8 *aData, PRUint32 aDataLen)
 This function sends a message to the IPC daemon asynchronously.
IPC_METHOD IPC_WaitMessage (PRUint32 aSenderID, const nsID &aTarget, ipcIMessageObserver *aObserver=nsnull, PRIntervalTime aTimeout=PR_INTERVAL_NO_TIMEOUT)
 This function blocks the calling thread until a message for the given target is received (optionally from the specified client).
IPC_METHOD IPC_GetID (PRUint32 *aClientID)
 Returns the "ClientID" of the current process.
IPC_METHOD IPC_AddName (const char *aName)
 Adds a new name for the current process.
IPC_METHOD IPC_RemoveName (const char *aName)
 Removes a name associated with the current process.
IPC_METHOD IPC_AddClientObserver (ipcIClientObserver *aObserver)
 Adds client observer.
IPC_METHOD IPC_RemoveClientObserver (ipcIClientObserver *aObserver)
 Removes client observer.
IPC_METHOD IPC_ResolveClientName (const char *aName, PRUint32 *aClientID)
 Resolves the given client name to a client ID of a process connected to the IPC daemon.
IPC_METHOD IPC_ClientExists (PRUint32 aClientID, PRBool *aResult)
 Tests whether the client is connected to the IPC daemon.

Define Documentation

Definition at line 284 of file ipcdclient.h.

Definition at line 71 of file ipcdclient.h.

Definition at line 58 of file ipcdclient.h.

Definition at line 62 of file ipcdclient.h.

Definition at line 67 of file ipcdclient.h.


Function Documentation

Adds client observer.

Will be called on the main thread.

Definition at line 906 of file ipcdclient.cpp.

Here is the call graph for this function:

IPC_METHOD IPC_AddName ( const char *  aName)

Adds a new name for the current process.

The IPC daemon is notified of this change, which allows other processes to discover this process by the given name.

Definition at line 888 of file ipcdclient.cpp.

Here is the call graph for this function:

IPC_METHOD IPC_ClientExists ( PRUint32  aClientID,
PRBool aResult 
)

Tests whether the client is connected to the IPC daemon.

Definition at line 957 of file ipcdclient.cpp.

{
  // this is a bit of a hack.  we forward a PING to the specified client.
  // the assumption is that the forwarding will only succeed if the client
  // exists, so we wait for the RESULT message corresponding to the FORWARD
  // request.  if that gives a successful status, then we know that the
  // client exists.

  ipcmMessagePing ping;

  return MakeIPCMRequest(new ipcmMessageForward(IPCM_MSG_REQ_FORWARD,
                                                aClientID,
                                                IPCM_TARGET,
                                                ping.Data(),
                                                ping.DataLen()));
}

Here is the call graph for this function:

IPC_METHOD IPC_DefineTarget ( const nsID aTarget,
ipcIMessageObserver aObserver,
PRBool  aOnCurrentThread = PR_TRUE 
)

Call this method to define a message target.

A message target is defined by a UUID and a message observer. This observer is notified asynchronously whenever a message is sent to this target in this process.

This function has three main effects: o If the message target is already defined, then this function simply resets its message observer. o If the message target is not already defined, then the message target is defined and the IPC daemon is notified of the existance of this message target. o If null is passed for the message observer, then the message target is removed, and the daemon is notified of the removal of this message target.

If aOnCurrentThread is true, then notifications to the observer will occur on the current thread. This means that there must be a nsIEventTarget associated with the calling thread. If aOnCurrentThread is false, then notifications to the observer will occur on a background thread. In which case, the observer must be threadsafe.

Definition at line 727 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  // do not permit the re-definition of the IPCM protocol's target.
  if (aTarget.Equals(IPCM_TARGET))
    return NS_ERROR_INVALID_ARG;

  nsresult rv;

  nsRefPtr<ipcTargetData> td;
  if (GetTarget(aTarget, getter_AddRefs(td)))
  {
    // clear out observer before removing target since we want to ensure that
    // the observer is released on the main thread.
    {
      nsAutoMonitor mon(td->monitor);
      td->SetObserver(aObserver, aOnCurrentThread);
    }

    // remove target outside of td's monitor to avoid holding the monitor
    // while entering the client state's monitor.
    if (!aObserver)
      RemoveTarget(aTarget, PR_TRUE);

    rv = NS_OK;
  }
  else
  {
    if (aObserver)
      rv = DefineTarget(aTarget, aObserver, aOnCurrentThread, PR_TRUE, nsnull);
    else
      rv = NS_ERROR_INVALID_ARG; // unknown target
  }

  return rv;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Call this method to temporarily disable the message observer configured for a message target.

Definition at line 768 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  // do not permit modifications to the IPCM protocol's target.
  if (aTarget.Equals(IPCM_TARGET))
    return NS_ERROR_INVALID_ARG;

  DisableMessageObserver(aTarget);
  return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Call this method to re-enable the message observer configured for a message target.

Definition at line 781 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  // do not permit modifications to the IPCM protocol's target.
  if (aTarget.Equals(IPCM_TARGET))
    return NS_ERROR_INVALID_ARG;

  EnableMessageObserver(aTarget);
  return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

IPC_METHOD IPC_GetID ( PRUint32 aClientID)

Returns the "ClientID" of the current process.

Definition at line 879 of file ipcdclient.cpp.

Connects this process to the IPC daemon and initializes it for use as a client of the IPC daemon.

This function must be called once before any other methods defined in this file can be used.

Returns:
NS_ERROR_ALREADY_INITIALIZED if IPC_Shutdown was not called since the last time IPC_Init was called.

Definition at line 693 of file ipcdclient.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Removes client observer.

Definition at line 915 of file ipcdclient.cpp.

Here is the call graph for this function:

IPC_METHOD IPC_RemoveName ( const char *  aName)

Removes a name associated with the current process.

Definition at line 896 of file ipcdclient.cpp.

Here is the call graph for this function:

IPC_METHOD IPC_ResolveClientName ( const char *  aName,
PRUint32 aClientID 
)

Resolves the given client name to a client ID of a process connected to the IPC daemon.

Definition at line 932 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  ipcMessage *msg;

  nsresult rv = MakeIPCMRequest(new ipcmMessageQueryClientByName(aName), &msg);
  if (NS_FAILED(rv))
    return rv;

  if (IPCM_GetType(msg) == IPCM_MSG_ACK_CLIENT_ID)
    *aClientID = ipcMessageCast<ipcmMessageClientID>(msg)->ClientID();
  else
  {
    LOG(("unexpected IPCM response: type=%x\n", IPCM_GetType(msg)));
    rv = NS_ERROR_UNEXPECTED;
  }
    
  delete msg;
  return rv;
}

Here is the call graph for this function:

IPC_METHOD IPC_SendMessage ( PRUint32  aReceiverID,
const nsID aTarget,
const PRUint8 aData,
PRUint32  aDataLen 
)

This function sends a message to the IPC daemon asynchronously.

If aReceiverID is non-zero, then the message is forwarded to the client corresponding to that identifier.

If there is no client corresponding to aRecieverID, then the IPC daemon will simply drop the message.

Definition at line 794 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  // do not permit sending IPCM messages
  if (aTarget.Equals(IPCM_TARGET))
    return NS_ERROR_INVALID_ARG;

  nsresult rv;
  if (aReceiverID == 0)
  {
    ipcMessage *msg = new ipcMessage(aTarget, (const char *) aData, aDataLen);
    if (!msg)
      return NS_ERROR_OUT_OF_MEMORY;

    rv = IPC_SendMsg(msg);
  }
  else
    rv = MakeIPCMRequest(new ipcmMessageForward(IPCM_MSG_REQ_FORWARD,
                                                aReceiverID,
                                                aTarget,
                                                (const char *) aData,
                                                aDataLen));

  return rv;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Disconnects this process from the IPC daemon.

After this function is called, no other methods in this file except for IPC_Init may be called.

Returns:
NS_ERROR_NOT_INITIALIZED if IPC_Init has not been called or if IPC_Init did not return a success code.

Definition at line 711 of file ipcdclient.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

IPC_METHOD IPC_WaitMessage ( PRUint32  aSenderID,
const nsID aTarget,
ipcIMessageObserver aObserver = nsnull,
PRIntervalTime  aTimeout = PR_INTERVAL_NO_TIMEOUT 
)

This function blocks the calling thread until a message for the given target is received (optionally from the specified client).

The aSenderID parameter is interpreted as follows: o If aSenderID is 0, then this function waits for a message to be sent by the IPC daemon. o If aSenderID is IPC_SENDER_ANY, then this function waits for a message to be sent from any source. o Otherwise, this function waits for a message to be sent by the client with ID given by aSenderID. If aSenderID does not identify a valid client, then this function will return an error.

The aObserver parameter is interpreted as follows: o If aObserver is null, then the default message observer for the target is invoked when the next message is received. o Otherwise, aObserver will be inovked when the next message is received.

The aTimeout parameter is interpreted as follows: o If aTimeout is PR_INTERVAL_NO_TIMEOUT, then this function will block until a matching message is received. o If aTimeout is PR_INTERVAL_NO_WAIT, then this function will only inspect the current queue of messages. If no matching message is found, then IPC_ERROR_WOULD_BLOCK is returned. o Otherwise, aTimeout specifies the maximum amount of time to wait for a matching message to be received. If no matching message is found after the timeout expires, then IPC_ERROR_WOULD_BLOCK is returned.

If aObserver's OnMessageAvailable function returns IPC_WAIT_NEXT_MESSAGE, then the function will continue blocking until the next matching message is received. Bypassed messages will be dispatched to the default message observer when the event queue, associated with the thread that called IPC_DefineTarget, is processed.

This function runs the risk of hanging the calling thread indefinitely if no matching message is ever received.

Definition at line 854 of file ipcdclient.cpp.

{
  NS_ENSURE_TRUE(gClientState, NS_ERROR_NOT_INITIALIZED);

  // do not permit waiting for IPCM messages
  if (aTarget.Equals(IPCM_TARGET))
    return NS_ERROR_INVALID_ARG;

  WaitMessageSelectorData data = { aSenderID, aObserver };

  ipcMessage *msg;
  nsresult rv = WaitTarget(aTarget, aTimeout, &msg, WaitMessageSelector, &data);
  if (NS_FAILED(rv))
    return rv;
  delete msg;

  return NS_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function: