ipc/ipc_test_sink.h

   1 // Copyright (c) 2011 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_TEST_SINK_H_
   6 #define IPC_IPC_TEST_SINK_H_
   7
   8 #include <stdint.h>
   9
  10 #include <utility>
  11 #include <vector>
  12
  13 #include "base/compiler_specific.h"
  14 #include "base/macros.h"
  15 #include "base/observer_list.h"
  16 #include "ipc/ipc_channel.h"
  17
  18 namespace IPC {
  19
  20 class Message;
  21
  22 // This test sink provides a "sink" for IPC messages that are sent. It allows
  23 // the caller to query messages received in various different ways.  It is
  24 // designed for tests for objects that use the IPC system.
  25 //
  26 // Typical usage:
  27 //
  28 //   test_sink.ClearMessages();
  29 //   do_something();
  30 //
  31 //   // We should have gotten exactly one update state message.
  32 //   EXPECT_TRUE(test_sink.GetUniqeMessageMatching(ViewHostMsg_Update::ID));
  33 //   // ...and no start load messages.
  34 //   EXPECT_FALSE(test_sink.GetFirstMessageMatching(ViewHostMsg_Start::ID));
  35 //
  36 //   // Now inspect a message. This assumes a message that was declared like
  37 //   // this: IPC_MESSAGE_ROUTED2(ViewMsg_Foo, bool, int)
  38 //   IPC::Message* msg = test_sink.GetFirstMessageMatching(ViewMsg_Foo::ID));
  39 //   ASSERT_TRUE(msg);
  40 //   bool first_param;
  41 //   int second_param;
  42 //   ViewMsg_Foo::Read(msg, &first_param, &second_param);
  43 //
  44 //   // Go on to the next phase of the test.
  45 //   test_sink.ClearMessages();
  46 //
  47 // To read a sync reply, do this:
  48 //
  49 //   IPC::Message* msg = test_sink.GetUniqueMessageMatching(IPC_REPLY_ID);
  50 //   ASSERT_TRUE(msg);
  51 //   base::TupleTypes<ViewHostMsg_Foo::ReplyParam>::ValueTuple reply_data;
  52 //   EXPECT_TRUE(ViewHostMsg_Foo::ReadReplyParam(msg, &reply_data));
  53 //
  54 // You can also register to be notified when messages are posted to the sink.
  55 // This can be useful if you need to wait for a particular message that will
  56 // be posted asynchronously.  Example usage:
  57 //
  58 //   class MyListener : public IPC::Listener {
  59 //    public:
  60 //     virtual bool OnMessageReceived(const IPC::Message& msg) {
  61 //       <do something with the message>
  62 //       MessageLoop::current()->Quit();
  63 //       return false;  // to store the message in the sink, or true to drop it
  64 //     }
  65 //   };
  66 //
  67 //   MyListener listener;
  68 //   test_sink.AddFilter(&listener);
  69 //   StartSomeAsynchronousProcess(&test_sink);
  70 //   MessageLoop::current()->Run();
  71 //   <inspect the results>
  72 //   ...
  73 //
  74 // To hook up the sink, all you need to do is call OnMessageReceived when a
  75 // message is received.
  76 class TestSink : public Channel {
  77  public:
  78   TestSink();
  79   ~TestSink() override;
  80
  81   // Interface in IPC::Channel. This copies the message to the sink and then
  82   // deletes it.
  83   bool Send(IPC::Message* message) override;
  84   bool Connect() override WARN_UNUSED_RESULT;
  85   void Close() override;
  86   base::ProcessId GetPeerPID() const override;
  87   base::ProcessId GetSelfPID() const override;
  88
  89 #if defined(OS_POSIX) && !defined(OS_NACL)
  90   int GetClientFileDescriptor() const override;
  91   base::ScopedFD TakeClientFileDescriptor() override;
  92 #endif  // defined(OS_POSIX) && !defined(OS_NACL)
  93
  94   // Used by the source of the messages to send the message to the sink. This
  95   // will make a copy of the message and store it in the list.
  96   bool OnMessageReceived(const Message& msg);
  97
  98   // Returns the number of messages in the queue.
  99   size_t message_count() const { return messages_.size(); }
 100
 101   // Clears the message queue of saved messages.
 102   void ClearMessages();
 103
 104   // Returns the message at the given index in the queue. The index may be out
 105   // of range, in which case the return value is NULL. The returned pointer will
 106   // only be valid until another message is received or the list is cleared.
 107   const Message* GetMessageAt(size_t index) const;
 108
 109   // Returns the first message with the given ID in the queue. If there is no
 110   // message with the given ID, returns NULL. The returned pointer will only be
 111   // valid until another message is received or the list is cleared.
 112   const Message* GetFirstMessageMatching(uint32_t id) const;
 113
 114   // Returns the message with the given ID in the queue. If there is no such
 115   // message or there is more than one of that message, this will return NULL
 116   // (with the expectation that you'll do an ASSERT_TRUE() on the result).
 117   // The returned pointer will only be valid until another message is received
 118   // or the list is cleared.
 119   const Message* GetUniqueMessageMatching(uint32_t id) const;
 120
 121   // Adds the given listener as a filter to the TestSink.
 122   // When a message is received by the TestSink, it will be dispatched to
 123   // the filters, in the order they were added.  If a filter returns true
 124   // from OnMessageReceived, subsequent filters will not receive the message
 125   // and the TestSink will not store it.
 126   void AddFilter(Listener* filter);
 127
 128   // Removes the given filter from the TestSink.
 129   void RemoveFilter(Listener* filter);
 130
 131  private:
 132   // The actual list of received messages.
 133   std::vector<Message> messages_;
 134   base::ObserverList<Listener> filter_list_;
 135
 136   DISALLOW_COPY_AND_ASSIGN(TestSink);
 137 };
 138
 139 }  // namespace IPC
 140
 141 #endif  // IPC_IPC_TEST_SINK_H_