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 15namespace IPC { 16 17class 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. 73class 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 82 // Used by the source of the messages to send the message to the sink. This 83 // will make a copy of the message and store it in the list. 84 bool OnMessageReceived(const Message& msg); 85 86 // Returns the number of messages in the queue. 87 size_t message_count() const { return messages_.size(); } 88 89 // Clears the message queue of saved messages. 90 void ClearMessages(); 91 92 // Returns the message at the given index in the queue. The index may be out 93 // of range, in which case the return value is NULL. The returned pointer will 94 // only be valid until another message is received or the list is cleared. 95 const Message* GetMessageAt(size_t index) const; 96 97 // Returns the first message with the given ID in the queue. If there is no 98 // message with the given ID, returns NULL. The returned pointer will only be 99 // valid until another message is received or the list is cleared. 100 const Message* GetFirstMessageMatching(uint32 id) const; 101 102 // Returns the message with the given ID in the queue. If there is no such 103 // message or there is more than one of that message, this will return NULL 104 // (with the expectation that you'll do an ASSERT_TRUE() on the result). 105 // The returned pointer will only be valid until another message is received 106 // or the list is cleared. 107 const Message* GetUniqueMessageMatching(uint32 id) const; 108 109 // Adds the given listener as a filter to the TestSink. 110 // When a message is received by the TestSink, it will be dispatched to 111 // the filters, in the order they were added. If a filter returns true 112 // from OnMessageReceived, subsequent filters will not receive the message 113 // and the TestSink will not store it. 114 void AddFilter(Listener* filter); 115 116 // Removes the given filter from the TestSink. 117 void RemoveFilter(Listener* filter); 118 119 private: 120 // The actual list of received messages. 121 std::vector<Message> messages_; 122 ObserverList<Listener> filter_list_; 123 124 DISALLOW_COPY_AND_ASSIGN(TestSink); 125}; 126 127} // namespace IPC 128 129#endif // IPC_IPC_TEST_SINK_H_ 130