LSPlant/library/jni/include/lsplant.hpp

#pragma once

#include <jni.h>
#include <string_view>

/// \namespace namespace of LSPlant
namespace lsplant {

inline namespace v1 {
/// \struct InitInfo
struct InitInfo {
    /// \typedef Type of inline hook function.
    /// In \p std::function form so that user can use lambda expression with capture list.<br>
    /// \p target is the target function to be hooked.<br>
    /// \p hooker is the hooker function to replace the \p target function.<br>
    /// \p return is the backup function that points to the previous target function.
    /// it should return null if hook fails and nonnull if successes.
    using InlineHookFunType = std::function<void *(void *target, void *hooker)>;
    /// \typedef Type of inline unhook function.
    /// In \p std::function form so that user can use lambda expression with capture list.<br>
    /// \p func is the target function that is previously hooked.<br>
    /// \p return should indicate the status of unhooking.<br>
    using InlineUnhookFunType = std::function<bool(void *func)>;
    /// \typedef Type of symbol resolver to \p libart.so.
    /// In \p std::function form so that user can use lambda expression with capture list.<br>
    /// \p symbol_name is the symbol name that needs to retrieve.<br>
    /// \p return is the absolute address in the memory that points to the target symbol. It should
    /// be null if the symbol cannot be found. <br>
    /// \note It should be able to resolve symbols from both .dynsym and .symtab.
    using ArtSymbolResolver = std::function<void *(std::string_view symbol_name)>;

    /// \brief The inline hooker function. Must not be null.
    InlineHookFunType inline_hooker;
    /// \brief The inline unhooker function. Must not be null.
    InlineUnhookFunType inline_unhooker;
    /// \brief The symbol resolver to \p libart.so. Must not be null.
    ArtSymbolResolver art_symbol_resolver;

    /// \brief The generated class name. Must not be empty. It contains a field and a method
    /// and they could be set by \p generated_field_name and \p generated_method_name respectively.
    std::string_view generated_class_name = "LSPHooker_";
    /// \brief The generated source name. Could be empty.
    std::string_view generated_source_name = "LSP";
    /// \brief The generated field name. Must not be empty.
    std::string_view generated_field_name = "hooker";
    /// \brief The generated class name. Must not be emtpy. If {target} is set,
    /// it will follows the name of the target.
    std::string_view generated_method_name = "{target}";
};

/// \brief Initialize LSPlant for the proceeding hook.
/// It mainly prefetch needed symbols and hook some functions.
/// \param[in] env The Java environment. Must not be null.
/// \param[in] info The information for initialized. \ref InitInfo.
/// Basically, the info provides the inline hooker and unhooker together with a symbol resolver of
/// libart.so to hook and extract needed native functions of ART.
/// \return Indicate whether initialization succeed. Behavior is undefined if calling other
/// LSPlant interfaces before initialization or after a fail initialization.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
bool Init(JNIEnv *env, const InitInfo &info);

/// \brief Hook a Java method by providing the \p target_method together with the context object
/// \p hooker_object and its callback \p callback_method.
/// \param[in] env The Java environment. Must not be null.
/// \param[in] target_method The method id to the method you want to hook. Must not be null.
/// \param[in] hooker_object The hooker object to store the context of the hook.
/// The most likely usage is to store the \b backup method into it so that when \b callback_method
/// is invoked, it can call the original method. Another scenario is that, for example,
/// in Xposed framework, multiple modules can hook the same Java method and the \b hooker_object
/// can be used to store all the callbacks to allow multiple modules work simultaneously without
/// conflict.
/// \param[in] callback_method The callback method to the \p hooker_object is used to replace the
/// \p target_method. Whenever the \p target_method is invoked, the \p callback_method will be
/// inked instead of the original \p target_method. The signature of the \p callback_method must
/// be:<br>
/// \code{.java}
/// Object callback_method(Object []args)
/// \endcode<br>
/// That is, the return type must be \p Object and the parameter type must be \b Object[]. Behavior
/// is undefined if the signature does not match the requirement.
/// Extra info can be provided by defining member variables of \p hooker_object.
/// This method must be a method to \p hooker_object.
/// \return The backup method. You can invoke it by reflection to invoke the original method. null
/// if fails.
/// \note This function will automatically generate a stub class for hook. To help debug, you
/// can set the generated class name, its field name, its source name and its method name
/// by setting generated_* in \p InitInfo.
/// \note This function thread safe (you can call it simultaneously from multiple thread)
/// but it's not atomic to the same \b target_method. That means \p UnHook or \p IsUnhook does
/// not guarantee to work properly on the same \p target_method before it returns. Also,
/// simultaneously call on this function with the same \p target_method does not guarantee only one
/// will success. If you call this with different \p hooker_object on the same target_method
/// simultaneously, the behavior is undefined.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
jmethodID
Hook(JNIEnv *env, jmethodID target_method, jobject hooker_object, jmethodID callback_method);

/// Unhook a Java function that is previously hooked.
/// \param[in] env The Java environment.
/// \param[in] target_method The target method that is previously hooked.
/// \return Indicate whether the unhook succeed.
/// \note please read Hook's note for more details.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
bool UnHook(JNIEnv *env, jmethodID target_method);

/// Check if a Java function is hooked by LSPlant or not
/// \param[in] env The Java environment.
/// \param[in] method The method to check if it was hooked or not.
/// \return If \p method hooked, ture; otherwise, false.
/// \note please read Hook's note for more details.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
bool IsHooked(JNIEnv *env, jmethodID method);

/// Deoptimize a method to avoid hooked callee not being called because of inline
/// \param[in] env The Java environment.
/// \param[in] method The method to deoptimize. By deoptimizing the method, the method will back all
/// callee without inlining. For example, if you hooked a short method B that is invoked by method
/// A, and you find that your callback to B is not invoked after hooking, then it may mean A has
/// inlined B inside its method body. To force A to call your hooked B, you can deoptimize A and then
/// your hook can take effect. Generally, you need to find all the callers of your hooked callee
/// and that can be hardly achieve. Use this function if you are sure the deoptimized callers
/// are all you need. Otherwise, it would be better to change the hook point or to deoptimize the
/// whole app manually (by simple reinstall the app without uninstalled).
/// \return Indicate whether the deoptimizing succeed or not.
/// \note It is safe to call deoptimizing on a hooked method because the deoptimization will
/// perform on the backup method instead.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
bool Deoptimize(JNIEnv *env, jmethodID method);

/// Get the registered native function pointer of a native function. It helps user to hook native
/// methods directly by backing up the native function pointer this function returns and
/// env->registerNatives another native function pointer.
/// \param[in] env The Java environment.
/// \param[in] method The native method to get the native function pointer.
/// \return The native function pointer the \p method previously registered. If it has not been
/// registered or it is not a native method, null is returned instead.
[[nodiscard]] [[maybe_unused]] [[gnu::visibility("default")]]
void *GetNativeFunction(JNIEnv *env, jmethodID method);
}
} // namespace lsplant