ipc/ipc_channel.h

   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
   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_message.h"
  11
  12 namespace IPC {
  13
  14 //------------------------------------------------------------------------------
  15
  16 class Channel : public Message::Sender {
  17   // Security tests need access to the pipe handle.
  18   friend class ChannelTest;
  19
  20  public:
  21   // Implemented by consumers of a Channel to receive messages.
  22   class Listener {
  23    public:
  24     virtual ~Listener() {}
  25
  26     // Called when a message is received.
  27     virtual void OnMessageReceived(const Message& message) = 0;
  28
  29     // Called when the channel is connected and we have received the internal
  30     // Hello message from the peer.
  31     virtual void OnChannelConnected(int32 peer_pid) {}
  32
  33     // Called when an error is detected that causes the channel to close.
  34     // This method is not called when a channel is closed normally.
  35     virtual void OnChannelError() {}
  36   };
  37
  38   enum Mode {
  39     MODE_NONE,
  40     MODE_SERVER,
  41     MODE_CLIENT
  42   };
  43
  44   enum {
  45     // The maximum message size in bytes. Attempting to receive a
  46     // message of this size or bigger results in a channel error.
  47     kMaximumMessageSize = 256 * 1024 * 1024,
  48
  49     // Ammount of data to read at once from the pipe.
  50     kReadBufferSize = 4 * 1024
  51   };
  52
  53   // Initialize a Channel.
  54   //
  55   // |channel_id| identifies the communication Channel.
  56   // |mode| specifies whether this Channel is to operate in server mode or
  57   // client mode.  In server mode, the Channel is responsible for setting up the
  58   // IPC object, whereas in client mode, the Channel merely connects to the
  59   // already established IPC object.
  60   // |listener| receives a callback on the current thread for each newly
  61   // received message.
  62   //
  63   Channel(const std::string& channel_id, Mode mode, Listener* listener);
  64
  65   ~Channel();
  66
  67   // Connect the pipe.  On the server side, this will initiate
  68   // waiting for connections.  On the client, it attempts to
  69   // connect to a pre-existing pipe.  Note, calling Connect()
  70   // will not block the calling thread and may complete
  71   // asynchronously.
  72   bool Connect() WARN_UNUSED_RESULT;
  73
  74   // Close this Channel explicitly.  May be called multiple times.
  75   void Close();
  76
  77   // Modify the Channel's listener.
  78   void set_listener(Listener* listener);
  79
  80   // Send a message over the Channel to the listener on the other end.
  81   //
  82   // |message| must be allocated using operator new.  This object will be
  83   // deleted once the contents of the Message have been sent.
  84   virtual bool Send(Message* message);
  85
  86 #if defined(OS_POSIX) && !defined(OS_NACL)
  87   // On POSIX an IPC::Channel wraps a socketpair(), this method returns the
  88   // FD # for the client end of the socket.
  89   // This method may only be called on the server side of a channel.
  90   //
  91   // If the kTestingChannelID flag is specified on the command line then
  92   // a named FIFO is used as the channel transport mechanism rather than a
  93   // socketpair() in which case this method returns -1.
  94   int GetClientFileDescriptor() const;
  95 #endif  // defined(OS_POSIX)
  96
  97  protected:
  98   // Used in Chrome by the TestSink to provide a dummy channel implementation
  99   // for testing. TestSink overrides the "interesting" functions in Channel so
 100   // no actual implementation is needed. This will cause un-overridden calls to
 101   // segfault. Do not use outside of test code!
 102   Channel() : channel_impl_(0) { }
 103
 104  private:
 105   // PIMPL to which all channel calls are delegated.
 106   class ChannelImpl;
 107   ChannelImpl *channel_impl_;
 108
 109   // The Hello message is internal to the Channel class.  It is sent
 110   // by the peer when the channel is connected.  The message contains
 111   // just the process id (pid).  The message has a special routing_id
 112   // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE).
 113   enum {
 114     HELLO_MESSAGE_TYPE = kuint16max  // Maximum value of message type (uint16),
 115                                      // to avoid conflicting with normal
 116                                      // message types, which are enumeration
 117                                      // constants starting from 0.
 118   };
 119 };
 120
 121 }  // namespace IPC
 122
 123 #endif  // IPC_IPC_CHANNEL_H_