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