src/lib/inspect_deprecated/reader.h

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef SRC_LIB_INSPECT_DEPRECATED_READER_H_
#define SRC_LIB_INSPECT_DEPRECATED_READER_H_

#include <fuchsia/inspect/deprecated/cpp/fidl.h>
#include <lib/fit/promise.h>
#include <lib/inspect/cpp/vmo/snapshot.h>

#include <vector>

#include "src/lib/inspect_deprecated/hierarchy.h"
#include "src/lib/inspect_deprecated/inspect.h"

namespace inspect_deprecated {

// Vector of child names, as returned by the API.
using ChildNameVector = fidl::VectorPtr<std::string>;

namespace internal {
// Wraps the state of the ObjectReader so that ObjectReader remains copyable.
struct ObjectReaderState {
  // The interface used to communicate with Inspect.
  fuchsia::inspect::deprecated::InspectPtr inspect_ptr_;
};
}  // namespace internal

// ObjectReader is a reading interface to the Inspect API.
// It takes ownership of an incoming channel and communicates with a remote
// Inspect interface over that channel to implement high-level reading
// operations for inspection.
class ObjectReader {
 public:
  // Construct a new Reader that wraps the given handle.
  explicit ObjectReader(
      fidl::InterfaceHandle<fuchsia::inspect::deprecated::Inspect> inspect_handle);

  // Allow moving and copying.
  ObjectReader(ObjectReader&&) = default;
  ObjectReader(const ObjectReader&) = default;
  ObjectReader& operator=(ObjectReader&&) = default;
  ObjectReader& operator=(const ObjectReader&) = default;

  ~ObjectReader() = default;

  // Reads and returns the value of this Object.
  // Returns a promise to the inspect object value.
  fit::promise<fuchsia::inspect::deprecated::Object> Read() const;

  // Lists the children of this Object.
  // Returns a promise to a list of child names.
  fit::promise<ChildNameVector> ListChildren() const;

  // Opens a named child of this object.
  // Returns a promise for a new |ObjectReader| pointing at that child.
  fit::promise<ObjectReader> OpenChild(std::string child_name) const;

  // Opens |ObjectReader|s for all children of this object.
  // Returns a promise to the opened Objects as a vector of |ObjectReader|s.
  // Note: The set of children may change between listing and opening a child,
  // so children visible in one call to |ListChildren| may not be included in
  // the opened list.
  fit::promise<std::vector<ObjectReader>> OpenChildren() const;

  // Take the channel from this reader and return it.
  // This will unbind the interface being used by this reader, and future
  // operations using the reader will fail.
  zx::channel TakeChannel() { return state_->inspect_ptr_.Unbind().TakeChannel(); }

 private:
  // Shared pointer to the state for this reader, allowing ObjectReaders to be
  // copied. ObjectReader needs to be copyable to allow keeping the ObjectReader
  // (including its wrapped connection) alive while promises are evaluated.
  std::shared_ptr<internal::ObjectReaderState> state_;
};

// Construct a new object hierarchy by asynchronously reading objects from the
// given reader wrapping a FIDL interface.
// Will only read |depth| levels past the immediate object, or all levels if
// |depth| is -1.
fit::promise<ObjectHierarchy> ReadFromFidl(ObjectReader reader, int depth = -1);

// Construct a new object hierarchy by synchronously reading objects out of
// the given VMO.
fit::result<ObjectHierarchy> ReadFromVmo(const zx::vmo& vmo);

// Construct a new object hierarchy by synchronously reading objects out of the
// given VMO Snapshot.
fit::result<ObjectHierarchy> ReadFromSnapshot(::inspect::Snapshot snapshot);

// Construct a new object hierarchy by synchronously reading objects out of the
// contents of the given.
fit::result<ObjectHierarchy> ReadFromBuffer(std::vector<uint8_t> buffer);

// TODO(crjohns, nathaniel): Needs to be asynchronous use of a ChildrenManager.
// Construct a new object hierarchy by directly reading objects
// from the given given inspect_deprecated::Object. Will only read |depth| levels past the
// immediate object, or all levels if |depth| is -1.
ObjectHierarchy ReadFromObject(const Node& object_root, int depth = -1);

// Construct a new object hierarchy by reading the contents of a FIDL wrapper.
ObjectHierarchy ReadFromFidlObject(const fuchsia::inspect::deprecated::Object object);

}  // namespace inspect_deprecated

#endif  // SRC_LIB_INSPECT_DEPRECATED_READER_H_