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