ipc/ipc_channel_reader.h

   1 // Copyright (c) 2012 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 IPC_IPC_CHANNEL_READER_H_
   6 #define IPC_IPC_CHANNEL_READER_H_
   7
   8 #include <set>
   9
  10 #include "base/basictypes.h"
  11 #include "base/gtest_prod_util.h"
  12 #include "base/memory/scoped_vector.h"
  13 #include "ipc/attachment_broker.h"
  14 #include "ipc/brokerable_attachment.h"
  15 #include "ipc/ipc_channel.h"
  16 #include "ipc/ipc_export.h"
  17
  18 namespace IPC {
  19 namespace internal {
  20
  21 // This class provides common pipe reading functionality for the
  22 // platform-specific IPC channel implementations.
  23 //
  24 // It does the common input buffer management and message dispatch, while the
  25 // platform-specific parts provide the pipe management through a virtual
  26 // interface implemented on a per-platform basis.
  27 //
  28 // Note that there is no "writer" corresponding to this because the code for
  29 // writing to the channel is much simpler and has very little common
  30 // functionality that would benefit from being factored out. If we add
  31 // something like that in the future, it would be more appropriate to add it
  32 // here (and rename appropriately) rather than writing a different class.
  33 class IPC_EXPORT ChannelReader : public SupportsAttachmentBrokering,
  34                                  public AttachmentBroker::Observer {
  35  public:
  36   explicit ChannelReader(Listener* listener);
  37   virtual ~ChannelReader();
  38
  39   void set_listener(Listener* listener) { listener_ = listener; }
  40
  41   // This type is returned by ProcessIncomingMessages to indicate the effect of
  42   // the method.
  43   enum DispatchState {
  44     // All messages were successfully dispatched, or there were no messages to
  45     // dispatch.
  46     DISPATCH_FINISHED,
  47     // There was a channel error.
  48     DISPATCH_ERROR,
  49     // Dispatching messages is blocked on receiving more information from the
  50     // broker.
  51     DISPATCH_WAITING_ON_BROKER,
  52   };
  53
  54   // Call to process messages received from the IPC connection and dispatch
  55   // them.
  56   DispatchState ProcessIncomingMessages();
  57
  58   // Handles asynchronously read data.
  59   //
  60   // Optionally call this after returning READ_PENDING from ReadData to
  61   // indicate that buffer was filled with the given number of bytes of
  62   // data. See ReadData for more.
  63   DispatchState AsyncReadComplete(int bytes_read);
  64
  65   // Returns true if the given message is internal to the IPC implementation,
  66   // like the "hello" message sent on channel set-up.
  67   bool IsInternalMessage(const Message& m);
  68
  69   // Returns true if the given message is an Hello message
  70   // sent on channel set-up.
  71   bool IsHelloMessage(const Message& m);
  72
  73  protected:
  74   enum ReadState { READ_SUCCEEDED, READ_FAILED, READ_PENDING };
  75
  76   Listener* listener() const { return listener_; }
  77
  78   // Populates the given buffer with data from the pipe.
  79   //
  80   // Returns the state of the read. On READ_SUCCESS, the number of bytes
  81   // read will be placed into |*bytes_read| (which can be less than the
  82   // buffer size). On READ_FAILED, the channel will be closed.
  83   //
  84   // If the return value is READ_PENDING, it means that there was no data
  85   // ready for reading. The implementation is then responsible for either
  86   // calling AsyncReadComplete with the number of bytes read into the
  87   // buffer, or ProcessIncomingMessages to try the read again (depending
  88   // on whether the platform's async I/O is "try again" or "write
  89   // asynchronously into your buffer").
  90   virtual ReadState ReadData(char* buffer, int buffer_len, int* bytes_read) = 0;
  91
  92   // Loads the required file desciptors into the given message. Returns true
  93   // on success. False means a fatal channel error.
  94   //
  95   // This will read from the input_fds_ and read more handles from the FD
  96   // pipe if necessary.
  97   virtual bool ShouldDispatchInputMessage(Message* msg) = 0;
  98
  99   // Overridden by subclasses to get attachments that are sent alongside the IPC
 100   // channel (as opposed to through a broker).
 101   // Returns true on success. False means a fatal channel error.
 102   virtual bool GetNonBrokeredAttachments(Message* msg) = 0;
 103
 104   // Performs post-dispatch checks. Called when all input buffers are empty,
 105   // though there could be more data ready to be read from the OS.
 106   virtual bool DidEmptyInputBuffers() = 0;
 107
 108   // Handles internal messages, like the hello message sent on channel startup.
 109   virtual void HandleInternalMessage(const Message& msg) = 0;
 110
 111   // Exposed for testing purposes only.
 112   ScopedVector<Message>* get_queued_messages() { return &queued_messages_; }
 113
 114   // Exposed for testing purposes only.
 115   virtual void DispatchMessage(Message* m);
 116
 117   // Get the process ID for the sender of the message.
 118   virtual base::ProcessId GetSenderPID() = 0;
 119
 120   // Whether the channel is an endpoint of attachment brokering.
 121   virtual bool IsAttachmentBrokerEndpoint() = 0;
 122
 123  private:
 124   FRIEND_TEST_ALL_PREFIXES(ChannelReaderTest, AttachmentAlreadyBrokered);
 125   FRIEND_TEST_ALL_PREFIXES(ChannelReaderTest, AttachmentNotYetBrokered);
 126
 127   typedef std::set<BrokerableAttachment::AttachmentId> AttachmentIdSet;
 128
 129   // Takes the given data received from the IPC channel, translates it into
 130   // Messages, and puts them in queued_messages_.
 131   // As an optimization, after a message is translated, the message is
 132   // immediately dispatched if able. This prevents an otherwise unnecessary deep
 133   // copy of the message which is needed to store the message in the message
 134   // queue.
 135   bool TranslateInputData(const char* input_data, int input_data_len);
 136
 137   // Dispatches messages from queued_messages_ to listeners. Successfully
 138   // dispatched messages are removed from queued_messages_.
 139   DispatchState DispatchMessages();
 140
 141   // Attempts to fill in the brokerable attachments of |msg| with information
 142   // from the Attachment Broker.
 143   // Returns the set of ids that are still waiting to be brokered.
 144   AttachmentIdSet GetBrokeredAttachments(Message* msg);
 145
 146   // AttachmentBroker::Observer overrides.
 147   void ReceivedBrokerableAttachmentWithId(
 148       const BrokerableAttachment::AttachmentId& id) override;
 149
 150   // This class should observe the attachment broker if and only if blocked_ids_
 151   // is not empty.
 152   void StartObservingAttachmentBroker();
 153   void StopObservingAttachmentBroker();
 154
 155   Listener* listener_;
 156
 157   // We read from the pipe into this buffer. Managed by DispatchInputData, do
 158   // not access directly outside that function.
 159   char input_buf_[Channel::kReadBufferSize];
 160
 161   // Large messages that span multiple pipe buffers, get built-up using
 162   // this buffer.
 163   std::string input_overflow_buf_;
 164
 165   // These messages are waiting to be dispatched. If this vector is non-empty,
 166   // then the front Message must be blocked on receiving an attachment from the
 167   // AttachmentBroker.
 168   ScopedVector<Message> queued_messages_;
 169
 170   // If the next message to be processed is blocked by the broker, then this
 171   // set contains the AttachmentIds that are needed to unblock the message.
 172   AttachmentIdSet blocked_ids_;
 173
 174   DISALLOW_COPY_AND_ASSIGN(ChannelReader);
 175 };
 176
 177 }  // namespace internal
 178 }  // namespace IPC
 179
 180 #endif  // IPC_IPC_CHANNEL_READER_H_