OLD | NEW |
1 // Copyright (c) 2010 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2010 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef IPC_IPC_CHANNEL_H_ | 5 #ifndef IPC_IPC_CHANNEL_H_ |
6 #define IPC_IPC_CHANNEL_H_ | 6 #define IPC_IPC_CHANNEL_H_ |
7 #pragma once | 7 #pragma once |
8 | 8 |
9 #include "base/compiler_specific.h" | 9 #include "base/compiler_specific.h" |
10 #include "ipc/ipc_channel_handle.h" | 10 #include "ipc/ipc_channel_handle.h" |
11 #include "ipc/ipc_message.h" | 11 #include "ipc/ipc_message.h" |
12 | 12 |
13 namespace IPC { | 13 namespace IPC { |
14 | 14 |
15 //------------------------------------------------------------------------------ | 15 //------------------------------------------------------------------------------ |
16 // See | |
17 // http://www.chromium.org/developers/design-documents/inter-process-communicati
on | |
18 // for overview of IPC in Chromium. | |
19 | |
20 // Channels are implemented using named pipes on Windows, and | |
21 // socket pairs (or in some special cases unix domain sockets) on POSIX. | |
22 // On Windows we access pipes in various processes by name. | |
23 // On POSIX we pass file descriptors to child processes and assign names to them | |
24 // in a lookup table. | |
25 // In general on POSIX we do not use unix domain sockets due to security | |
26 // concerns and the fact that they can leave garbage around the file system | |
27 // (MacOS does not support abstract named unix domain sockets). | |
28 // You can use unix domain sockets if you like on POSIX by constructing the | |
29 // the channel with the mode set to one of the NAMED modes. NAMED modes are | |
30 // currently used by automation and service processes. | |
31 | 16 |
32 class Channel : public Message::Sender { | 17 class Channel : public Message::Sender { |
33 // Security tests need access to the pipe handle. | 18 // Security tests need access to the pipe handle. |
34 friend class ChannelTest; | 19 friend class ChannelTest; |
35 | 20 |
36 public: | 21 public: |
37 // Implemented by consumers of a Channel to receive messages. | 22 // Implemented by consumers of a Channel to receive messages. |
38 class Listener { | 23 class Listener { |
39 public: | 24 public: |
40 virtual ~Listener() {} | 25 virtual ~Listener() {} |
41 | 26 |
42 // Called when a message is received. | 27 // Called when a message is received. |
43 virtual void OnMessageReceived(const Message& message) = 0; | 28 virtual void OnMessageReceived(const Message& message) = 0; |
44 | 29 |
45 // Called when the channel is connected and we have received the internal | 30 // Called when the channel is connected and we have received the internal |
46 // Hello message from the peer. | 31 // Hello message from the peer. |
47 virtual void OnChannelConnected(int32 peer_pid) {} | 32 virtual void OnChannelConnected(int32 peer_pid) {} |
48 | 33 |
49 // Called when an error is detected that causes the channel to close. | 34 // Called when an error is detected that causes the channel to close. |
50 // This method is not called when a channel is closed normally. | 35 // This method is not called when a channel is closed normally. |
51 virtual void OnChannelError() {} | 36 virtual void OnChannelError() {} |
52 | |
53 #if defined(OS_POSIX) | |
54 // Called on the server side when a channel that listens for connections | |
55 // denies an attempt to connect. | |
56 virtual void OnChannelDenied() {} | |
57 | |
58 // Called on the server side when a channel that listens for connections | |
59 // has an error that causes the listening channel to close. | |
60 virtual void OnChannelListenError() {} | |
61 #endif // OS_POSIX | |
62 }; | 37 }; |
63 | 38 |
64 enum Mode { | 39 enum Mode { |
65 MODE_NONE, | 40 MODE_NONE, |
66 MODE_SERVER, | 41 MODE_SERVER, |
67 MODE_CLIENT, | 42 MODE_CLIENT |
68 // Channels on Windows are named by default and accessible from other | |
69 // processes. On POSIX channels are anonymous by default and not accessible | |
70 // from other processes. Named channels work via named unix domain sockets. | |
71 // On Windows MODE_NAMED_SERVER == MODE_SERVER and | |
72 // MODE_NAMED_CLIENT == MODE_CLIENT. | |
73 MODE_NAMED_SERVER, | |
74 MODE_NAMED_CLIENT, | |
75 }; | 43 }; |
76 | 44 |
77 enum { | 45 enum { |
78 // The maximum message size in bytes. Attempting to receive a | 46 // The maximum message size in bytes. Attempting to receive a |
79 // message of this size or bigger results in a channel error. | 47 // message of this size or bigger results in a channel error. |
80 kMaximumMessageSize = 128 * 1024 * 1024, | 48 kMaximumMessageSize = 128 * 1024 * 1024, |
81 | 49 |
82 // Ammount of data to read at once from the pipe. | 50 // Ammount of data to read at once from the pipe. |
83 kReadBufferSize = 4 * 1024 | 51 kReadBufferSize = 4 * 1024 |
84 }; | 52 }; |
(...skipping 17 matching lines...) Expand all Loading... |
102 ~Channel(); | 70 ~Channel(); |
103 | 71 |
104 // Connect the pipe. On the server side, this will initiate | 72 // Connect the pipe. On the server side, this will initiate |
105 // waiting for connections. On the client, it attempts to | 73 // waiting for connections. On the client, it attempts to |
106 // connect to a pre-existing pipe. Note, calling Connect() | 74 // connect to a pre-existing pipe. Note, calling Connect() |
107 // will not block the calling thread and may complete | 75 // will not block the calling thread and may complete |
108 // asynchronously. | 76 // asynchronously. |
109 bool Connect() WARN_UNUSED_RESULT; | 77 bool Connect() WARN_UNUSED_RESULT; |
110 | 78 |
111 // Close this Channel explicitly. May be called multiple times. | 79 // Close this Channel explicitly. May be called multiple times. |
112 // On POSIX calling close on an IPC channel that listens for connections will | |
113 // cause it to close any accepted connections, and it will stop listening for | |
114 // new connections. If you just want to close the currently accepted | |
115 // connection and listen for new ones, use ResetToAcceptingConnectionState. | |
116 void Close(); | 80 void Close(); |
117 | 81 |
118 // Modify the Channel's listener. | 82 // Modify the Channel's listener. |
119 void set_listener(Listener* listener); | 83 void set_listener(Listener* listener); |
120 | 84 |
121 // Send a message over the Channel to the listener on the other end. | 85 // Send a message over the Channel to the listener on the other end. |
122 // | 86 // |
123 // |message| must be allocated using operator new. This object will be | 87 // |message| must be allocated using operator new. This object will be |
124 // deleted once the contents of the Message have been sent. | 88 // deleted once the contents of the Message have been sent. |
125 virtual bool Send(Message* message); | 89 virtual bool Send(Message* message); |
126 | 90 |
127 #if defined(OS_POSIX) && !defined(OS_NACL) | 91 #if defined(OS_POSIX) && !defined(OS_NACL) |
128 // On POSIX an IPC::Channel wraps a socketpair(), this method returns the | 92 // On POSIX an IPC::Channel wraps a socketpair(), this method returns the |
129 // FD # for the client end of the socket. | 93 // FD # for the client end of the socket. |
130 // This method may only be called on the server side of a channel. | 94 // This method may only be called on the server side of a channel. |
| 95 // |
| 96 // If the kTestingChannelID flag is specified on the command line then |
| 97 // a named FIFO is used as the channel transport mechanism rather than a |
| 98 // socketpair() in which case this method returns -1. |
131 int GetClientFileDescriptor() const; | 99 int GetClientFileDescriptor() const; |
132 | |
133 // On POSIX an IPC::Channel can either wrap an established socket, or it | |
134 // can wrap a socket that is listening for connections. Currently an | |
135 // IPC::Channel that listens for connections can only accept one connection | |
136 // at a time. | |
137 | |
138 // Returns true if the channel supports listening for connections. | |
139 bool AcceptsConnections() const; | |
140 | |
141 // Returns true if the channel supports listening for connections and is | |
142 // currently connected. | |
143 bool HasAcceptedConnection() const; | |
144 | |
145 // Closes any currently connected socket, and returns to a listening state | |
146 // for more connections. | |
147 void ResetToAcceptingConnectionState(); | |
148 #endif // defined(OS_POSIX) | 100 #endif // defined(OS_POSIX) |
149 | 101 |
150 protected: | 102 protected: |
151 // Used in Chrome by the TestSink to provide a dummy channel implementation | 103 // Used in Chrome by the TestSink to provide a dummy channel implementation |
152 // for testing. TestSink overrides the "interesting" functions in Channel so | 104 // for testing. TestSink overrides the "interesting" functions in Channel so |
153 // no actual implementation is needed. This will cause un-overridden calls to | 105 // no actual implementation is needed. This will cause un-overridden calls to |
154 // segfault. Do not use outside of test code! | 106 // segfault. Do not use outside of test code! |
155 Channel() : channel_impl_(0) { } | 107 Channel() : channel_impl_(0) { } |
156 | 108 |
157 private: | 109 private: |
158 // PIMPL to which all channel calls are delegated. | 110 // PIMPL to which all channel calls are delegated. |
159 class ChannelImpl; | 111 class ChannelImpl; |
160 ChannelImpl *channel_impl_; | 112 ChannelImpl *channel_impl_; |
161 | 113 |
162 // The Hello message is internal to the Channel class. It is sent | 114 // The Hello message is internal to the Channel class. It is sent |
163 // by the peer when the channel is connected. The message contains | 115 // by the peer when the channel is connected. The message contains |
164 // just the process id (pid). The message has a special routing_id | 116 // just the process id (pid). The message has a special routing_id |
165 // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE). | 117 // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE). |
166 enum { | 118 enum { |
167 HELLO_MESSAGE_TYPE = kuint16max // Maximum value of message type (uint16), | 119 HELLO_MESSAGE_TYPE = kuint16max // Maximum value of message type (uint16), |
168 // to avoid conflicting with normal | 120 // to avoid conflicting with normal |
169 // message types, which are enumeration | 121 // message types, which are enumeration |
170 // constants starting from 0. | 122 // constants starting from 0. |
171 }; | 123 }; |
172 }; | 124 }; |
173 | 125 |
174 } // namespace IPC | 126 } // namespace IPC |
175 | 127 |
176 #endif // IPC_IPC_CHANNEL_H_ | 128 #endif // IPC_IPC_CHANNEL_H_ |
OLD | NEW |