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. |
16 | 31 |
17 class Channel : public Message::Sender { | 32 class Channel : public Message::Sender { |
18 // Security tests need access to the pipe handle. | 33 // Security tests need access to the pipe handle. |
19 friend class ChannelTest; | 34 friend class ChannelTest; |
20 | 35 |
21 public: | 36 public: |
22 // Implemented by consumers of a Channel to receive messages. | 37 // Implemented by consumers of a Channel to receive messages. |
23 class Listener { | 38 class Listener { |
24 public: | 39 public: |
25 virtual ~Listener() {} | 40 virtual ~Listener() {} |
26 | 41 |
27 // Called when a message is received. | 42 // Called when a message is received. |
28 virtual void OnMessageReceived(const Message& message) = 0; | 43 virtual void OnMessageReceived(const Message& message) = 0; |
29 | 44 |
30 // Called when the channel is connected and we have received the internal | 45 // Called when the channel is connected and we have received the internal |
31 // Hello message from the peer. | 46 // Hello message from the peer. |
32 virtual void OnChannelConnected(int32 peer_pid) {} | 47 virtual void OnChannelConnected(int32 peer_pid) {} |
33 | 48 |
34 // Called when an error is detected that causes the channel to close. | 49 // Called when an error is detected that causes the channel to close. |
35 // This method is not called when a channel is closed normally. | 50 // This method is not called when a channel is closed normally. |
36 virtual void OnChannelError() {} | 51 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 |
37 }; | 62 }; |
38 | 63 |
39 enum Mode { | 64 enum Mode { |
40 MODE_NONE, | 65 MODE_NONE, |
41 MODE_SERVER, | 66 MODE_SERVER, |
42 MODE_CLIENT, | 67 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. |
43 MODE_NAMED_SERVER, | 73 MODE_NAMED_SERVER, |
44 MODE_NAMED_CLIENT | 74 MODE_NAMED_CLIENT, |
45 }; | 75 }; |
46 | 76 |
47 enum { | 77 enum { |
48 // The maximum message size in bytes. Attempting to receive a | 78 // The maximum message size in bytes. Attempting to receive a |
49 // message of this size or bigger results in a channel error. | 79 // message of this size or bigger results in a channel error. |
50 kMaximumMessageSize = 128 * 1024 * 1024, | 80 kMaximumMessageSize = 128 * 1024 * 1024, |
51 | 81 |
52 // Ammount of data to read at once from the pipe. | 82 // Ammount of data to read at once from the pipe. |
53 kReadBufferSize = 4 * 1024 | 83 kReadBufferSize = 4 * 1024 |
54 }; | 84 }; |
(...skipping 17 matching lines...) Expand all Loading... |
72 ~Channel(); | 102 ~Channel(); |
73 | 103 |
74 // Connect the pipe. On the server side, this will initiate | 104 // Connect the pipe. On the server side, this will initiate |
75 // waiting for connections. On the client, it attempts to | 105 // waiting for connections. On the client, it attempts to |
76 // connect to a pre-existing pipe. Note, calling Connect() | 106 // connect to a pre-existing pipe. Note, calling Connect() |
77 // will not block the calling thread and may complete | 107 // will not block the calling thread and may complete |
78 // asynchronously. | 108 // asynchronously. |
79 bool Connect() WARN_UNUSED_RESULT; | 109 bool Connect() WARN_UNUSED_RESULT; |
80 | 110 |
81 // Close this Channel explicitly. May be called multiple times. | 111 // 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. |
82 void Close(); | 116 void Close(); |
83 | 117 |
84 // Modify the Channel's listener. | 118 // Modify the Channel's listener. |
85 void set_listener(Listener* listener); | 119 void set_listener(Listener* listener); |
86 | 120 |
87 // Send a message over the Channel to the listener on the other end. | 121 // Send a message over the Channel to the listener on the other end. |
88 // | 122 // |
89 // |message| must be allocated using operator new. This object will be | 123 // |message| must be allocated using operator new. This object will be |
90 // deleted once the contents of the Message have been sent. | 124 // deleted once the contents of the Message have been sent. |
91 virtual bool Send(Message* message); | 125 virtual bool Send(Message* message); |
92 | 126 |
93 #if defined(OS_POSIX) && !defined(OS_NACL) | 127 #if defined(OS_POSIX) && !defined(OS_NACL) |
94 // On POSIX an IPC::Channel wraps a socketpair(), this method returns the | 128 // On POSIX an IPC::Channel wraps a socketpair(), this method returns the |
95 // FD # for the client end of the socket. | 129 // FD # for the client end of the socket. |
96 // This method may only be called on the server side of a channel. | 130 // This method may only be called on the server side of a channel. |
97 // | |
98 // If the kTestingChannelID flag is specified on the command line then | |
99 // a named FIFO is used as the channel transport mechanism rather than a | |
100 // socketpair() in which case this method returns -1. | |
101 int GetClientFileDescriptor() const; | 131 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(); |
102 #endif // defined(OS_POSIX) | 148 #endif // defined(OS_POSIX) |
103 | 149 |
104 protected: | 150 protected: |
105 // Used in Chrome by the TestSink to provide a dummy channel implementation | 151 // Used in Chrome by the TestSink to provide a dummy channel implementation |
106 // for testing. TestSink overrides the "interesting" functions in Channel so | 152 // for testing. TestSink overrides the "interesting" functions in Channel so |
107 // no actual implementation is needed. This will cause un-overridden calls to | 153 // no actual implementation is needed. This will cause un-overridden calls to |
108 // segfault. Do not use outside of test code! | 154 // segfault. Do not use outside of test code! |
109 Channel() : channel_impl_(0) { } | 155 Channel() : channel_impl_(0) { } |
110 | 156 |
111 private: | 157 private: |
112 // PIMPL to which all channel calls are delegated. | 158 // PIMPL to which all channel calls are delegated. |
113 class ChannelImpl; | 159 class ChannelImpl; |
114 ChannelImpl *channel_impl_; | 160 ChannelImpl *channel_impl_; |
115 | 161 |
116 // The Hello message is internal to the Channel class. It is sent | 162 // The Hello message is internal to the Channel class. It is sent |
117 // by the peer when the channel is connected. The message contains | 163 // by the peer when the channel is connected. The message contains |
118 // just the process id (pid). The message has a special routing_id | 164 // just the process id (pid). The message has a special routing_id |
119 // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE). | 165 // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE). |
120 enum { | 166 enum { |
121 HELLO_MESSAGE_TYPE = kuint16max // Maximum value of message type (uint16), | 167 HELLO_MESSAGE_TYPE = kuint16max // Maximum value of message type (uint16), |
122 // to avoid conflicting with normal | 168 // to avoid conflicting with normal |
123 // message types, which are enumeration | 169 // message types, which are enumeration |
124 // constants starting from 0. | 170 // constants starting from 0. |
125 }; | 171 }; |
126 }; | 172 }; |
127 | 173 |
128 } // namespace IPC | 174 } // namespace IPC |
129 | 175 |
130 #endif // IPC_IPC_CHANNEL_H_ | 176 #endif // IPC_IPC_CHANNEL_H_ |
OLD | NEW |