e1n.h

Go to the documentation of this file.

/*
 * This software was developed at the National Institute of Standards and
 * Technology (NIST) by employees of the Federal Government in the course
 * of their official duties. Pursuant to title 17 Section 105 of the
 * United States Code, this software is not subject to copyright protection
 * and is in the public domain. NIST assumes no responsibility whatsoever for
 * its use by other parties, and makes no guarantees, expressed or implied,
 * about its quality, reliability, or any other characteristic.
 */

 
#ifndef FRIF_EVALUATIONS_E1N_H_
#define FRIF_EVALUATIONS_E1N_H_
 
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <tuple>
#include <vector>
 
#include <frifte/frifte.h>

namespace FRIF::Evaluations::Exemplar1N
{
        LibraryIdentifier
        getLibraryIdentifier();

        class ExtractionInterface
        {
        public:
                struct Compatibility
                {
                        bool supportsProbeTemplateIntrospection{};

                        bool supportsReferenceTemplateIntrospection{};

                        std::set<uint16_t> probeTemplateVersions{};

                        std::set<uint16_t> referenceTemplateVersions{};

                        std::set<uint16_t> referenceDatabaseVersions{};
                };

                virtual
                std::tuple<ReturnStatus, std::optional<CreateTemplateResult>>
                createTemplate(
                    const TemplateType templateType,
                    const std::string &identifier,
                    const std::vector<Sample> &samples)
                    const = 0;

                virtual
                std::optional<std::tuple<ReturnStatus,
                    std::vector<TemplateData>>>
                extractTemplateData(
                    const TemplateType templateType,
                    const CreateTemplateResult &templateResult)
                    const = 0;

                virtual
                ReturnStatus
                createReferenceDatabase(
                    const TemplateArchive &referenceTemplates,
                    const std::filesystem::path &databaseDirectory,
                    const uint64_t maxSize)
                    const = 0;
 
                /**************************************************************/

                static
                std::shared_ptr<ExtractionInterface>
                getImplementation(
                    const std::filesystem::path &configurationDirectory);

                static
                std::optional<ProductIdentifier>
                getProductIdentifier();

                static
                Compatibility
                getCompatibility();

                ExtractionInterface(const ExtractionInterface&) = delete;
                ExtractionInterface& operator=(const ExtractionInterface&) =
                    delete;
 
                ExtractionInterface();
                virtual ~ExtractionInterface();
        };

        class SearchInterface
        {
        public:
                struct Compatibility
                {
                        bool supportsCorrespondence{};

                        std::set<uint16_t> probeTemplateVersions{};

                        std::set<uint16_t> referenceDatabaseVersions{};
                };

                virtual
                ReturnStatus
                load(
                    const uint64_t maxSize) = 0;
 
                /**************************************************************/

                virtual
                std::tuple<ReturnStatus,
                    std::optional<SearchSubjectPositionResult>>
                searchSubjectPosition(
                    const std::vector<std::byte> &probeTemplate,
                    const uint16_t maxCandidates)
                    const = 0;

                virtual
                std::tuple<ReturnStatus, std::optional<SearchSubjectResult>>
                searchSubject(
                    const std::vector<std::byte> &probeTemplate,
                    const uint16_t maxCandidates)
                    const = 0;

                virtual
                std::optional<SubjectPositionCandidateListCorrespondence>
                extractCorrespondenceSubjectPosition(
                    const std::vector<std::byte> &probeTemplate,
                    const SearchSubjectPositionResult &searchResult)
                    const = 0;

                virtual
                std::optional<SubjectCandidateListCorrespondence>
                extractCorrespondenceSubject(
                    const std::vector<std::byte> &probeTemplate,
                    const SearchSubjectResult &searchResult)
                    const = 0;
 
                /**************************************************************/

                static
                std::shared_ptr<SearchInterface>
                getImplementation(
                    const std::filesystem::path &configurationDirectory,
                    const std::filesystem::path &databaseDirectory);

                static
                std::optional<ProductIdentifier>
                getProductIdentifier();

                static
                Compatibility
                getCompatibility();

                SearchInterface(const SearchInterface&) = delete;
                SearchInterface& operator=(const SearchInterface&) = delete;
 
                SearchInterface();
                virtual ~SearchInterface();
        };
 
        /*
         * API versioning.
         *
         * NIST code will extern the version number symbols. Participant code
         * shall compile them into their core library.
         */
        #ifdef NIST_EXTERN_FRIFTE_E1N_API_VERSION
        extern uint16_t API_MAJOR_VERSION;
        extern uint16_t API_MINOR_VERSION;
        extern uint16_t API_PATCH_VERSION;
        #else /* NIST_EXTERN_FRIFTE_E1N_API_VERSION */
        uint16_t API_MAJOR_VERSION{1};
        uint16_t API_MINOR_VERSION{2};
        uint16_t API_PATCH_VERSION{0};
        #endif /* NIST_EXTERN_FRIFTE_E1N_API_VERSION */
}
 
#endif /* FRIF_EVALUATIONS_E1N_H_ */