STORE: Add documentation on expecting specific infos

[B<-text arg>]

[B<-engine id>]

[B<-r>]

[B<-certs>]

[B<-keys>]

[B<-crls>]

B<uri> ...

=head1 DESCRIPTION

Fetch objects recursively when possible.

=item B<-certs>

=item B<-keys>

=item B<-crls>

Only select the certificates, keys or CRLs from the given URI.

However, if this URI would return a set of names (URIs), those are always

returned.

=back

=head1 SEE ALSO

=head1 COPYRIGHT

Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,

OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,

OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,

OSSL_STORE_LOADER_set_expect,

OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,

OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,

OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,

OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,

OSSL_STORE_expect_fn,

OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,

OSSL_STORE_close_fn - Types and functions to manipulate, register and

unregister STORE loaders for different URI schemes

                                   va_list args);

 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,

                                OSSL_STORE_ctrl_fn store_ctrl_function);

 typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);

 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,

                                  OSSL_STORE_expect_fn expect_function);

 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,

                                                UI_METHOD *ui_method,

                                                void *ui_data);

B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader

using B<struct ossl_store_loader_ctx_st { ... }>.

B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_load_fn>,

B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> are the function pointer

types used within a STORE loader.

B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,

B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn>

are the function pointer types used within a STORE loader.

The functions pointed at define the functionality of the given loader.

=over 4

This function is expected to return 1 on success, 0 on error.

=item B<OSSL_STORE_expect_fn>

This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>

identity B<expected>, and is used to tell the loader what object type is

expected.

B<expected> may be zero to signify that no specific object type is expected.

This function is expected to return 1 on success, 0 on error.

=item B<OSSL_STORE_load_fn>

This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>

OSSL_STORE_LOADER_set_ctrl() sets the control function for the

B<store_loader>.

OSSL_STORE_LOADER_set_expect() sets the expect function for the

B<store_loader>.

OSSL_STORE_LOADER_set_load() sets the loader function for the

B<store_loader>.

=head1 RETURN VALUES

The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,

B<OSSL_STORE_expect_fn>,

B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> have the

same return values as OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and

OSSL_STORE_close(), respectively.

same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),

OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.

OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,

or B<NULL> on failure.

=pod

=head1 NAME

OSSL_STORE_expect - Specify what object type is expected

=head1 SYNOPSIS

 #include <openssl/store.h>

 int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);

=head1 DESCRIPTION

OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns

by specifying a B<OSSL_STORE_INFO> type.

For example, if C<file:/foo/bar/store.pem> contains several different objects

and only the certificates are interesting, the application can simply say

that it expects the type B<OSSL_STORE_INFO_CERT>.

All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>)

except for B<OSSL_STORE_INFO_NAME> are supported.

OSSL_STORE_expect() I<must> be called before the first OSSL_STORE_load()

of a given session, or it will fail.

=head1 NOTES

If a more elaborate filter is required by the application, a better choice

would be to use a post-processing function.

See L<OSSL_STORE_open(3)> for more information.

However, some loaders may take advantage of the knowledge of an expected type

to make object retrieval more efficient, so if a single type is expected, this

method is usually preferable.

=head1 RETURN VALUES

OSSL_STORE_expect() returns 1 on success, or 0 on failure.

=head1 SEE ALSO

L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_load(3)>

=head1 HISTORY

OSSL_STORE_expect()

was added to OpenSSL 1.1.1.

=head1 COPYRIGHT

Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

=head1 SEE ALSO

L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>

L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,

L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>

=head1 COPYRIGHT

OSSL_STORE_LOADER_CTX                   datatype

OSSL_STORE_close_fn                     datatype

OSSL_STORE_ctrl_fn                      datatype

OSSL_STORE_expect_fn                    datatype

OSSL_STORE_eof_fn                       datatype

OSSL_STORE_error_fn                     datatype

OSSL_STORE_load_fn                      datatype