STORE: Add documentation on search criteria

[openssl.git] / doc / man3 / OSSL_STORE_LOADER.pod

diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod
index aa64f2d77393a3cca4ffc0984595656de2d95eca..e827434192d905cd47004b98bfcdf377d0b80f56 100644 (file)
--- a/doc/man3/OSSL_STORE_LOADER.pod
+++ b/doc/man3/OSSL_STORE_LOADER.pod
@@ -5,12 +5,12 @@
 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, 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_expect, OSSL_STORE_LOADER_set_find,

 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_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_expect_fn, OSSL_STORE_find_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
 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


@@ -42,6 +42,10 @@ unregister STORE loaders for different URI schemes
  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 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 int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
+                                   OSSL_STORE_SEARCH *criteria);
+ int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
+                                OSSL_STORE_find_fn find_function);

  typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
                                                 UI_METHOD *ui_method,
                                                 void *ui_data);
  typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
                                                 UI_METHOD *ui_method,
                                                 void *ui_data);


@@ -77,7 +81,8 @@ 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_expect_fn>,
 using B<struct ossl_store_loader_ctx_st { ... }>.
 
 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>
+B<OSSL_STORE_find_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.
 
 are the function pointer types used within a STORE loader.
 The functions pointed at define the functionality of the given loader.
 


@@ -122,6 +127,18 @@ 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.
 
 
 This function is expected to return 1 on success, 0 on error.
 

+=item B<OSSL_STORE_find_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
+B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
+to search for.
+
+When called with the loader context being B<NULL>, this function is expected
+to return 1 if the loader supports the criterion, otherwise 0.
+
+When called with the loader context being something other than B<NULL>, 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>
 =item B<OSSL_STORE_load_fn>
 
 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>