=head1 NAME

nbd_can_meta_context - does the server support a specific meta context?

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_can_meta_context (
       struct nbd_handle *h, const char *metacontext
     );

=head1 DESCRIPTION

Returns true if the server supports the given meta context
(see L<nbd_add_meta_context(3)>).  Returns false if
the server does not.  It is possible for this command to fail if
meta contexts were requested but there is a missing or failed
attempt at NBD_OPT_SET_META_CONTEXT during option negotiation.

If the server supports block status filtering (see
L<nbd_can_block_status_payload(3)>, this function must return
true for any filter name passed to L<nbd_block_status_filter(3)>.

The single parameter is the name of the metadata context,
for example C<LIBNBD_CONTEXT_BASE_ALLOCATION>.
B<E<lt>libnbd.hE<gt>> includes defined constants for well-known
namespace contexts beginning with C<LIBNBD_CONTEXT_>, but you
are free to pass in other contexts.

This call does not block, because it returns data that is saved in
the handle from the NBD protocol handshake.

=head1 RETURN VALUE

This call returns a boolean value.

=head1 ERRORS

On error C<-1> is returned.

Refer to L<libnbd(3)/ERROR HANDLING>
for how to get further details of the error.

The following parameters must not be NULL: C<h>, C<metacontext>.
For more information see L<libnbd(3)/Non-NULL parameters>.

=head1 HANDLE STATE

nbd_can_meta_context
can be called when the handle is in the following states:

 ┌─────────────────────────────────────┬─────────────────────────┐
 │ Handle created, before connecting   │ ❌ error                │
 │ Connecting                          │ ❌ error                │
 │ Connecting & handshaking (opt_mode) │ ✅ allowed              │
 │ Connected to the server             │ ✅ allowed              │
 │ Connection shut down                │ ✅ allowed              │
 │ Handle dead                         │ ❌ error                │
 └─────────────────────────────────────┴─────────────────────────┘

=head1 VERSION

This function first appeared in libnbd 1.0.

If you need to test if this function is available at compile time
check if the following macro is defined:

 #define LIBNBD_HAVE_NBD_CAN_META_CONTEXT 1

=head1 SEE ALSO

L<nbd_add_meta_context(3)>,
L<nbd_aio_block_status_64(3)>,
L<nbd_block_status_64(3)>,
L<nbd_block_status_filter(3)>,
L<nbd_can_block_status_payload(3)>,
L<nbd_create(3)>,
L<nbd_opt_info(3)>,
L<nbd_opt_set_meta_context(3)>,
L<nbd_set_request_meta_context(3)>,
L<libnbd(3)/Flag calls>,
L<libnbd(3)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
