ipc/ipcd/shared/src/ipcMessage.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Mozilla IPC.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 2002
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Darin Fisher <darin@netscape.com>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef ipcMessage_h__
  39 #define ipcMessage_h__
  40
  41 #include "nsID.h"
  42
  43 //
  44 // ipc message format:
  45 //
  46 //   +------------------------------------+
  47 //   | DWORD : length                     |
  48 //   +------------------+-----------------+
  49 //   | WORD  : version  | WORD : flags    |
  50 //   +------------------+-----------------+
  51 //   | nsID  : target                     |
  52 //   +------------------------------------+
  53 //   | data                               |
  54 //   +------------------------------------+
  55 //
  56 // header is 24 bytes.  flags are defined below.  default value of flags is
  57 // zero.  protocol implementations should ignore unrecognized flags.  target
  58 // is a 16 byte UUID indicating the intended receiver of this message.
  59 //
  60
  61 struct ipcMessageHeader
  62 {
  63     PRUint32 mLen;
  64     PRUint16 mVersion;
  65     PRUint16 mFlags;
  66     nsID     mTarget;
  67 };
  68
  69 #define IPC_MSG_VERSION       (0x1)
  70 #define IPC_MSG_HEADER_SIZE   (sizeof(ipcMessageHeader))
  71 #define IPC_MSG_GUESSED_SIZE  (IPC_MSG_HEADER_SIZE + 64)
  72
  73 //
  74 // the IPC message protocol supports synchronous messages.  these messages can
  75 // only be sent from a client to the daemon.  a daemon module cannot send a
  76 // synchronous message.  the client sets the SYNC_QUERY flag to indicate that
  77 // it is expecting a response with the SYNC_REPLY flag set.
  78 //
  79 #define IPC_MSG_FLAG_SYNC_QUERY (0x1)
  80 #define IPC_MSG_FLAG_SYNC_REPLY (0x2)
  81
  82 //-----------------------------------------------------------------------------
  83 // ipcMessage
  84 //-----------------------------------------------------------------------------
  85
  86 class ipcMessage
  87 {
  88 public:
  89     ipcMessage()
  90         : mNext(NULL)
  91         , mMetaData(0)
  92         , mMsgHdr(NULL)
  93         , mMsgOffset(0)
  94         , mMsgComplete(PR_FALSE)
  95         { }
  96     ipcMessage(const nsID &target, const char *data, PRUint32 dataLen)
  97         : mNext(NULL)
  98         , mMetaData(0)
  99         , mMsgHdr(NULL)
 100         , mMsgOffset(0)
 101         { Init(target, data, dataLen); }
 102    ~ipcMessage() NS_HIDDEN;
 103
 104     //
 105     // reset message to uninitialized state
 106     //
 107     NS_HIDDEN_(void) Reset();
 108
 109     //
 110     // create a copy of this message
 111     //
 112     NS_HIDDEN_(ipcMessage *) Clone() const;
 113
 114     //
 115     // initialize message
 116     //
 117     // param:
 118     //   topic   - message topic string
 119     //   data    - message data (may be null to leave data uninitialized)
 120     //   dataLen - message data len
 121     //
 122     NS_HIDDEN_(PRStatus) Init(const nsID &target, const char *data, PRUint32 dataLen);
 123
 124     //
 125     // copy data into the message's data section, starting from offset.  this
 126     // function can be used to write any portion of the message's data.
 127     //
 128     // param:
 129     //   offset  - destination offset
 130     //   data    - data to write
 131     //   dataLen - number of bytes to write
 132     //
 133     NS_HIDDEN_(PRStatus) SetData(PRUint32 offset, const char *data, PRUint32 dataLen);
 134
 135     //
 136     // access message flags
 137     //
 138     void SetFlag(PRUint16 flag)          { mMsgHdr->mFlags |= flag; }
 139     void ClearFlag(PRUint16 flag)        { mMsgHdr->mFlags &= ~flag; }
 140     PRBool TestFlag(PRUint16 flag) const { return mMsgHdr->mFlags & flag; }
 141
 142     //
 143     // if true, the message is complete and the members of the message
 144     // can be accessed.
 145     //
 146     PRBool IsComplete() const { return mMsgComplete; }
 147
 148     //
 149     // readonly accessors
 150     //
 151     const ipcMessageHeader *Header()  const { return mMsgHdr; }
 152     const nsID             &Target()  const { return mMsgHdr->mTarget; }
 153     const char             *Data()    const { return (char *) mMsgHdr + IPC_MSG_HEADER_SIZE; }
 154     PRUint32                DataLen() const { return mMsgHdr->mLen - IPC_MSG_HEADER_SIZE; }
 155     const char             *MsgBuf()  const { return (char *) mMsgHdr; }
 156     PRUint32                MsgLen()  const { return mMsgHdr->mLen; }
 157
 158     //
 159     // message comparison functions
 160     //
 161     // param:
 162     //   topic   - message topic (may be null)
 163     //   data    - message data (must not be null)
 164     //   dataLen - message data length
 165     //
 166     NS_HIDDEN_(PRBool) Equals(const nsID &target, const char *data, PRUint32 dataLen) const;
 167     NS_HIDDEN_(PRBool) Equals(const ipcMessage *msg) const;
 168
 169     //
 170     // write the message to a buffer segment; segment need not be large
 171     // enough to hold entire message.  called repeatedly.
 172     //
 173     NS_HIDDEN_(PRStatus) WriteTo(char     *buf,
 174                                  PRUint32  bufLen,
 175                                  PRUint32 *bytesWritten,
 176                                  PRBool   *complete);
 177
 178     //
 179     // read the message from a buffer segment; segment need not contain
 180     // the entire messgae.  called repeatedly.
 181     //
 182     NS_HIDDEN_(PRStatus) ReadFrom(const char *buf,
 183                                   PRUint32    bufLen,
 184                                   PRUint32   *bytesRead,
 185                                   PRBool     *complete);
 186
 187     //
 188     // a message can be added to a singly-linked list.
 189     //
 190     class ipcMessage *mNext;
 191
 192     //
 193     // meta data associated with this message object.  the owner of the
 194     // ipcMessage object is free to use this field for any purpose.  by
 195     // default, it is initialized to 0.
 196     //
 197     PRUint32          mMetaData;
 198
 199 private:
 200     ipcMessageHeader *mMsgHdr;
 201
 202     // XXX document me
 203     PRUint32          mMsgOffset;
 204     PRPackedBool      mMsgComplete;
 205 };
 206
 207 #endif // !ipcMessage_h__