Back to index

lightning-sunbird  0.9+nobinonly
ipcMessage.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
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 2002
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *   Darin Fisher <darin@netscape.com>
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef ipcMessage_h__
00039 #define ipcMessage_h__
00040 
00041 #include "nsID.h"
00042 
00043 //
00044 // ipc message format:
00045 //
00046 //   +------------------------------------+
00047 //   | DWORD : length                     |
00048 //   +------------------+-----------------+
00049 //   | WORD  : version  | WORD : flags    |
00050 //   +------------------+-----------------+
00051 //   | nsID  : target                     |
00052 //   +------------------------------------+
00053 //   | data                               |
00054 //   +------------------------------------+
00055 //
00056 // header is 24 bytes.  flags are defined below.  default value of flags is
00057 // zero.  protocol implementations should ignore unrecognized flags.  target
00058 // is a 16 byte UUID indicating the intended receiver of this message.
00059 //
00060 
00061 struct ipcMessageHeader
00062 {
00063     PRUint32 mLen;
00064     PRUint16 mVersion;
00065     PRUint16 mFlags;
00066     nsID     mTarget;
00067 };
00068 
00069 #define IPC_MSG_VERSION       (0x1)
00070 #define IPC_MSG_HEADER_SIZE   (sizeof(ipcMessageHeader))
00071 #define IPC_MSG_GUESSED_SIZE  (IPC_MSG_HEADER_SIZE + 64)
00072 
00073 //
00074 // the IPC message protocol supports synchronous messages.  these messages can
00075 // only be sent from a client to the daemon.  a daemon module cannot send a
00076 // synchronous message.  the client sets the SYNC_QUERY flag to indicate that
00077 // it is expecting a response with the SYNC_REPLY flag set.
00078 //
00079 #define IPC_MSG_FLAG_SYNC_QUERY (0x1)
00080 #define IPC_MSG_FLAG_SYNC_REPLY (0x2)
00081 
00082 //-----------------------------------------------------------------------------
00083 // ipcMessage
00084 //-----------------------------------------------------------------------------
00085 
00086 class ipcMessage
00087 {
00088 public:
00089     ipcMessage()
00090         : mNext(NULL)
00091         , mMetaData(0)
00092         , mMsgHdr(NULL)
00093         , mMsgOffset(0)
00094         , mMsgComplete(PR_FALSE)
00095         { }
00096     ipcMessage(const nsID &target, const char *data, PRUint32 dataLen)
00097         : mNext(NULL)
00098         , mMetaData(0)
00099         , mMsgHdr(NULL)
00100         , mMsgOffset(0)
00101         { Init(target, data, dataLen); }
00102    ~ipcMessage() NS_HIDDEN;
00103 
00104     //
00105     // reset message to uninitialized state
00106     //
00107     NS_HIDDEN_(void) Reset();
00108 
00109     // 
00110     // create a copy of this message
00111     //
00112     NS_HIDDEN_(ipcMessage *) Clone() const;
00113 
00114     //
00115     // initialize message
00116     //
00117     // param:
00118     //   topic   - message topic string
00119     //   data    - message data (may be null to leave data uninitialized)
00120     //   dataLen - message data len
00121     //
00122     NS_HIDDEN_(PRStatus) Init(const nsID &target, const char *data, PRUint32 dataLen);
00123 
00124     //
00125     // copy data into the message's data section, starting from offset.  this
00126     // function can be used to write any portion of the message's data.
00127     //
00128     // param:
00129     //   offset  - destination offset
00130     //   data    - data to write
00131     //   dataLen - number of bytes to write
00132     //
00133     NS_HIDDEN_(PRStatus) SetData(PRUint32 offset, const char *data, PRUint32 dataLen);
00134 
00135     //
00136     // access message flags
00137     //
00138     void SetFlag(PRUint16 flag)          { mMsgHdr->mFlags |= flag; }
00139     void ClearFlag(PRUint16 flag)        { mMsgHdr->mFlags &= ~flag; }
00140     PRBool TestFlag(PRUint16 flag) const { return mMsgHdr->mFlags & flag; }
00141 
00142     //
00143     // if true, the message is complete and the members of the message
00144     // can be accessed.
00145     //
00146     PRBool IsComplete() const { return mMsgComplete; }
00147 
00148     //
00149     // readonly accessors
00150     //
00151     const ipcMessageHeader *Header()  const { return mMsgHdr; }
00152     const nsID             &Target()  const { return mMsgHdr->mTarget; }
00153     const char             *Data()    const { return (char *) mMsgHdr + IPC_MSG_HEADER_SIZE; }
00154     PRUint32                DataLen() const { return mMsgHdr->mLen - IPC_MSG_HEADER_SIZE; }
00155     const char             *MsgBuf()  const { return (char *) mMsgHdr; }
00156     PRUint32                MsgLen()  const { return mMsgHdr->mLen; }
00157 
00158     //
00159     // message comparison functions
00160     //
00161     // param:
00162     //   topic   - message topic (may be null)
00163     //   data    - message data (must not be null)
00164     //   dataLen - message data length 
00165     //
00166     NS_HIDDEN_(PRBool) Equals(const nsID &target, const char *data, PRUint32 dataLen) const;
00167     NS_HIDDEN_(PRBool) Equals(const ipcMessage *msg) const;
00168 
00169     //
00170     // write the message to a buffer segment; segment need not be large
00171     // enough to hold entire message.  called repeatedly.
00172     //
00173     NS_HIDDEN_(PRStatus) WriteTo(char     *buf,
00174                                  PRUint32  bufLen,
00175                                  PRUint32 *bytesWritten,
00176                                  PRBool   *complete);
00177 
00178     //
00179     // read the message from a buffer segment; segment need not contain
00180     // the entire messgae.  called repeatedly.
00181     //
00182     NS_HIDDEN_(PRStatus) ReadFrom(const char *buf,
00183                                   PRUint32    bufLen,
00184                                   PRUint32   *bytesRead,
00185                                   PRBool     *complete);
00186 
00187     //
00188     // a message can be added to a singly-linked list.
00189     //
00190     class ipcMessage *mNext;
00191 
00192     //
00193     // meta data associated with this message object.  the owner of the
00194     // ipcMessage object is free to use this field for any purpose.  by
00195     // default, it is initialized to 0.
00196     //
00197     PRUint32          mMetaData;
00198 
00199 private:
00200     ipcMessageHeader *mMsgHdr;
00201 
00202     // XXX document me
00203     PRUint32          mMsgOffset;
00204     PRPackedBool      mMsgComplete;
00205 };
00206 
00207 #endif // !ipcMessage_h__