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