callout_handle.h

Go to the documentation of this file.

// Copyright (C) 2013-2026 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
#ifndef CALLOUT_HANDLE_H
#define CALLOUT_HANDLE_H
 
#include <exceptions/exceptions.h>
#include <hooks/library_handle.h>
#include <hooks/parking_lots.h>
#include <util/dhcp_space.h>
 
#include <cstdint>
#include <map>
#include <string>
#include <vector>
 
#include <boost/any.hpp>
#include <boost/shared_ptr.hpp>
 
namespace isc {
namespace hooks {
 
class ServerHooks;

 
class NoSuchArgument : public Exception {
public:
    NoSuchArgument(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

 
class NoSuchCalloutContext : public Exception {
public:
    NoSuchCalloutContext(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};
 
// Forward declaration of the library handle and related collection classes.
 
class CalloutManager;
class LibraryManagerCollection;

 
class CalloutHandle {
public:

    enum CalloutNextStep : uint16_t {
        NEXT_STEP_CONTINUE = 0, 
        NEXT_STEP_SKIP = 1,     
        NEXT_STEP_DROP = 2,     
        NEXT_STEP_PARK = 3      
    };
 

    typedef std::map<std::string, boost::any> ElementCollection;

    typedef std::map<int, ElementCollection> ContextCollection;

    CalloutHandle(const boost::shared_ptr<CalloutManager>& manager,
                  const boost::shared_ptr<LibraryManagerCollection>& lmcoll =
                        boost::shared_ptr<LibraryManagerCollection>());

    ~CalloutHandle();

    template <typename T>
    void setArgument(const std::string& name, T value) {
        arguments_[name] = value;
    }

    template <typename T>
    void getArgument(const std::string& name, T& value) const {
        ElementCollection::const_iterator element_ptr = arguments_.find(name);
        if (element_ptr == arguments_.end()) {
            isc_throw(NoSuchArgument, "unable to find argument with name " <<
                      name);
        }
 
        value = boost::any_cast<T>(element_ptr->second);
    }

    std::vector<std::string> getArgumentNames() const;

    void deleteArgument(const std::string& name) {
        static_cast<void>(arguments_.erase(name));
    }

    void deleteAllArguments() {
        arguments_.clear();
    }

    void setStatus(const CalloutNextStep next) {
        next_step_ = next;
    }

    CalloutNextStep getStatus() const {
        return (next_step_);
    }

    template <typename T>
    void setContext(const std::string& name, T value) {
        getContextForLibrary()[name] = value;
    }

    template <typename T>
    void getContext(const std::string& name, T& value) const {
        const ElementCollection& lib_context = getContextForLibrary();
 
        ElementCollection::const_iterator element_ptr = lib_context.find(name);
        if (element_ptr == lib_context.end()) {
            isc_throw(NoSuchCalloutContext, "unable to find callout context "
                      "item " << name << " in the context associated with "
                      "current library");
        }
 
        value = boost::any_cast<T>(element_ptr->second);
    }

    template <typename T>
    bool getOptionalContext(const std::string& name, T& value) const {
        const auto context_iter = context_collection_.find(current_library_);
        if (context_iter == context_collection_.end()) {
            // No context, punt.
            return (false);
        }
 
        auto lib_context = context_iter->second;
        ElementCollection::const_iterator element_ptr = lib_context.find(name);
        if (element_ptr == lib_context.end()) {
            return (false);
        }
 
        value = boost::any_cast<T>(element_ptr->second);
        return (true);
    }

    std::vector<std::string> getContextNames() const;

    void deleteContext(const std::string& name) {
        static_cast<void>(getContextForLibrary().erase(name));
    }

    void deleteAllContext() {
        getContextForLibrary().clear();
    }

    std::string getHookName() const;

    ParkingLotHandlePtr getParkingLotHandlePtr() const;

    int getCurrentLibrary() const {
        return (current_library_);
    }

    void setCurrentLibrary(int library_index) {
        current_library_ = library_index;
    }

    int getCurrentHook() const {
        return (current_hook_);
    }

    void setCurrentHook(int hook_index) {
        current_hook_ = hook_index;
    }
 
private:

    int getLibraryIndex() const;

    ElementCollection& getContextForLibrary();

    const ElementCollection& getContextForLibrary() const;
 
    // Member variables

    boost::shared_ptr<LibraryManagerCollection> lm_collection_;

    ElementCollection arguments_;

    ContextCollection context_collection_;

    boost::shared_ptr<CalloutManager> manager_;

    ServerHooks& server_hooks_;

    int current_library_;

    int current_hook_;

    CalloutNextStep next_step_;
};

typedef boost::shared_ptr<CalloutHandle> CalloutHandlePtr;

class ScopedCalloutHandleState {
public:

    explicit ScopedCalloutHandleState(const CalloutHandlePtr& callout_handle);

    ~ScopedCalloutHandleState();

    std::function<void()> on_completion_;
 
private:

    void resetState();

    CalloutHandlePtr callout_handle_;
};
 
} // namespace hooks
} // namespace isc
 
 
#endif // CALLOUT_HANDLE_H