ipc/ipc_channel.h

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