sdk/fidl/fuchsia.fdomain/channel.fidl

// Copyright 2024 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.fdomain;

using zx;

// Result from a channel write operation.
type WriteChannelError = strict union {
    1: error Error;
    2: op_errors vector<Error:optional>;
};

// Message received through a channel.
type ChannelMessage = struct {
    data vector<uint8>:zx.CHANNEL_MAX_MSG_BYTES;
    handles vector<HandleInfo>:zx.CHANNEL_MAX_MSG_HANDLES;
};

// FDomain operations on Channels.
@no_resource
open protocol Channel {
    // Create a new channel in this FDomain and return both its ends.
    flexible CreateChannel(struct {
        handles array<NewHandleId, 2>;
    }) -> () error Error;

    // Read a message from a channel. This method will fail if the channel is currently being read
    // using the streaming read functions.
    //
    // Note that this method is not like zx_channel_read in that it will not
    // return `SHOULD_WAIT` but will instead delay returning until there is data
    // to return.
    flexible ReadChannel(struct {
        handle HandleId;
    }) -> (ChannelMessage) error Error;

    // Write to a channel. Handles are always consumed.
    flexible WriteChannel(struct {
        handle HandleId;
        data vector<uint8>:zx.CHANNEL_MAX_MSG_BYTES;
        handles strict union {
            1: handles vector<HandleId>:zx.CHANNEL_MAX_MSG_HANDLES;
            2: dispositions vector<HandleDisposition>:zx.CHANNEL_MAX_MSG_HANDLES;
        };
    }) -> () error WriteChannelError;

    // Starts reading from the given channel. Data is returned via the `ChannelStreamingData` event.
    // That event will occur repeatedly until `ReadChannelStreamingStop` is called for the same handle
    // or the event indicates the handle is closed.
    flexible ReadChannelStreamingStart(struct {
        handle HandleId;
    }) -> () error Error;

    // Stop asynchronous reading from the given channel.
    flexible ReadChannelStreamingStop(struct {
        handle HandleId;
    }) -> () error Error;

    // Data read asynchronously from a channel.
    flexible -> OnChannelStreamingData(struct {
        handle HandleId;
        channel_sent flexible union {
            1: message ChannelMessage;
            2: stopped AioStopped;
        };
    });
};