diff options
Diffstat (limited to '')
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__ */ |