Add botan_ffi_supports_api function

This lets us upgrade the FFI version over time and still allow
applications to reliably detect if the current library binary
supports their version.

As an example, it would be useful to be able to add features to FFI
sometime in 2.x. In that case, we would increase the value of the
FFI API version, even though anything calling the old API would still
work perfectly. Applications can verify at runtime the API they want to
use is supported using this new call.

2 files changed, 17 insertions, 0 deletions

diff --git a/src/lib/ffi/ffi.cpp b/src/lib/ffi/ffi.cpp
index 4727c0763..5c4cba4e7 100644
--- a/src/lib/ffi/ffi.cpp
+++ b/src/lib/ffi/ffi.cpp
@@ -208,6 +208,17 @@ uint32_t botan_ffi_api_version()
    return BOTAN_HAS_FFI;
    }
 
+int botan_ffi_supports_api(uint32_t api_version)
+   {
+   /*
+   * In the future if multiple versions are supported, this
+   * function would accept any of them.
+   */
+   if(api_version == BOTAN_HAS_FFI)
+      return 0;
+   return -1;
+   }
+
 const char* botan_version_string()
    {
    return Botan::version_cstr();
diff --git a/src/lib/ffi/ffi.h b/src/lib/ffi/ffi.h
index ed1b55a56..3378e0dcd 100644
--- a/src/lib/ffi/ffi.h
+++ b/src/lib/ffi/ffi.h
@@ -66,6 +66,12 @@ how to provide the cleanest API for such users would be most welcome.
 */
 BOTAN_DLL uint32_t botan_ffi_api_version();
 
+/*
+* Return 0 (ok) if the version given is one this library supports.
+* botan_ffi_supports_api(botan_ffi_api_version()) will always return 0.
+*/
+BOTAN_DLL int botan_ffi_supports_api(uint32_t api_version);
+
 BOTAN_DLL const char* botan_version_string();
 BOTAN_DLL uint32_t botan_version_major();
 BOTAN_DLL uint32_t botan_version_minor();