// Copyright 2016 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.

library fuchsia.modular;

[Discoverable]
interface ContextWriter {
    // Creates and returns a ContextValueWriter for a future value of |type|,
    // allowing the client to set and update the contents at a later time.  The
    // value is removed from the Context service when |value_writer| is closed or
    // a connection error occurs.
    1: CreateValue(request<ContextValueWriter> value_writer, ContextValueType type);

    // This method is here to make transitioning from topic-based context
    // publishing to CreateValue() easier and will be removed eventually.
    // Internally, calls CreateValue() with type = ContextValueType.ENTITY,
    // and sets metadata.entity.topic = topic, unless WriteEntityTopic() was
    // called already on this instance with the same |topic| value. In that case,
    // performs an upate instead of adding a new value.
    //
    // Leaving |value| null removes the topic value from the Context service.
    //
    // TODO(thatguy): Remove this method and replace its behavior with
    // client-side library methods.
    2: WriteEntityTopic(string topic, string? value);
};

interface ContextValueWriter {
    // Like ContextWriter.CreateValue(), but creates the new value as a child to
    // this value.
    //
    // TODO(thatguy): What is the lifetime relationship between these two values?
    // Ie, does removing the parent remove all its children?
    1: CreateChildValue(request<ContextValueWriter> value_writer, ContextValueType type);

    // Updates the content and/or metadata of this value. If either |content| or
    // |metadata| are left null, the existing values will remain.
    2: Set(string? content, ContextMetadata? metadata);
};