// Copyright 2018 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 LIB_FIDL_ASYNC_BIND_H_
#define LIB_FIDL_ASYNC_BIND_H_

#include <lib/async/dispatcher.h>
#include <zircon/fidl.h>

__BEGIN_CDECLS

// A generic FIDL dispatch function.
//
// For FIDL interfaces with [Layout="Simple"], the C backend generates a
// dispatch function that decodes the |msg| and calls through an |ops| table.
//
// This function signature matches the structure of these generated functions
// but with the type of the |ops| table erased.
//
// Example:
//
//  fidl_bind(dispatcher, channel, (fidl_dispatch_t*)spaceship_SpaceShip_dispatch, ctx, &kOps);
//
typedef zx_status_t(fidl_dispatch_t)(void* ctx, fidl_txn_t* txn, fidl_incoming_msg_t* msg,
                                     const void* ops);

// Binds a |dispatch| function to |channel| using |dispatcher|.
//
// This function adds an |async_wait_t| to the given |dispatcher| that waits
// asynchronously for new messages to arrive on |channel|. When a message
// arrives, the |dispatch| function is called on one of the threads associated
// with the |dispatcher| with the |fidl_incoming_msg_t| as well as the given
// |ctx| and |ops|.
//
// Typically, the |dispatch| function is generated by the C backend for FIDL
// interfaces with [Layout="Simple"] (see |fidl_dispatch_t|). These dispatch
// functions decode the |fidl_incoming_msg_t| and call through the |ops| table
// implementations of the interface's methods, passing along the |ctx| and a
// |fidl_txn_t| (if the method has a reply message).
//
// The |fidl_txn_t| passed to |dispatch| is valid only until |dispatch| returns.
// If the method has a reply message, the |reply| function on the |fidl_txn_t|
// object must be called synchronously within the |dispatch| call.
//
// If a client wishes to reply to the message asynchronously, |fidl_async_txn_create|
// must be invoked on |fidl_txn_t|, and ZX_ERR_ASYNC must be returned.
//
// Returns whether |fidl_bind| was able to begin waiting on the given |channel|.
// Upon any error, |channel| is closed and the binding is terminated.
//
// The |dispatcher| takes ownership of the channel. Shutting down the |dispatcher|
// results in |channel| being closed.
//
// It is safe to shutdown the dispatcher at any time.
//
// It is unsafe to destroy the dispatcher from within a dispatch function.
// It is unsafe to destroy the dispatcher while any |fidl_async_txn_t| objects
// are alive.
zx_status_t fidl_bind(async_dispatcher_t* dispatcher, zx_handle_t channel,
                      fidl_dispatch_t* dispatch, void* ctx, const void* ops);

// An asynchronous FIDL txn.
//
// This is an opaque wrapper around |fidl_txn_t| which can extend the lifetime
// of the object beyond the dispatched function.
typedef struct fidl_async_txn fidl_async_txn_t;

// Takes ownership of |txn| and allows usage of the txn beyond the currently
// dispatched function.
//
// If this function is invoked within a dispatched function, that function
// must return ZX_ERR_ASYNC.
//
// The result must be destroyed with a call to |fidl_async_txn_complete|.
fidl_async_txn_t* fidl_async_txn_create(fidl_txn_t* txn);

// Acquire a reference to the |fidl_txn_t| backing this txn object.
//
// It is unsafe to use this |fidl_txn_t| after |async_txn| is completed.
fidl_txn_t* fidl_async_txn_borrow(fidl_async_txn_t* async_txn);

// Destroys an asynchronous transaction created with |fidl_async_txn_create|.
// This function is intented to be the single termination function.
//
// If requested, rebinds the underlying txn against the binding.
// Returns an error if |rebind| is true and the transaction could not be
// re-bound.
//
// In all cases, the |async_txn| object is consumed.
//
// Note: Regardless of whether the client wants to rebind the txn or not,
// `fidl_async_txn_complete` should be the final function invoked. As such, if
// this function fails to rebind, there isn't much we can do with the
// |async_txn| beyond that point, and we therefore prefer to consume it in all
// cases.
zx_status_t fidl_async_txn_complete(fidl_async_txn_t* async_txn, bool rebind);

__END_CDECLS

#endif  // LIB_FIDL_ASYNC_BIND_H_