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