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