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 <stddef.h> 9 #include <stdint.h> 10 11 #include <utility> 12 #include <vector> 13 14 #include "base/compiler_specific.h" 15 #include "base/macros.h" 16 #include "base/observer_list.h" 17 #include "build/build_config.h" 18 #include "ipc/ipc_channel.h" 19 20 namespace IPC { 21 22 class Message; 23 24 // This test sink provides a "sink" for IPC messages that are sent. It allows 25 // the caller to query messages received in various different ways. It is 26 // designed for tests for objects that use the IPC system. 27 // 28 // Typical usage: 29 // 30 // test_sink.ClearMessages(); 31 // do_something(); 32 // 33 // // We should have gotten exactly one update state message. 34 // EXPECT_TRUE(test_sink.GetUniqeMessageMatching(ViewHostMsg_Update::ID)); 35 // // ...and no start load messages. 36 // EXPECT_FALSE(test_sink.GetFirstMessageMatching(ViewHostMsg_Start::ID)); 37 // 38 // // Now inspect a message. This assumes a message that was declared like 39 // // this: IPC_MESSAGE_ROUTED2(ViewMsg_Foo, bool, int) 40 // IPC::Message* msg = test_sink.GetFirstMessageMatching(ViewMsg_Foo::ID)); 41 // ASSERT_TRUE(msg); 42 // bool first_param; 43 // int second_param; 44 // ViewMsg_Foo::Read(msg, &first_param, &second_param); 45 // 46 // // Go on to the next phase of the test. 47 // test_sink.ClearMessages(); 48 // 49 // To read a sync reply, do this: 50 // 51 // IPC::Message* msg = test_sink.GetUniqueMessageMatching(IPC_REPLY_ID); 52 // ASSERT_TRUE(msg); 53 // base::TupleTypes<ViewHostMsg_Foo::ReplyParam>::ValueTuple reply_data; 54 // EXPECT_TRUE(ViewHostMsg_Foo::ReadReplyParam(msg, &reply_data)); 55 // 56 // You can also register to be notified when messages are posted to the sink. 57 // This can be useful if you need to wait for a particular message that will 58 // be posted asynchronously. Example usage: 59 // 60 // class MyListener : public IPC::Listener { 61 // public: 62 // MyListener(const base::Closure& closure) 63 // : message_received_closure_(closure) {} 64 // virtual bool OnMessageReceived(const IPC::Message& msg) { 65 // <do something with the message> 66 // message_received_closure_.Run(); 67 // return false; // to store the message in the sink, or true to drop it 68 // } 69 // private: 70 // base::Closure message_received_closure_; 71 // }; 72 // 73 // base::RunLoop run_loop; 74 // MyListener listener(run_loop.QuitClosure()); 75 // test_sink.AddFilter(&listener); 76 // StartSomeAsynchronousProcess(&test_sink); 77 // run_loop.Run(); 78 // <inspect the results> 79 // ... 80 // 81 // To hook up the sink, all you need to do is call OnMessageReceived when a 82 // message is received. 83 class TestSink : public Channel { 84 public: 85 TestSink(); 86 ~TestSink() override; 87 88 // Interface in IPC::Channel. This copies the message to the sink and then 89 // deletes it. 90 bool Send(IPC::Message* message) override; 91 bool Connect() override WARN_UNUSED_RESULT; 92 void Close() override; 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. message_count()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_ 142