mojo/public/cpp/bindings/message.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MOJO_PUBLIC_CPP_BINDINGS_MESSAGE_H_
   6 #define MOJO_PUBLIC_CPP_BINDINGS_MESSAGE_H_
   7
   8 #include <assert.h>
   9
  10 #include <vector>
  11
  12 #include "mojo/public/cpp/bindings/lib/message_internal.h"
  13
  14 namespace mojo {
  15
  16 // Message is a holder for the data and handles to be sent over a MessagePipe.
  17 // Message owns its data and handles, but a consumer of Message is free to
  18 // mutate the data and handles. The message's data is comprised of a header
  19 // followed by payload.
  20 class Message {
  21  public:
  22   Message();
  23   ~Message();
  24
  25   // These may only be called on a newly created Message object.
  26   void AllocUninitializedData(uint32_t num_bytes);
  27   void AdoptData(uint32_t num_bytes, internal::MessageData* data);
  28
  29   // Swaps data and handles between this Message and another.
  30   void Swap(Message* other);
  31
  32   uint32_t data_num_bytes() const { return data_num_bytes_; }
  33
  34   // Access the raw bytes of the message.
  35   const uint8_t* data() const { return
  36     reinterpret_cast<const uint8_t*>(data_);
  37   }
  38   uint8_t* mutable_data() { return reinterpret_cast<uint8_t*>(data_); }
  39
  40   // Access the header.
  41   const internal::MessageHeader* header() const { return &data_->header; }
  42
  43   uint32_t name() const { return data_->header.name; }
  44   bool has_flag(uint32_t flag) const { return !!(data_->header.flags & flag); }
  45
  46   // Access the request_id field (if present).
  47   bool has_request_id() const { return data_->header.num_fields >= 3; }
  48   uint64_t request_id() const {
  49     assert(has_request_id());
  50     return static_cast<const internal::MessageHeaderWithRequestID*>(
  51         &data_->header)->request_id;
  52   }
  53   void set_request_id(uint64_t request_id) {
  54     assert(has_request_id());
  55     static_cast<internal::MessageHeaderWithRequestID*>(&data_->header)->
  56         request_id = request_id;
  57   }
  58
  59   // Access the payload.
  60   const uint8_t* payload() const {
  61     return reinterpret_cast<const uint8_t*>(data_) + data_->header.num_bytes;
  62   }
  63   uint8_t* mutable_payload() {
  64     return reinterpret_cast<uint8_t*>(data_) + data_->header.num_bytes;
  65   }
  66
  67   // Access the handles.
  68   const std::vector<Handle>* handles() const { return &handles_; }
  69   std::vector<Handle>* mutable_handles() { return &handles_; }
  70
  71  private:
  72   uint32_t data_num_bytes_;
  73   internal::MessageData* data_;  // Heap-allocated using malloc.
  74   std::vector<Handle> handles_;
  75
  76   MOJO_DISALLOW_COPY_AND_ASSIGN(Message);
  77 };
  78
  79 class MessageReceiver {
  80  public:
  81   virtual ~MessageReceiver() {}
  82
  83   // The receiver may mutate the given message.  Returns true if the message
  84   // was accepted and false otherwise, indicating that the message was invalid
  85   // or malformed.
  86   virtual bool Accept(Message* message) MOJO_WARN_UNUSED_RESULT = 0;
  87
  88   // A variant on Accept that registers a MessageReceiver (known as the
  89   // responder) to handle the response message generated from the given
  90   // message. The responder's Accept method may be called during
  91   // AcceptWithResponder or some time after its return.
  92   //
  93   // NOTE: Upon returning true, AcceptWithResponder assumes ownership of
  94   // |responder| and will delete it after calling |responder->Accept| or upon
  95   // its own destruction.
  96   //
  97   virtual bool AcceptWithResponder(
  98       Message* message, MessageReceiver* responder) MOJO_WARN_UNUSED_RESULT = 0;
  99 };
 100
 101 // Read a single message from the pipe and dispatch to the given receiver.  The
 102 // receiver may be null, in which case the message is simply discarded.
 103 // Returns MOJO_RESULT_SHOULD_WAIT if the caller should wait on the handle to
 104 // become readable. Returns MOJO_RESULT_OK if a message was dispatched and
 105 // otherwise returns an error code if something went wrong.
 106 MojoResult ReadAndDispatchMessage(MessagePipeHandle handle,
 107                                   MessageReceiver* receiver,
 108                                   bool* receiver_result);
 109
 110 }  // namespace mojo
 111
 112 #endif  // MOJO_PUBLIC_CPP_BINDINGS_MESSAGE_H_