ipc/ipc_channel.h

   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_CHANNEL_H_
   6 #define IPC_IPC_CHANNEL_H_
   7 #pragma once
   8
   9 #include "base/compiler_specific.h"
  10 #include "ipc/ipc_channel_handle.h"
  11 #include "ipc/ipc_message.h"
  12
  13 namespace IPC {
  14
  15 //------------------------------------------------------------------------------
  16 // See
  17 // http://www.chromium.org/developers/design-documents/inter-process-communication
  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
  32 class IPC_EXPORT Channel : public Message::Sender {
  33   // Security tests need access to the pipe handle.
  34   friend class ChannelTest;
  35
  36  public:
  37   // Implemented by consumers of a Channel to receive messages.
  38   class IPC_EXPORT Listener {
  39    public:
  40     virtual ~Listener() {}
  41
  42     // Called when a message is received.  Returns true iff the message was
  43     // handled.
  44     virtual bool OnMessageReceived(const Message& message) = 0;
  45
  46     // Called when the channel is connected and we have received the internal
  47     // Hello message from the peer.
  48     virtual void OnChannelConnected(int32 peer_pid) {}
  49
  50     // Called when an error is detected that causes the channel to close.
  51     // This method is not called when a channel is closed normally.
  52     virtual void OnChannelError() {}
  53
  54 #if defined(OS_POSIX)
  55     // Called on the server side when a channel that listens for connections
  56     // denies an attempt to connect.
  57     virtual void OnChannelDenied() {}
  58
  59     // Called on the server side when a channel that listens for connections
  60     // has an error that causes the listening channel to close.
  61     virtual void OnChannelListenError() {}
  62 #endif  // OS_POSIX
  63   };
  64
  65   // Flags to test modes
  66   enum ModeFlags {
  67     MODE_NO_FLAG = 0x0,
  68     MODE_SERVER_FLAG = 0x1,
  69     MODE_CLIENT_FLAG = 0x2,
  70     MODE_NAMED_FLAG = 0x4,
  71 #if defined(OS_POSIX)
  72     MODE_OPEN_ACCESS_FLAG = 0x8, // Don't restrict access based on client UID.
  73 #endif
  74   };
  75
  76   // Some Standard Modes
  77   enum Mode {
  78     MODE_NONE = MODE_NO_FLAG,
  79     MODE_SERVER = MODE_SERVER_FLAG,
  80     MODE_CLIENT = MODE_CLIENT_FLAG,
  81     // Channels on Windows are named by default and accessible from other
  82     // processes. On POSIX channels are anonymous by default and not accessible
  83     // from other processes. Named channels work via named unix domain sockets.
  84     // On Windows MODE_NAMED_SERVER is equivalent to MODE_SERVER and
  85     // MODE_NAMED_CLIENT is equivalent to MODE_CLIENT.
  86     MODE_NAMED_SERVER = MODE_SERVER_FLAG | MODE_NAMED_FLAG,
  87     MODE_NAMED_CLIENT = MODE_CLIENT_FLAG | MODE_NAMED_FLAG,
  88 #if defined(OS_POSIX)
  89     // An "open" named server accepts connections from ANY client.
  90     // The caller must then implement their own access-control based on the
  91     // client process' user Id.
  92     MODE_OPEN_NAMED_SERVER = MODE_OPEN_ACCESS_FLAG | MODE_SERVER_FLAG |
  93                              MODE_NAMED_FLAG
  94 #endif
  95   };
  96
  97   // The maximum message size in bytes. Attempting to receive a message of this
  98   // size or bigger results in a channel error.
  99   static const size_t kMaximumMessageSize = 128 * 1024 * 1024;
 100
 101   // Ammount of data to read at once from the pipe.
 102   static const size_t kReadBufferSize = 4 * 1024;
 103
 104   // Initialize a Channel.
 105   //
 106   // |channel_handle| identifies the communication Channel. For POSIX, if
 107   // the file descriptor in the channel handle is != -1, the channel takes
 108   // ownership of the file descriptor and will close it appropriately, otherwise
 109   // it will create a new descriptor internally.
 110   // |mode| specifies whether this Channel is to operate in server mode or
 111   // client mode.  In server mode, the Channel is responsible for setting up the
 112   // IPC object, whereas in client mode, the Channel merely connects to the
 113   // already established IPC object.
 114   // |listener| receives a callback on the current thread for each newly
 115   // received message.
 116   //
 117   Channel(const IPC::ChannelHandle &channel_handle, Mode mode,
 118           Listener* listener);
 119
 120   virtual ~Channel();
 121
 122   // Connect the pipe.  On the server side, this will initiate
 123   // waiting for connections.  On the client, it attempts to
 124   // connect to a pre-existing pipe.  Note, calling Connect()
 125   // will not block the calling thread and may complete
 126   // asynchronously.
 127   bool Connect() WARN_UNUSED_RESULT;
 128
 129   // Close this Channel explicitly.  May be called multiple times.
 130   // On POSIX calling close on an IPC channel that listens for connections will
 131   // cause it to close any accepted connections, and it will stop listening for
 132   // new connections. If you just want to close the currently accepted
 133   // connection and listen for new ones, use ResetToAcceptingConnectionState.
 134   void Close();
 135
 136   // Modify the Channel's listener.
 137   void set_listener(Listener* listener);
 138
 139   // Send a message over the Channel to the listener on the other end.
 140   //
 141   // |message| must be allocated using operator new.  This object will be
 142   // deleted once the contents of the Message have been sent.
 143   virtual bool Send(Message* message) OVERRIDE;
 144
 145 #if defined(OS_POSIX) && !defined(OS_NACL)
 146   // On POSIX an IPC::Channel wraps a socketpair(), this method returns the
 147   // FD # for the client end of the socket.
 148   // This method may only be called on the server side of a channel.
 149   // This method can be called on any thread.
 150   int GetClientFileDescriptor() const;
 151
 152   // Same as GetClientFileDescriptor, but transfers the ownership of the
 153   // file descriptor to the caller.
 154   // This method can be called on any thread.
 155   int TakeClientFileDescriptor();
 156
 157   // On POSIX an IPC::Channel can either wrap an established socket, or it
 158   // can wrap a socket that is listening for connections. Currently an
 159   // IPC::Channel that listens for connections can only accept one connection
 160   // at a time.
 161
 162   // Returns true if the channel supports listening for connections.
 163   bool AcceptsConnections() const;
 164
 165   // Returns true if the channel supports listening for connections and is
 166   // currently connected.
 167   bool HasAcceptedConnection() const;
 168
 169   // Returns true if the peer process' effective user id can be determined, in
 170   // which case the supplied client_euid is updated with it.
 171   bool GetClientEuid(uid_t* client_euid) const;
 172
 173   // Closes any currently connected socket, and returns to a listening state
 174   // for more connections.
 175   void ResetToAcceptingConnectionState();
 176 #endif  // defined(OS_POSIX) && !defined(OS_NACL)
 177
 178   // Returns true if a named server channel is initialized on the given channel
 179   // ID. Even if true, the server may have already accepted a connection.
 180   static bool IsNamedServerInitialized(const std::string& channel_id);
 181
 182 #if defined(OS_LINUX)
 183   // Sandboxed processes live in a PID namespace, so when sending the IPC hello
 184   // message from client to server we need to send the PID from the global
 185   // PID namespace.
 186   static void SetGlobalPid(int pid);
 187 #endif
 188
 189  protected:
 190   // Used in Chrome by the TestSink to provide a dummy channel implementation
 191   // for testing. TestSink overrides the "interesting" functions in Channel so
 192   // no actual implementation is needed. This will cause un-overridden calls to
 193   // segfault. Do not use outside of test code!
 194   Channel() : channel_impl_(0) { }
 195
 196  private:
 197   // PIMPL to which all channel calls are delegated.
 198   class ChannelImpl;
 199   ChannelImpl *channel_impl_;
 200
 201   // The Hello message is internal to the Channel class.  It is sent
 202   // by the peer when the channel is connected.  The message contains
 203   // just the process id (pid).  The message has a special routing_id
 204   // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE).
 205   enum {
 206     HELLO_MESSAGE_TYPE = kuint16max  // Maximum value of message type (uint16),
 207                                      // to avoid conflicting with normal
 208                                      // message types, which are enumeration
 209                                      // constants starting from 0.
 210   };
 211 };
 212
 213 }  // namespace IPC
 214
 215 #endif  // IPC_IPC_CHANNEL_H_