ipc/ipcd/shared/src/ipcm.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 ipcm_h__
  39 #define ipcm_h__
  40
  41 #include "ipcMessage.h"
  42 #include "ipcMessagePrimitives.h"
  43
  44 //-----------------------------------------------------------------------------
  45
  46 //
  47 // IPCM (IPC Manager) protocol support
  48 //
  49
  50 // The IPCM message target identifier:
  51 extern const nsID IPCM_TARGET;
  52
  53 //
  54 // Every IPCM message has the following structure:
  55 //
  56 //  +-----------------------------------------+
  57 //  | (ipc message header)                    |
  58 //  +-----------------------------------------+
  59 //  | DWORD : type                            |
  60 //  +-----------------------------------------+
  61 //  | DWORD : requestIndex                    |
  62 //  +-----------------------------------------+
  63 //  .                                         .
  64 //  . (payload)                               .
  65 //  .                                         .
  66 //  +-----------------------------------------+
  67 //
  68 // where |type| is an integer uniquely identifying the message.  the type is
  69 // composed of a message class identifier and a message number.  there are 3
  70 // message classes:
  71 //
  72 //   ACK - acknowledging a request
  73 //   REQ - making a request
  74 //   PSH - providing unrequested, "pushed" information
  75 //
  76 // The requestIndex field is initialized when a request is made.  An
  77 // acknowledgement's requestIndex is equal to that of its corresponding
  78 // request message.  This enables the requesting side of the message exchange
  79 // to match acknowledgements to requests.  The requestIndex field is ignored
  80 // for PSH messages.
  81 //
  82
  83 // The IPCM message class is stored in the most significant byte.
  84 #define IPCM_MSG_CLASS_REQ (1 << 24)
  85 #define IPCM_MSG_CLASS_ACK (2 << 24)
  86 #define IPCM_MSG_CLASS_PSH (4 << 24)
  87
  88 // Requests
  89 #define IPCM_MSG_REQ_PING                   (IPCM_MSG_CLASS_REQ | 1)
  90 #define IPCM_MSG_REQ_FORWARD                (IPCM_MSG_CLASS_REQ | 2)
  91 #define IPCM_MSG_REQ_CLIENT_HELLO           (IPCM_MSG_CLASS_REQ | 3)
  92 #define IPCM_MSG_REQ_CLIENT_ADD_NAME        (IPCM_MSG_CLASS_REQ | 4)
  93 #define IPCM_MSG_REQ_CLIENT_DEL_NAME        (IPCM_MSG_CLASS_REQ | 5)
  94 #define IPCM_MSG_REQ_CLIENT_ADD_TARGET      (IPCM_MSG_CLASS_REQ | 6)
  95 #define IPCM_MSG_REQ_CLIENT_DEL_TARGET      (IPCM_MSG_CLASS_REQ | 7)
  96 #define IPCM_MSG_REQ_QUERY_CLIENT_BY_NAME   (IPCM_MSG_CLASS_REQ | 8)
  97 #define IPCM_MSG_REQ_QUERY_CLIENT_NAMES     (IPCM_MSG_CLASS_REQ | 9)  // TODO
  98 #define IPCM_MSG_REQ_QUERY_CLIENT_TARGETS   (IPCM_MSG_CLASS_REQ | 10) // TODO
  99
 100 // Acknowledgements
 101 #define IPCM_MSG_ACK_RESULT                 (IPCM_MSG_CLASS_ACK | 1)
 102 #define IPCM_MSG_ACK_CLIENT_ID              (IPCM_MSG_CLASS_ACK | 2)
 103 #define IPCM_MSG_ACK_CLIENT_NAMES           (IPCM_MSG_CLASS_ACK | 3)  // TODO
 104 #define IPCM_MSG_ACK_CLIENT_TARGETS         (IPCM_MSG_CLASS_ACK | 4)  // TODO
 105
 106 // Push messages
 107 #define IPCM_MSG_PSH_CLIENT_STATE           (IPCM_MSG_CLASS_PSH | 1)
 108 #define IPCM_MSG_PSH_FORWARD                (IPCM_MSG_CLASS_PSH | 2)
 109
 110 //-----------------------------------------------------------------------------
 111
 112 //
 113 // IPCM header
 114 //
 115 struct ipcmMessageHeader
 116 {
 117     PRUint32 mType;
 118     PRUint32 mRequestIndex;
 119 };
 120
 121 //
 122 // returns IPCM message type.
 123 //
 124 static inline int
 125 IPCM_GetType(const ipcMessage *msg)
 126 {
 127     return ((const ipcmMessageHeader *) msg->Data())->mType;
 128 }
 129
 130 //
 131 // return IPCM message request index.
 132 //
 133 static inline PRUint32
 134 IPCM_GetRequestIndex(const ipcMessage *msg)
 135 {
 136     return ((const ipcmMessageHeader *) msg->Data())->mRequestIndex;
 137 }
 138
 139 //
 140 // return a request index that is unique to this process.
 141 //
 142 NS_HIDDEN_(PRUint32)
 143 IPCM_NewRequestIndex();
 144
 145 //-----------------------------------------------------------------------------
 146
 147 //
 148 // The IPCM protocol is detailed below:
 149 //
 150
 151 // REQUESTS
 152
 153 //
 154 // req: IPCM_MSG_REQ_PING
 155 // ack: IPCM_MSG_ACK_RESULT
 156 //
 157 // A PING can be sent from either a client to the daemon, or from the daemon
 158 // to a client.  The expected acknowledgement is a RESULT message with a status
 159 // code of 0.
 160 //
 161 // This request message has no payload.
 162 //
 163
 164 //
 165 // req: IPCM_MSG_REQ_FORWARD
 166 // ack: IPCM_MSG_ACK_RESULT
 167 //
 168 // A FORWARD is sent when a client wishes to send a message to another client.
 169 // The payload of this message is another message that should be forwarded by
 170 // the daemon's IPCM to the specified client.  The expected acknowledgment is
 171 // a RESULT message with a status code indicating success or failure.
 172 //
 173 // When the daemon receives a FORWARD message, it creates a PSH_FORWARD message
 174 // and sends that on to the destination client.
 175 //
 176 // This request message has as its payload:
 177 //
 178 //  +-----------------------------------------+
 179 //  | DWORD : clientID                        |
 180 //  +-----------------------------------------+
 181 //  | (innerMsgHeader)                        |
 182 //  +-----------------------------------------+
 183 //  | (innerMsgData)                          |
 184 //  +-----------------------------------------+
 185 //
 186
 187 //
 188 // req: IPCM_MSG_REQ_CLIENT_HELLO
 189 // ack: IPCM_MSG_REQ_CLIENT_ID <or> IPCM_MSG_REQ_RESULT
 190 //
 191 // A CLIENT_HELLO is sent when a client connects to the IPC daemon.  The
 192 // expected acknowledgement is a CLIENT_ID message informing the new client of
 193 // its ClientID.  If for some reason the IPC daemon cannot accept the new
 194 // client, it returns a RESULT message with a failure status code.
 195 //
 196 // This request message has no payload.
 197 //
 198
 199 //
 200 // req: IPCM_MSG_REQ_CLIENT_ADD_NAME
 201 // ack: IPCM_MSG_ACK_RESULT
 202 //
 203 // A CLIENT_ADD_NAME is sent when a client wishes to register an additional
 204 // name for itself.  The expected acknowledgement is a RESULT message with a
 205 // status code indicating success or failure.
 206 //
 207 // This request message has as its payload a null-terminated ASCII character
 208 // string indicating the name of the client.
 209 //
 210
 211 //
 212 // req: IPCM_MSG_REQ_CLIENT_DEL_NAME
 213 // ack: IPCM_MSG_ACK_RESULT
 214 //
 215 // A CLIENT_DEL_NAME is sent when a client wishes to unregister a name that it
 216 // has registered.  The expected acknowledgement is a RESULT message with a
 217 // status code indicating success or failure.
 218 //
 219 // This request message has as its payload a null-terminated ASCII character
 220 // string indicating the name of the client.
 221 //
 222
 223 //
 224 // req: IPCM_MSG_REQ_CLIENT_ADD_TARGET
 225 // ack: IPCM_MSG_ACK_RESULT
 226 //
 227 // A CLIENT_ADD_TARGET is sent when a client wishes to register an additional
 228 // target that it supports.  The expected acknowledgement is a RESULT message
 229 // with a status code indicating success or failure.
 230 //
 231 // This request message has as its payload a 128-bit UUID indicating the
 232 // target to add.
 233 //
 234
 235 //
 236 // req: IPCM_MSG_REQ_CLIENT_DEL_TARGET
 237 // ack: IPCM_MSG_ACK_RESULT
 238 //
 239 // A CLIENT_DEL_TARGET is sent when a client wishes to unregister a target
 240 // that it has registered.  The expected acknowledgement is a RESULT message
 241 // with a status code indicating success or failure.
 242 //
 243 // This request message has as its payload a 128-bit UUID indicating the
 244 // target to remove.
 245 //
 246
 247 //
 248 // req: IPCM_MSG_REQ_QUERY_CLIENT_BY_NAME
 249 // ack: IPCM_MSG_ACK_CLIENT_ID <or> IPCM_MSG_ACK_RESULT
 250 //
 251 // A QUERY_CLIENT_BY_NAME may be sent by a client to discover the client that
 252 // is known by a common name.  If more than one client matches the name, then
 253 // only the ID of the more recently registered client is returned.  The
 254 // expected acknowledgement is a CLIENT_ID message carrying the ID of the
 255 // corresponding client.  If no client matches the given name or if some error
 256 // occurs, then a RESULT message with a failure status code is returned.
 257 //
 258 // This request message has as its payload a null-terminated ASCII character
 259 // string indicating the client name to query.
 260 //
 261
 262 // ACKNOWLEDGEMENTS
 263
 264 //
 265 // ack: IPCM_MSG_ACK_RESULT
 266 //
 267 // This acknowledgement is returned to indicate a success or failure status.
 268 //
 269 // The payload consists of a single DWORD value.
 270 //
 271 // Possible status codes are listed below (negative values indicate failure
 272 // codes):
 273 //
 274 #define IPCM_OK               0  // success: generic
 275 #define IPCM_ERROR_GENERIC   -1  // failure: generic
 276 #define IPCM_ERROR_NO_CLIENT -2  // failure: client does not exist
 277
 278 //
 279 // ack: IPCM_MSG_ACK_CLIENT_ID
 280 //
 281 // This acknowledgement is returned to specify a client ID.
 282 //
 283 // The payload consists of a single DWORD value.
 284 //
 285
 286 // PUSH MESSAGES
 287
 288 //
 289 // psh: ICPM_MSG_PSH_CLIENT_STATE
 290 //
 291 // This message is sent to clients to indicate the status of other clients.
 292 //
 293 // The payload consists of:
 294 //
 295 //  +-----------------------------------------+
 296 //  | DWORD : clientID                        |
 297 //  +-----------------------------------------+
 298 //  | DWORD : clientState                     |
 299 //  +-----------------------------------------+
 300 //
 301 // where, clientState is one of the following values indicating whether the
 302 // client has recently connected (up) or disconnected (down):
 303 //
 304 #define IPCM_CLIENT_STATE_UP     1
 305 #define IPCM_CLIENT_STATE_DOWN   2
 306
 307 //
 308 // psh: IPCM_MSG_PSH_FORWARD
 309 //
 310 // This message is sent by the daemon to a client on behalf of another client.
 311 // The recipient is expected to unpack the contained message and process it.
 312 //
 313 // The payload of this message matches the payload of IPCM_MSG_REQ_FORWARD,
 314 // with the exception that the clientID field is set to the clientID of the
 315 // sender of the IPCM_MSG_REQ_FORWARD message.
 316 //
 317
 318 //-----------------------------------------------------------------------------
 319
 320 //
 321 // NOTE: This file declares some helper classes that simplify constructing
 322 //       and parsing IPCM messages.  Each class subclasses ipcMessage, but
 323 //       adds no additional member variables.  |operator new| should be used
 324 //       to allocate one of the IPCM helper classes, e.g.:
 325 //
 326 //          ipcMessage *msg = new ipcmMessageClientHello("foo");
 327 //
 328 //       Given an arbitrary ipcMessage, it can be parsed using logic similar
 329 //       to the following:
 330 //
 331 //          void func(const ipcMessage *unknown)
 332 //          {
 333 //            if (unknown->Topic().Equals(IPCM_TARGET)) {
 334 //              if (IPCM_GetMsgType(unknown) == IPCM_MSG_TYPE_CLIENT_ID) {
 335 //                ipcMessageCast<ipcmMessageClientID> msg(unknown);
 336 //                printf("Client ID: %u\n", msg->ClientID());
 337 //              }
 338 //            }
 339 //          }
 340 //
 341
 342 // REQUESTS
 343
 344 class ipcmMessagePing : public ipcMessage_DWORD_DWORD
 345 {
 346 public:
 347     ipcmMessagePing()
 348         : ipcMessage_DWORD_DWORD(
 349             IPCM_TARGET,
 350             IPCM_MSG_REQ_PING,
 351             IPCM_NewRequestIndex()) {}
 352 };
 353
 354 class ipcmMessageForward : public ipcMessage
 355 {
 356 public:
 357     // @param type        the type of this message: IPCM_MSG_{REQ,PSH}_FORWARD
 358     // @param clientID    the client id of the sender or receiver
 359     // @param target      the message target
 360     // @param data        the message data
 361     // @param dataLen     the message data length
 362     ipcmMessageForward(PRUint32 type,
 363                        PRUint32 clientID,
 364                        const nsID &target,
 365                        const char *data,
 366                        PRUint32 dataLen) NS_HIDDEN;
 367
 368     // set inner message data, constrained to the data length passed
 369     // to this class's constructor.
 370     NS_HIDDEN_(void) SetInnerData(PRUint32 offset, const char *data, PRUint32 dataLen);
 371
 372     NS_HIDDEN_(PRUint32)     ClientID() const;
 373     NS_HIDDEN_(const nsID &) InnerTarget() const;
 374     NS_HIDDEN_(const char *) InnerData() const;
 375     NS_HIDDEN_(PRUint32)     InnerDataLen() const;
 376 };
 377
 378 class ipcmMessageClientHello : public ipcMessage_DWORD_DWORD
 379 {
 380 public:
 381     ipcmMessageClientHello()
 382         : ipcMessage_DWORD_DWORD(
 383             IPCM_TARGET,
 384             IPCM_MSG_REQ_CLIENT_HELLO,
 385             IPCM_NewRequestIndex()) {}
 386 };
 387
 388 class ipcmMessageClientAddName : public ipcMessage_DWORD_DWORD_STR
 389 {
 390 public:
 391     ipcmMessageClientAddName(const char *name)
 392         : ipcMessage_DWORD_DWORD_STR(
 393             IPCM_TARGET,
 394             IPCM_MSG_REQ_CLIENT_ADD_NAME,
 395             IPCM_NewRequestIndex(),
 396             name) {}
 397
 398     const char *Name() const { return Third(); }
 399 };
 400
 401 class ipcmMessageClientDelName : public ipcMessage_DWORD_DWORD_STR
 402 {
 403 public:
 404     ipcmMessageClientDelName(const char *name)
 405         : ipcMessage_DWORD_DWORD_STR(
 406             IPCM_TARGET,
 407             IPCM_MSG_REQ_CLIENT_DEL_NAME,
 408             IPCM_NewRequestIndex(),
 409             name) {}
 410
 411     const char *Name() const { return Third(); }
 412 };
 413
 414 class ipcmMessageClientAddTarget : public ipcMessage_DWORD_DWORD_ID
 415 {
 416 public:
 417     ipcmMessageClientAddTarget(const nsID &target)
 418         : ipcMessage_DWORD_DWORD_ID(
 419             IPCM_TARGET,
 420             IPCM_MSG_REQ_CLIENT_ADD_TARGET,
 421             IPCM_NewRequestIndex(),
 422             target) {}
 423
 424     const nsID &Target() const { return Third(); }
 425 };
 426
 427 class ipcmMessageClientDelTarget : public ipcMessage_DWORD_DWORD_ID
 428 {
 429 public:
 430     ipcmMessageClientDelTarget(const nsID &target)
 431         : ipcMessage_DWORD_DWORD_ID(
 432             IPCM_TARGET,
 433             IPCM_MSG_REQ_CLIENT_ADD_TARGET,
 434             IPCM_NewRequestIndex(),
 435             target) {}
 436
 437     const nsID &Target() const { return Third(); }
 438 };
 439
 440 class ipcmMessageQueryClientByName : public ipcMessage_DWORD_DWORD_STR
 441 {
 442 public:
 443     ipcmMessageQueryClientByName(const char *name)
 444         : ipcMessage_DWORD_DWORD_STR(
 445             IPCM_TARGET,
 446             IPCM_MSG_REQ_QUERY_CLIENT_BY_NAME,
 447             IPCM_NewRequestIndex(),
 448             name) {}
 449
 450     const char *Name() const { return Third(); }
 451     PRUint32 RequestIndex() const { return Second(); }
 452 };
 453
 454 // ACKNOWLEDGEMENTS
 455
 456 class ipcmMessageResult : public ipcMessage_DWORD_DWORD_DWORD
 457 {
 458 public:
 459     ipcmMessageResult(PRUint32 requestIndex, PRInt32 status)
 460         : ipcMessage_DWORD_DWORD_DWORD(
 461             IPCM_TARGET,
 462             IPCM_MSG_ACK_RESULT,
 463             requestIndex,
 464             (PRUint32) status) {}
 465
 466     PRInt32 Status() const { return (PRInt32) Third(); }
 467 };
 468
 469 class ipcmMessageClientID : public ipcMessage_DWORD_DWORD_DWORD
 470 {
 471 public:
 472     ipcmMessageClientID(PRUint32 requestIndex, PRUint32 clientID)
 473         : ipcMessage_DWORD_DWORD_DWORD(
 474             IPCM_TARGET,
 475             IPCM_MSG_ACK_CLIENT_ID,
 476             requestIndex,
 477             clientID) {}
 478
 479     PRUint32 ClientID() const { return Third(); }
 480 };
 481
 482 // PUSH MESSAGES
 483
 484 class ipcmMessageClientState : public ipcMessage_DWORD_DWORD_DWORD_DWORD
 485 {
 486 public:
 487     ipcmMessageClientState(PRUint32 clientID, PRUint32 clientStatus)
 488         : ipcMessage_DWORD_DWORD_DWORD_DWORD(
 489             IPCM_TARGET,
 490             IPCM_MSG_PSH_CLIENT_STATE,
 491             0,
 492             clientID,
 493             clientStatus) {}
 494
 495     PRUint32 ClientID() const { return Third(); }
 496     PRUint32 ClientState() const { return Fourth(); }
 497 };
 498
 499 #endif // !ipcm_h__