dbus/file_descriptor.h

   1 // Copyright (c) 2012 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 DBUS_FILE_DESCRIPTOR_H_
   6 #define DBUS_FILE_DESCRIPTOR_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "dbus/dbus_export.h"
  11
  12 namespace dbus {
  13
  14 // FileDescriptor is a type used to encapsulate D-Bus file descriptors
  15 // and to follow the RAII idiom appropiate for use with message operations
  16 // where the descriptor might be easily leaked.  To guard against this the
  17 // descriptor is closed when an instance is destroyed if it is owned.
  18 // Ownership is asserted only when PutValue is used and TakeValue can be
  19 // used to take ownership.
  20 //
  21 // For example, in the following
  22 //  FileDescriptor fd;
  23 //  if (!reader->PopString(&name) ||
  24 //      !reader->PopFileDescriptor(&fd) ||
  25 //      !reader->PopUint32(&flags)) {
  26 // the descriptor in fd will be closed if the PopUint32 fails.  But
  27 //   writer.AppendFileDescriptor(dbus::FileDescriptor(1));
  28 // will not automatically close "1" because it is not owned.
  29 //
  30 // Descriptors must be validated before marshalling in a D-Bus message
  31 // or using them after unmarshalling.  We disallow descriptors to a
  32 // directory to reduce the security risks.  Splitting out validation
  33 // also allows the caller to do this work on the File thread to conform
  34 // with i/o restrictions.
  35 class CHROME_DBUS_EXPORT FileDescriptor {
  36  public:
  37   // This provides a simple way to pass around file descriptors since they must
  38   // be closed on a thread that is allowed to perform I/O.
  39   struct Deleter {
  40     void CHROME_DBUS_EXPORT operator()(FileDescriptor* fd);
  41   };
  42
  43   // Permits initialization without a value for passing to
  44   // dbus::MessageReader::PopFileDescriptor to fill in and from int values.
  45   FileDescriptor() : value_(-1), owner_(false), valid_(false) {}
  46   explicit FileDescriptor(int value) : value_(value), owner_(false),
  47       valid_(false) {}
  48
  49   virtual ~FileDescriptor();
  50
  51   // Retrieves value as an int without affecting ownership.
  52   int value() const;
  53
  54   // Retrieves whether or not the descriptor is ok to send/receive.
  55   int is_valid() const { return valid_; }
  56
  57   // Sets the value and assign ownership.
  58   void PutValue(int value) {
  59     value_ = value;
  60     owner_ = true;
  61     valid_ = false;
  62   }
  63
  64   // Takes the value and ownership.
  65   int TakeValue();
  66
  67   // Checks (and records) validity of the file descriptor.
  68   // We disallow directories to avoid potential sandbox escapes.
  69   // Note this call must be made on a thread where file i/o is allowed.
  70   void CheckValidity();
  71
  72  private:
  73   int value_;
  74   bool owner_;
  75   bool valid_;
  76
  77   DISALLOW_COPY_AND_ASSIGN(FileDescriptor);
  78 };
  79
  80 using ScopedFileDescriptor =
  81     scoped_ptr<FileDescriptor, FileDescriptor::Deleter>;
  82
  83 }  // namespace dbus
  84
  85 #endif  // DBUS_FILE_DESCRIPTOR_H_