Back to index

lightning-sunbird  0.9+nobinonly
ipcdclient.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is Mozilla IPC.
00015  *
00016  * The Initial Developer of the Original Code is IBM Corporation.
00017  * Portions created by the Initial Developer are Copyright (C) 2004
00018  * the Initial Developer. All Rights Reserved.
00019  *
00020  * Contributor(s):
00021  *   Darin Fisher <darin@meer.net>
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef ipcdclient_h__
00038 #define ipcdclient_h__
00039 
00040 /*****************************************************************************
00041  * This file provides a client-side API to the IPC daemon.
00042  *
00043  * This API can be used to communicate with other clients of the IPC daemon
00044  * as well as modules running inside the IPC daemon.
00045  *
00046  * This API is meant to be used only on the application's main thread.  It is
00047  * assumed that callbacks can be dispatched via the main thread's event queue.
00048  */
00049 
00050 #include "nscore.h"
00051 #include "nsID.h"
00052 #include "nsError.h"
00053 #include "ipcIMessageObserver.h"
00054 #include "ipcIClientObserver.h"
00055 
00056 /* This API is only provided for the extensions compiled into the IPCDC
00057  * library, hence this API is hidden in the final DSO. */
00058 #define IPC_METHOD NS_HIDDEN_(nsresult)
00059 
00060 /* This value can be used to represent the client id of any client connected
00061  * to the IPC daemon. */
00062 #define IPC_SENDER_ANY PR_UINT32_MAX
00063 
00064 /* This error code can only be returned by OnMessageAvailable, when called by
00065  * IPC_WaitMessage.  See IPC_WaitMessage for a description of how this error
00066  * code may be used. */
00067 #define IPC_WAIT_NEXT_MESSAGE \
00068   NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_GENERAL, 10)
00069 
00070 /* This error code is returned by IPC_WaitMessage under certain conditions. */
00071 #define IPC_ERROR_WOULD_BLOCK NS_BASE_STREAM_WOULD_BLOCK
00072 
00073 /*****************************************************************************
00074  * Initialization and Shutdown
00075  */
00076 
00077 // XXX limit these to the main thread, and call them from our module's ctor/dtor?
00078 
00087 IPC_METHOD IPC_Init();
00088 
00096 IPC_METHOD IPC_Shutdown();
00097 
00098 
00099 /*****************************************************************************
00100  * The core messaging API
00101  */
00102 
00123 IPC_METHOD IPC_DefineTarget(
00124   const nsID          &aTarget,
00125   ipcIMessageObserver *aObserver,
00126   PRBool               aOnCurrentThread = PR_TRUE
00127 );
00128 
00133 IPC_METHOD IPC_DisableMessageObserver(
00134   const nsID          &aTarget
00135 );
00136 
00141 IPC_METHOD IPC_EnableMessageObserver(
00142   const nsID          &aTarget
00143 );
00144 
00153 IPC_METHOD IPC_SendMessage(
00154   PRUint32             aReceiverID,
00155   const nsID          &aTarget,
00156   const PRUint8       *aData,
00157   PRUint32             aDataLen
00158 );
00159 
00197 IPC_METHOD IPC_WaitMessage(
00198   PRUint32             aSenderID,
00199   const nsID          &aTarget,
00200   ipcIMessageObserver *aObserver = nsnull,
00201   PRIntervalTime       aTimeout = PR_INTERVAL_NO_TIMEOUT
00202 );
00203 
00204 /*****************************************************************************/
00205 
00209 IPC_METHOD IPC_GetID(
00210   PRUint32 *aClientID
00211 );
00212 
00218 IPC_METHOD IPC_AddName(
00219   const char *aName
00220 );
00221 
00225 IPC_METHOD IPC_RemoveName(
00226   const char *aName
00227 );
00228 
00232 IPC_METHOD IPC_AddClientObserver(
00233   ipcIClientObserver *aObserver
00234 );
00235 
00239 IPC_METHOD IPC_RemoveClientObserver(
00240   ipcIClientObserver *aObserver
00241 );
00242 
00247 IPC_METHOD IPC_ResolveClientName(
00248   const char *aName,
00249   PRUint32   *aClientID
00250 );
00251 
00255 IPC_METHOD IPC_ClientExists(
00256   PRUint32  aClientID,
00257   PRBool   *aResult
00258 );
00259 
00260 /*****************************************************************************/
00261 
00266 class ipcDisableMessageObserverForScope
00267 {
00268 public:
00269   ipcDisableMessageObserverForScope(const nsID &aTarget)
00270     : mTarget(aTarget)
00271   {
00272     IPC_DisableMessageObserver(mTarget);
00273   }
00274 
00275   ~ipcDisableMessageObserverForScope()
00276   {
00277     IPC_EnableMessageObserver(mTarget);
00278   }
00279 
00280 private:
00281   const nsID &mTarget;
00282 };
00283 
00284 #define IPC_DISABLE_MESSAGE_OBSERVER_FOR_SCOPE(_t) \
00285   ipcDisableMessageObserverForScope ipc_dmo_for_scope##_t(_t)
00286 
00287 #endif /* ipcdclient_h__ */