summaryrefslogtreecommitdiffstats
path: root/src/libs/xpcom18a4/ipc/ipcd/client/public
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
commit16f504a9dca3fe3b70568f67b7d41241ae485288 (patch)
treec60f36ada0496ba928b7161059ba5ab1ab224f9d /src/libs/xpcom18a4/ipc/ipcd/client/public
parentInitial commit. (diff)
downloadvirtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.tar.xz
virtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.zip
Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/libs/xpcom18a4/ipc/ipcd/client/public')
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/.cvsignore1
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/Makefile.in59
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/ipcCID.h53
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIClientObserver.idl51
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIMessageObserver.idl64
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIService.idl228
-rw-r--r--src/libs/xpcom18a4/ipc/ipcd/client/public/ipcdclient.h326
7 files changed, 782 insertions, 0 deletions
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/.cvsignore b/src/libs/xpcom18a4/ipc/ipcd/client/public/.cvsignore
new file mode 100644
index 00000000..f3c7a7c5
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/.cvsignore
@@ -0,0 +1 @@
+Makefile
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/Makefile.in b/src/libs/xpcom18a4/ipc/ipcd/client/public/Makefile.in
new file mode 100644
index 00000000..896e68b8
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/Makefile.in
@@ -0,0 +1,59 @@
+# vim: noexpandtab ts=4 sw=4
+# ***** 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 IPC.
+#
+# The Initial Developer of the Original Code is
+# Netscape Communications Corporation.
+# Portions created by the Initial Developer are Copyright (C) 2002
+# the Initial Developer. All Rights Reserved.
+#
+# Contributor(s):
+# Darin Fisher <darin@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 *****
+
+DEPTH = ../../../..
+topsrcdir = @top_srcdir@
+srcdir = @srcdir@
+VPATH = @srcdir@
+
+include $(DEPTH)/config/autoconf.mk
+
+MODULE = ipcd
+
+EXPORTS = \
+ ipcdclient.h \
+ ipcCID.h \
+ $(NULL)
+
+XPIDLSRCS = \
+ ipcIService.idl \
+ ipcIMessageObserver.idl \
+ ipcIClientObserver.idl \
+ $(NULL)
+
+include $(topsrcdir)/config/rules.mk
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcCID.h b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcCID.h
new file mode 100644
index 00000000..4863ff0d
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcCID.h
@@ -0,0 +1,53 @@
+/* ***** 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 IPC.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 2002
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ * Darin Fisher <darin@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 ipcCID_h__
+#define ipcCID_h__
+
+#define IPC_SERVICE_CLASSNAME \
+ "ipcService"
+#define IPC_SERVICE_CONTRACTID \
+ "@mozilla.org/ipc/service;1"
+#define IPC_SERVICE_CID \
+{ /* 9f12676a-5168-4a08-beb8-edf8a593a1ca */ \
+ 0x9f12676a, \
+ 0x5168, \
+ 0x4a08, \
+ {0xbe, 0xb8, 0xed, 0xf8, 0xa5, 0x93, 0xa1, 0xca} \
+}
+
+#endif // !ipcCID_h__
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIClientObserver.idl b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIClientObserver.idl
new file mode 100644
index 00000000..c72d0909
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIClientObserver.idl
@@ -0,0 +1,51 @@
+/* ***** 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 IPC.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 2002
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ * Darin Fisher <darin@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 ***** */
+
+#include "nsISupports.idl"
+
+/**
+ * ipcIClientObserver
+ */
+[scriptable, uuid(42283079-030c-4b13-b069-a08b7ad5eab2)]
+interface ipcIClientObserver : nsISupports
+{
+ const unsigned long CLIENT_UP = 1;
+ const unsigned long CLIENT_DOWN = 2;
+
+ void onClientStateChange(in unsigned long aClientID,
+ in unsigned long aClientState);
+};
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIMessageObserver.idl b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIMessageObserver.idl
new file mode 100644
index 00000000..db24b1f2
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIMessageObserver.idl
@@ -0,0 +1,64 @@
+/* ***** 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 IPC.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 2002
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ * Darin Fisher <darin@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 ***** */
+
+#include "nsISupports.idl"
+
+/**
+ * ipcIMessageObserver
+ */
+[scriptable, uuid(e40a4a3c-2dc1-470e-ab7f-5675fe1f1384)]
+interface ipcIMessageObserver : nsISupports
+{
+ /**
+ * @param aSenderID
+ * the 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.
+ * @param aTarget
+ * the 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.
+ * @param aData
+ * the data of the message.
+ * @param aDataLen
+ * the data length of the message.
+ */
+ void onMessageAvailable(in unsigned long aSenderID,
+ in nsIDRef aTarget,
+ [array, const, size_is(aDataLen)]
+ in octet aData,
+ in unsigned long aDataLen);
+};
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIService.idl b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIService.idl
new file mode 100644
index 00000000..671b557d
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcIService.idl
@@ -0,0 +1,228 @@
+/* ***** 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 IPC.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 2002
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ * Darin Fisher <darin@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 ***** */
+
+#include "nsISupports.idl"
+
+interface ipcIMessageObserver;
+interface ipcIClientObserver;
+
+/**
+ * ipcIService
+ *
+ * the IPC service provides the means to communicate with an external IPC
+ * daemon and/or other mozilla-based applications on the same physical system.
+ * the IPC daemon hosts modules (some builtin and others dynamically loaded)
+ * with which applications may interact.
+ *
+ * at application startup, the IPC service will attempt to establish a
+ * connection with the IPC daemon. the IPC daemon will be automatically
+ * started if necessary. when a connection has been established, the IPC
+ * service will enumerate the "ipc-startup-category" and broadcast an
+ * "ipc-startup" notification using the observer service.
+ *
+ * when the connection to the IPC daemon is closed, an "ipc-shutdown"
+ * notification will be broadcast.
+ *
+ * each client has a name. the client name need not be unique across all
+ * clients, but it is usually good if it is. the IPC service does not require
+ * unique names. instead, the IPC daemon assigns each client a unique ID that
+ * is good for the current "session." clients can query other clients by name
+ * or by ID. the IPC service supports forwarding messages from one client to
+ * another via the IPC daemon.
+ *
+ * for performance reasons, this system should not be used to transfer large
+ * amounts of data. instead, applications may choose to utilize shared memory,
+ * and rely on the IPC service for synchronization and small message transfer
+ * only.
+ */
+[scriptable, uuid(53d3e3a7-528f-4b09-9eab-9416272568c0)]
+interface ipcIService : nsISupports
+{
+ /**************************************************************************
+ * properties of this process
+ */
+
+ /**
+ * returns the "client ID" assigned to this process by the IPC daemon.
+ *
+ * @throws NS_ERROR_NOT_AVAILABLE if no connection to the IPC daemon.
+ */
+ readonly attribute unsigned long ID;
+
+ /**
+ * this process can appear under several client names. use the following
+ * methods to add or remove names for this process.
+ *
+ * for example, the mozilla browser might have the primary name "mozilla",
+ * but it could also register itself under the names "browser", "mail",
+ * "news", "addrbook", etc. other IPC clients can then query the IPC
+ * daemon for the client named "mail" in order to talk with a mail program.
+ *
+ * XXX An IPC client name resembles a XPCOM contract ID.
+ */
+ void addName(in string aName);
+ void removeName(in string aName);
+
+ /**
+ * add a new observer of client status change notifications.
+ */
+ void addClientObserver(in ipcIClientObserver aObserver);
+
+ /**
+ * remove an observer of client status change notifications.
+ */
+ void removeClientObserver(in ipcIClientObserver aObserver);
+
+ /**************************************************************************
+ * client query methods
+ */
+
+ /**
+ * resolve the given client name to the id of a connected client. this
+ * involves a round trip to the daemon, and as a result the calling thread
+ * may block on this function call while waiting for the daemon to respond.
+ */
+ unsigned long resolveClientName(in string aName);
+
+
+ /**
+ * tests whether a particular client is connected to the IPC daemon.
+ */
+ boolean clientExists(in unsigned long aClientID);
+
+
+ // XXX need other functions to enumerate clients, clients implementing targets, etc.
+ // enumerator getClients();
+ // enumerator getClientsSupportingTarget(in nsIDRef aTarget);
+ // enumerator getClientNames(in unsigned long aClientID);
+ // enumerator getClientTargets(in unsigned long aClientID);
+
+
+ /**************************************************************************
+ * message methods
+ */
+
+ /**
+ * set a message observer for a particular message target.
+ *
+ * @param aTarget
+ * the message target being observed. any existing observer will
+ * be replaced.
+ * @param aObserver
+ * the message observer to receive incoming messages for the
+ * specified target. pass null to remove the existing observer.
+ * @param aOnCurrentThread
+ * if true, then the message observer will be called on the same
+ * thread that calls defineTarget. otherwise, aObserver will be
+ * called on a background thread.
+ */
+ void defineTarget(in nsIDRef aTarget,
+ in ipcIMessageObserver aObserver,
+ in boolean aOnCurrentThread);
+
+ /**
+ * send message asynchronously to a client or a module in the IPC daemon.
+ * there is no guarantee that the message will be delivered.
+ *
+ * @param aClientID
+ * the client ID of the foreign application that should receive this
+ * message. pass 0 to send a message to a module in the IPC daemon.
+ * @param aTarget
+ * the target of the message. if aClientID is 0, then this is the
+ * ID of the daemon module that should receive this message.
+ * @param aData
+ * the message data.
+ * @param aDataLen
+ * the message length.
+ */
+ void sendMessage(in unsigned long aReceiverID,
+ in nsIDRef aTarget,
+ [array, const, size_is(aDataLen)]
+ in octet aData,
+ in unsigned long aDataLen);
+
+ /**
+ * block the calling thread until a matching message is received.
+ *
+ * @param aSenderID
+ * pass 0 to wait for a message from the daemon. pass PR_UINT32_MAX
+ * to wait for a message from any source. otherwise, pass a client
+ * id to wait for a message from that particular client.
+ * @param aTarget
+ * wait for a message to be delivered to this target.
+ * @param aObserver
+ * this observer's OnMessageAvailable method is called when a
+ * matching message is available. pass null to use the default
+ * observer associated with aTarget.
+ * @param aTimeout
+ * indicates maximum length of time in milliseconds that this
+ * function may block the calling thread.
+ *
+ * @throws IPC_ERROR_WOULD_BLOCK if the timeout expires.
+ *
+ * the observer's OnMessageAvailable method may throw IPC_WAIT_NEXT_MESSAGE
+ * to indicate that it does not wish to handle the message that it was
+ * given, and that it will wait to be called with the next message. this
+ * enables the observer to keep messages in the queue that do not match the
+ * desired message. messages that remain in the queue will be dispatched
+ * asynchronously to the default message handler after waitMessage finishes.
+ *
+ * NOTE: this function may hang the calling thread until a matching message
+ * is received, so use it with caution.
+ */
+ void waitMessage(in unsigned long aSenderID,
+ in nsIDRef aTarget,
+ in ipcIMessageObserver aObserver,
+ in unsigned long aTimeout);
+
+ /**
+ * Call this method to disable the default message observer for a target.
+ */
+ void disableMessageObserver(in nsIDRef aTarget);
+
+ /**
+ * Call this method to re-enable the default message observer for a target.
+ */
+ void enableMessageObserver(in nsIDRef aTarget);
+};
+
+%{C++
+// category and observer event defines (XXX not yet implemented)
+#define IPC_SERVICE_STARTUP_CATEGORY "ipc-startup-category"
+#define IPC_SERVICE_STARTUP_TOPIC "ipc-startup"
+#define IPC_SERVICE_SHUTDOWN_TOPIC "ipc-shutdown"
+%}
diff --git a/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcdclient.h b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcdclient.h
new file mode 100644
index 00000000..5cbed879
--- /dev/null
+++ b/src/libs/xpcom18a4/ipc/ipcd/client/public/ipcdclient.h
@@ -0,0 +1,326 @@
+/* ***** 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 IPC.
+ *
+ * The Initial Developer of the Original Code is IBM Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 2004
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ * Darin Fisher <darin@meer.net>
+ *
+ * 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 ipcdclient_h__
+#define ipcdclient_h__
+
+/*****************************************************************************
+ * This file provides a client-side API to the IPC daemon.
+ *
+ * This API can be used to communicate with other clients of the IPC daemon
+ * as well as modules running inside the IPC daemon.
+ *
+ * This API is meant to be used only on the application's main thread. It is
+ * assumed that callbacks can be dispatched via the main thread's event queue.
+ */
+
+#include "nscore.h"
+#include "nsID.h"
+#include "nsError.h"
+#include "ipcIMessageObserver.h"
+#include "ipcIClientObserver.h"
+
+/* This API is only provided for the extensions compiled into the IPCDC
+ * library, hence this API is hidden in the final DSO. */
+#define IPC_METHOD NS_HIDDEN_(nsresult)
+
+/* This value can be used to represent the client id of any client connected
+ * to the IPC daemon. */
+#define IPC_SENDER_ANY PR_UINT32_MAX
+
+/* This error code can only be returned by OnMessageAvailable, when called by
+ * IPC_WaitMessage. See IPC_WaitMessage for a description of how this error
+ * code may be used. */
+#define IPC_WAIT_NEXT_MESSAGE \
+ NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_GENERAL, 10)
+
+#ifdef VBOX
+/* This error code can only be returned by the selector functions called by
+ * WaitTarget. The message should be dropped without processing. */
+#define IPC_DISCARD_MESSAGE \
+ NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_GENERAL, 12)
+#endif /* VBOX */
+
+/* This error code is returned by IPC_WaitMessage under certain conditions. */
+#define IPC_ERROR_WOULD_BLOCK NS_BASE_STREAM_WOULD_BLOCK
+
+/*****************************************************************************
+ * Initialization and Shutdown
+ */
+
+// XXX limit these to the main thread, and call them from our module's ctor/dtor?
+
+/**
+ * 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.
+ */
+IPC_METHOD IPC_Init();
+
+/**
+ * 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.
+ *
+ * This function calls all client observers (registered with
+ * IPC_AddClientObserver) before it actually disconnects from the IPC daemon,
+ * with aClientID parameter of the OnClientStateChange callback specially
+ * set to IPC_SENDER_ANY and aClientState set to CLIENT_DOWN. This gives
+ * the interested party an opportunity to perform a proper shutdown procedure.
+ * All IPC methods are still available inside OnClientStateChange call except
+ * the IPC_WaitMessage function, that will immediately fail with an error.
+ * OnClientStateChange is called on the same thread where this function is
+ * called.
+ *
+ * @returns NS_ERROR_NOT_INITIALIZED if IPC_Init has not been called or if
+ * IPC_Init did not return a success code.
+ */
+IPC_METHOD IPC_Shutdown();
+
+
+/*****************************************************************************
+ * The core messaging API
+ */
+
+/**
+ * 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.
+ */
+IPC_METHOD IPC_DefineTarget(
+ const nsID &aTarget,
+ ipcIMessageObserver *aObserver,
+ PRBool aOnCurrentThread = PR_TRUE
+);
+
+/**
+ * Call this method to temporarily disable the message observer configured
+ * for a message target.
+ */
+IPC_METHOD IPC_DisableMessageObserver(
+ const nsID &aTarget
+);
+
+/**
+ * Call this method to re-enable the message observer configured for a
+ * message target.
+ */
+IPC_METHOD IPC_EnableMessageObserver(
+ const nsID &aTarget
+);
+
+/**
+ * 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.
+ */
+IPC_METHOD IPC_SendMessage(
+ PRUint32 aReceiverID,
+ const nsID &aTarget,
+ const PRUint8 *aData,
+ PRUint32 aDataLen
+);
+
+/**
+ * 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, or if the client dies while waiting, 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 aConsumer parameter is interpreted as follows:
+ * o If aObserver is null or aConsumer is null, this parameter is ignored.
+ * o Otherwise, aConsumer will be invoked right after (and only if) aObserver
+ * has accepted some message. It will receive exactly the same message
+ * that was accepted by aObserver.
+ *
+ * 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.
+ *
+ * There is a special case if aSenderID is IPC_SENDER_ANY and one of IPC clients
+ * dies while this function waits for a message. In this case, aObserver's
+ * OnMessageAvailable function is called with a special set of arguments:
+ * dead client id, empty target id and null message (both data and data length
+ * are zeroes). If it returns IPC_WAIT_NEXT_MESSAGE, IPC_WaitMessage continues
+ * blocking as usual, otherwise an error is immediately returned to the caller.
+ *
+ * aObserver is not expected to use any IPC system functons from within its
+ * OnMessageAvailable implementation. This is because the IPC system is not
+ * re-entrant during invocation of OnMessageAvailable function, and making other
+ * IPC calls can lead to unexpected results (like message losses or traps). On
+ * the contrary, aConsumer's OnMessageAvailable function is allowed to use the
+ * IPC system without any limitations.
+ *
+ * This function runs the risk of hanging the calling thread indefinitely if
+ * no matching message is ever received.
+ */
+IPC_METHOD IPC_WaitMessage(
+ PRUint32 aSenderID,
+ const nsID &aTarget,
+ ipcIMessageObserver *aObserver = nsnull,
+ ipcIMessageObserver *aConsumer = nsnull,
+ PRIntervalTime aTimeout = PR_INTERVAL_NO_TIMEOUT
+);
+
+/*****************************************************************************/
+
+/**
+ * Returns the "ClientID" of the current process.
+ */
+IPC_METHOD IPC_GetID(
+ PRUint32 *aClientID
+);
+
+/**
+ * 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.
+ */
+IPC_METHOD IPC_AddName(
+ const char *aName
+);
+
+/**
+ * Removes a name associated with the current process.
+ */
+IPC_METHOD IPC_RemoveName(
+ const char *aName
+);
+
+/**
+ * Adds client observer. Will be called on the main thread.
+ */
+IPC_METHOD IPC_AddClientObserver(
+ ipcIClientObserver *aObserver
+);
+
+/**
+ * Removes client observer.
+ */
+IPC_METHOD IPC_RemoveClientObserver(
+ ipcIClientObserver *aObserver
+);
+
+/**
+ * Resolves the given client name to a client ID of a process connected to
+ * the IPC daemon.
+ */
+IPC_METHOD IPC_ResolveClientName(
+ const char *aName,
+ PRUint32 *aClientID
+);
+
+/**
+ * Tests whether the client is connected to the IPC daemon.
+ */
+IPC_METHOD IPC_ClientExists(
+ PRUint32 aClientID,
+ PRBool *aResult
+);
+
+/*****************************************************************************/
+
+/**
+ * This class can be used to temporarily disable the default message observer
+ * defined for a particular message target.
+ */
+class ipcDisableMessageObserverForScope
+{
+public:
+ ipcDisableMessageObserverForScope(const nsID &aTarget)
+ : mTarget(aTarget)
+ {
+ IPC_DisableMessageObserver(mTarget);
+ }
+
+ ~ipcDisableMessageObserverForScope()
+ {
+ IPC_EnableMessageObserver(mTarget);
+ }
+
+private:
+ const nsID &mTarget;
+};
+
+#define IPC_DISABLE_MESSAGE_OBSERVER_FOR_SCOPE(_t) \
+ ipcDisableMessageObserverForScope ipc_dmo_for_scope##_t(_t)
+
+#endif /* ipcdclient_h__ */