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   enum {
  98     // The maximum message size in bytes. Attempting to receive a
  99     // message of this size or bigger results in a channel error.
 100     kMaximumMessageSize = 128 * 1024 * 1024,
 101
 102     // Ammount of data to read at once from the pipe.
 103     kReadBufferSize = 4 * 1024
 104   };
 105
 106   // Initialize a Channel.
 107   //
 108   // |channel_handle| identifies the communication Channel. For POSIX, if
 109   // the file descriptor in the channel handle is != -1, the channel takes
 110   // ownership of the file descriptor and will close it appropriately, otherwise
 111   // it will create a new descriptor internally.
 112   // |mode| specifies whether this Channel is to operate in server mode or
 113   // client mode.  In server mode, the Channel is responsible for setting up the
 114   // IPC object, whereas in client mode, the Channel merely connects to the
 115   // already established IPC object.
 116   // |listener| receives a callback on the current thread for each newly
 117   // received message.
 118   //
 119   Channel(const IPC::ChannelHandle &channel_handle, Mode mode,
 120           Listener* listener);
 121
 122   virtual ~Channel();
 123
 124   // Connect the pipe.  On the server side, this will initiate
 125   // waiting for connections.  On the client, it attempts to
 126   // connect to a pre-existing pipe.  Note, calling Connect()
 127   // will not block the calling thread and may complete
 128   // asynchronously.
 129   bool Connect() WARN_UNUSED_RESULT;
 130
 131   // Close this Channel explicitly.  May be called multiple times.
 132   // On POSIX calling close on an IPC channel that listens for connections will
 133   // cause it to close any accepted connections, and it will stop listening for
 134   // new connections. If you just want to close the currently accepted
 135   // connection and listen for new ones, use ResetToAcceptingConnectionState.
 136   void Close();
 137
 138   // Modify the Channel's listener.
 139   void set_listener(Listener* listener);
 140
 141   // Send a message over the Channel to the listener on the other end.
 142   //
 143   // |message| must be allocated using operator new.  This object will be
 144   // deleted once the contents of the Message have been sent.
 145   virtual bool Send(Message* message);
 146
 147 #if defined(OS_POSIX) && !defined(OS_NACL)
 148   // On POSIX an IPC::Channel wraps a socketpair(), this method returns the
 149   // FD # for the client end of the socket.
 150   // This method may only be called on the server side of a channel.
 151   int GetClientFileDescriptor() const;
 152
 153   // On POSIX an IPC::Channel can either wrap an established socket, or it
 154   // can wrap a socket that is listening for connections. Currently an
 155   // IPC::Channel that listens for connections can only accept one connection
 156   // at a time.
 157
 158   // Returns true if the channel supports listening for connections.
 159   bool AcceptsConnections() const;
 160
 161   // Returns true if the channel supports listening for connections and is
 162   // currently connected.
 163   bool HasAcceptedConnection() const;
 164
 165   // Returns true if the peer process' effective user id can be determined, in
 166   // which case the supplied client_euid is updated with it.
 167   bool GetClientEuid(uid_t* client_euid) const;
 168
 169   // Closes any currently connected socket, and returns to a listening state
 170   // for more connections.
 171   void ResetToAcceptingConnectionState();
 172 #endif  // defined(OS_POSIX) && !defined(OS_NACL)
 173
 174   // Returns true if a named server channel is initialized on the given channel
 175   // ID. Even if true, the server may have already accepted a connection.
 176   static bool IsNamedServerInitialized(const std::string& channel_id);
 177
 178  protected:
 179   // Used in Chrome by the TestSink to provide a dummy channel implementation
 180   // for testing. TestSink overrides the "interesting" functions in Channel so
 181   // no actual implementation is needed. This will cause un-overridden calls to
 182   // segfault. Do not use outside of test code!
 183   Channel() : channel_impl_(0) { }
 184
 185  private:
 186   // PIMPL to which all channel calls are delegated.
 187   class ChannelImpl;
 188   ChannelImpl *channel_impl_;
 189
 190   // The Hello message is internal to the Channel class.  It is sent
 191   // by the peer when the channel is connected.  The message contains
 192   // just the process id (pid).  The message has a special routing_id
 193   // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE).
 194   enum {
 195     HELLO_MESSAGE_TYPE = kuint16max  // Maximum value of message type (uint16),
 196                                      // to avoid conflicting with normal
 197                                      // message types, which are enumeration
 198                                      // constants starting from 0.
 199   };
 200 };
 201
 202 }  // namespace IPC
 203
 204 #endif  // IPC_IPC_CHANNEL_H_