[thirdparty/openssl.git] / doc / man3 / OSSL_STORE_expect.pod

=pod

=head1 NAME

OSSL_STORE_expect,
OSSL_STORE_supports_search,
OSSL_STORE_find
- Specify what object type is expected

=head1 SYNOPSIS

 #include <openssl/store.h>

 int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);

 int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);

 int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search);

=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_find() helps applications specify a criterion for a more fine
grained search of objects.

OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE
context supports the given search type.
See L<OSSL_STORE_SEARCH(3)/SUPPORTED CRITERION TYPES> for information on the
supported search criterion types.

OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first
OSSL_STORE_load() of a given session, or they 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.

OSSL_STORE_supports_search() returns 1 if the criterion is supported, or 0
otherwise.

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

=head1 SEE ALSO

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

=head1 HISTORY

OSSL_STORE_expect(), OSSL_STORE_supports_search() and OSSL_STORE_find()
were added in OpenSSL 1.1.1.

=head1 COPYRIGHT

Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (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
Commit	Line	Data
ce9586b9 RL	1	=pod
	2
	3	=head1 NAME
	4
6ab6decc RL	5	OSSL_STORE_expect,
	6	OSSL_STORE_supports_search,
	7	OSSL_STORE_find
	8	- Specify what object type is expected
ce9586b9 RL	9
	10	=head1 SYNOPSIS
	11
	12	#include <openssl/store.h>
	13
	14	int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
	15
6ab6decc	16	int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);
379cc089	17
6ab6decc RL	18	int OSSL_STORE_find(OSSL_STORE_CTX ctx, OSSL_STORE_SEARCH search);
6ab6decc RL	19
ce9586b9 RL	20	=head1 DESCRIPTION
	21
	22	OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns
	23	by specifying a B<OSSL_STORE_INFO> type.
	24	For example, if C<file:/foo/bar/store.pem> contains several different objects
	25	and only the certificates are interesting, the application can simply say
	26	that it expects the type B<OSSL_STORE_INFO_CERT>.
	27	All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>)
	28	except for B<OSSL_STORE_INFO_NAME> are supported.
	29
6ab6decc RL	30	OSSL_STORE_find() helps applications specify a criterion for a more fine
	31	grained search of objects.
	32
	33	OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE
	34	context supports the given search type.
6e4618a0	35	See L<OSSL_STORE_SEARCH(3)/SUPPORTED CRITERION TYPES> for information on the
6ab6decc RL	36	supported search criterion types.
	37
	38	OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first
	39	OSSL_STORE_load() of a given session, or they will fail.
ce9586b9 RL	40
	41	=head1 NOTES
	42
	43	If a more elaborate filter is required by the application, a better choice
	44	would be to use a post-processing function.
	45	See L<OSSL_STORE_open(3)> for more information.
	46
	47	However, some loaders may take advantage of the knowledge of an expected type
	48	to make object retrieval more efficient, so if a single type is expected, this
	49	method is usually preferable.
	50
	51	=head1 RETURN VALUES
	52
	53	OSSL_STORE_expect() returns 1 on success, or 0 on failure.
	54
6ab6decc RL	55	OSSL_STORE_supports_search() returns 1 if the criterion is supported, or 0
	56	otherwise.
	57
	58	OSSL_STORE_find() returns 1 on success, or 0 on failure.
	59
ce9586b9 RL	60	=head1 SEE ALSO
ce9586b9 RL	61
6ab6decc RL	62	L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_SEARCH(3)>,
6ab6decc RL	63	L<OSSL_STORE_load(3)>
ce9586b9 RL	64
	65	=head1 HISTORY
	66
6ab6decc	67	OSSL_STORE_expect(), OSSL_STORE_supports_search() and OSSL_STORE_find()
fc5ecadd	68	were added in OpenSSL 1.1.1.
ce9586b9 RL	69
	70	=head1 COPYRIGHT
	71
	72	Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
	73
4746f25a	74	Licensed under the Apache License 2.0 (the "License"). You may not use
ce9586b9 RL	75	this file except in compliance with the License. You can obtain a copy
	76	in the file LICENSE in the source distribution or at
	77	L<https://www.openssl.org/source/license.html>.
	78
	79	=cut