sdk/fidl/fuchsia.bluetooth.map/mce.fidl

// Copyright 2023 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.
@available(added=HEAD)
library fuchsia.bluetooth.map;

using fuchsia.bluetooth as bt;
using zx;

/// Use a MessagingClient to access messages on one or more Instances on
/// Message Access Servers.
@discoverable
open protocol MessagingClient {
    /// An `Accessor` will be returned for each peer as they are
    /// connected, and only one exists at a time for each peer.
    /// Hangs until a new peer becomes available once all connected
    /// peers have been delivered through this protocol.
    /// Returns an error if [WatchAccessor] is called again when there
    /// already is a pending request.
    flexible WatchAccessor() -> (resource table {
        1: peer_id bt.PeerId;
        2: accessor client_end:Accessor;
    }) error Error;
};

open protocol MessageController {
    /// Retrieve all available message details.
    /// + request `handle` Unique identifier for a Messsage.
    /// + request `include_attachment` Whether or not attachment should be included as
    ///                                part of Message content if it's available.
    /// - response NOT_FOUND error is returned if the message with the given handle does not exist.
    flexible GetDetails(struct {
        handle uint64;
        include_attachment bool;
    }) -> (Message) error Error;
};

/// Protocol used for accessing messages and notifications for a connected Bluetooth peer.
open protocol Accessor {
    compose MessageController;

    // Lists all the message repositories available with this peer.
    flexible ListAllMasInstances() -> (struct {
        instances vector<MasInstance>:MAX_NUM_MAS_INSTANCE_LENGTH;
    }) error Error;

    /// Registers for notifications from the specified MAS instances.
    /// Note that notification registration may only be open one at a time.
    /// If the NotificationRegistration protocol is active when a new
    /// request is made, the request will fail with an Unavailable error
    /// until the existing channel is closed.
    /// Hangs until registration process is completed.
    /// + request `mas_instance_ids` If empty, registration for notifications
    ///                               is done for all known MAS instances.
    /// + request `server` Client end of the repository notifier protocol
    ///                    that needs to be passed to the Accessor server.
    ///                    Caller should hold onto the server end to
    ///                    receive incoming notifications. Should not be empty.
    flexible SetNotificationRegistration(resource table {
        1: mas_instance_ids vector<uint8>:MAX_NUM_MAS_INSTANCE_LENGTH;
        2: server client_end:NotificationRegistration;
    }) -> () error Error;
};

/// Protocol for relaying event reports from the peer's message
/// repositories to the client.
/// This protocol exists to support the Notification Feature of MAP.
/// + request `notification` Notification received from the peer.
/// + request `received` The monotonic time when the notification was
///                      received from the peer.
protocol NotificationRegistration {
    /// Relays incoming event report from the peer as a Notification.
    flexible NewEventReport(table {
        1: notification Notification;
        2: received zx.Time;
    }) -> ();
};

// TODO(https://fxbug.dev/42082455): add `InstanceBrowser` protocol, which
// would be used for browsing through a specific message repository.