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