class WireClient

Create an initialized client which manages the binding of the client end of

a channel to a dispatcher, as if that client had been default-constructed

then later bound to that endpoint via |Bind|.

It is a logic error to use a dispatcher that is shutting down or already

shut down. Doing so will result in a panic.

If any other error occurs during initialization, the

|event_handler->on_fidl_error| handler will be invoked asynchronously with

the reason, if specified.

Create an uninitialized client. The client may then be bound to an endpoint

later via |Bind|.

Prefer using the constructor overload that binds the client to a channel

atomically during construction. Use this default constructor only when the

client must be constructed first before a channel could be obtained (for

example, if the client is an instance variable).

Returns if the |WireClient| is initialized.

The destructor of |WireClient| will initiate binding teardown.

When the client destructs:

- The channel will be closed.

- Pointers obtained via |get| will be invalidated.

- Binding teardown will happen, implying:

* In-progress calls will be forgotten. Async callbacks will be dropped.

|WireClient|s can be safely moved without affecting any in-flight FIDL

method calls. Note that calling methods on a client should be serialized

with respect to operations that consume the client, such as moving it or

destroying it.

Initializes the client by binding the |client_end| endpoint to the

dispatcher.

It is a logic error to invoke |Bind| on a dispatcher that is shutting down

or already shut down. Doing so will result in a panic.

When other errors occur during binding, the |event_handler->on_fidl_error|

handler will be asynchronously invoked with the reason, if specified.

It is not allowed to call |Bind| on an initialized client. To rebind a

|WireClient| to a different endpoint, simply replace the |WireClient|

variable with a new instance.

Returns the interface for making outgoing FIDL calls with managed memory

allocation. The client must be initialized first.

If the binding has been torn down, calls on the interface return error with

status |ZX_ERR_CANCELED| and reason |fidl::Reason::kUnbind|.

Persisting this pointer to a local variable is discouraged, since that

results in unsafe borrows. Always prefer making calls directly via the

|WireClient| reference-counting type.

Returns a veneer object which exposes the caller-allocating API, using the

provided |resource| to allocate buffers necessary for each call. Requests

will live on those buffers. Responses on the other hand do not live on

those buffers; they are separately managed and may become invalid after the

corresponding async response/result callback returns.

Examples of supported memory resources are:

* |fidl::BufferSpan|, referencing a range of bytes.

* |fidl::AnyArena

&

|, referencing an arena.

* Any type for which there is a |MakeAnyBufferAllocator| specialization.

See |AnyBufferAllocator|.

This interface is suitable when one needs complete control over memory

allocation. Instead of implicitly heap allocating the necessary bookkeeping

for in-flight operations, the methods take a raw pointer to a

|fidl::WireResponseContext

<FidlMethod

>|, which may be allocated via any

means as long as it outlives the duration of this async FIDL call. Refer to

documentation on the response context.

The returned object borrows from this object, hence must not outlive

the client object.

The returned object may be briefly persisted for use over multiple calls:

fidl::Arena my_arena;

fidl::WireClient client(std::move(client_end), some_dispatcher);

auto buffered = client.buffer(my_arena);

buffered->FooMethod(args, foo_response_context);

buffered->BarMethod(args, bar_response_context);

...

In this situation, those calls will all use the initially provided memory

resource (`my_arena`) to allocate their message buffers. The memory

resource won't be reset/overwritten across calls. Note that if a

|BufferSpan| is provided as the memory resource, sharing memory resource in

this manner may eventually exhaust the capacity of the buffer span since it

represents a single fixed size buffer. To reuse (overwrite) the underlying

buffer across multiple calls, obtain a new caller-allocating veneer object

for each call:

fidl::BufferSpan span(some_large_buffer, size);

fidl::WireClient client(std::move(client_end), some_dispatcher);

client.buffer(span)->FooMethod(args, foo_response_context);

client.buffer(span)->BarMethod(args, bar_response_context);

Returns a veneer object exposing synchronous calls. Example:

fidl::WireClient client(std::move(client_end), some_dispatcher);

fidl::WireResult result = client.sync()->FooMethod(args);

Attempts to disassociate the client object from its endpoint and stop

monitoring it for messages. After this call, subsequent operations will

fail with an unbound error.

If there are pending two-way async calls, the endpoint is closed and this

method will fail with |fidl::Reason::kPendingTwoWayCallPreventsUnbind|. The

caller needs to arrange things such that unbinding happens after any

replies to two-way calls.

If the endpoint was already closed due to an earlier error, that error will

be returned here.

Otherwise, returns the client endpoint.