Plugins: Add PluginEventInfo and IPostProcessMetadata

Il2CppInspector.Common/IL2CPP/Metadata.cs

@@ -50,30 +50,38 @@ namespace Il2CppInspector
 
         public Metadata(MemoryStream stream, EventHandler<string> statusCallback = null) : base(stream)
         {
-            // Read magic bytes
+            // Pre-processing hook
-            if (ReadUInt32() != 0xFAB11BAF) {
+            var pluginResult = PluginHooks.PreProcessMetadata(stream);
+            IsModified = pluginResult.IsStreamModified;
+
+            // Read metadata header
+            Header = ReadObject<Il2CppGlobalMetadataHeader>(0);
+
+            // Check for correct magic bytes
+            if (Header.signature != Il2CppConstants.MetadataSignature) {
                 throw new InvalidOperationException("The supplied metadata file is not valid.");
             }
 
             // Set object versioning for Bin2Object from metadata version
-            Version = ReadInt32();
+            Version = Header.version;
 
-            // Rewind and read metadata header in full
+            if (Version < 16 || Version > 27) {
-            Header = ReadObject<Il2CppGlobalMetadataHeader>(0);
-            if (Version < 16 || Version > 27)
-            {
                 throw new InvalidOperationException($"The supplied metadata file is not of a supported version ({Header.version}).");
             }
 
+            // Rewind and read metadata header with the correct version settings
+            Header = ReadObject<Il2CppGlobalMetadataHeader>(0);
+
             // Sanity checking
             // Unity.IL2CPP.MetadataCacheWriter.WriteLibIl2CppMetadata always writes the metadata information in the same order it appears in the header,
             // with each block always coming directly after the previous block, 4-byte aligned. We can use this to check the integrity of the data and
             // detect sub-versions.
 
-            // For metadata v24, the header can either be either 0x110 (24.0, 24.1) or 0x108 (24.2) bytes long. Since 'stringLiteralOffset' is the first thing
+            // For metadata v24.0, the header can either be either 0x110 (24.0, 24.1) or 0x108 (24.2) bytes long. Since 'stringLiteralOffset' is the first thing
             // in the header after the sanity and version fields, and since it will always point directly to the first byte after the end of the header,
             // we can use this value to determine the actual header length and therefore narrow down the metadata version to 24.0/24.1 or 24.2.
 
+            if (!pluginResult.AdditionalData.SkipValidation) {
                 var realHeaderLength = Header.stringLiteralOffset;
 
                 if (realHeaderLength != Sizeof(typeof(Il2CppGlobalMetadataHeader))) {
@@ -86,6 +94,7 @@ namespace Il2CppInspector
                 if (realHeaderLength != Sizeof(typeof(Il2CppGlobalMetadataHeader))) {
                     throw new InvalidOperationException("Could not verify the integrity of the metadata file or accurately identify the metadata sub-version");
                 }
+            }
             
             // Load all the relevant metadata using offsets provided in the header
             if (Version >= 16)
@@ -219,7 +228,7 @@ namespace Il2CppInspector
                 StringLiterals[i] = ReadFixedLengthString(Header.stringLiteralDataOffset + stringLiteralList[i].dataIndex, stringLiteralList[i].length);
 
             // Post-processing hook
-            PluginHooks.PostProcessMetadata(this);
+            IsModified |= PluginHooks.PostProcessMetadata(this).IsStreamModified;
         }
 
         // Save metadata to file, overwriting if necessary

Il2CppInspector.Common/IL2CPP/MetadataClasses.cs

@@ -38,7 +38,7 @@ namespace Il2CppInspector
 #pragma warning disable CS0649
     public class Il2CppGlobalMetadataHeader
     {
-        public uint sanity;
+        public uint signature;
         public int version;
         public int stringLiteralOffset; // string data for managed code
         public int stringLiteralCount;

Il2CppInspector.Common/Plugins/API/V100/Hooks.cs

@@ -4,13 +4,25 @@
     All rights reserved.
 */
 
+using System;
+using System.IO;
+
 namespace Il2CppInspector.PluginAPI.V100
 {
+    /// <summary>
+    /// Process global-metadata.dat when it is first opened as a sequence of bytes
+    /// Seek cursor will be at the start of the file
+    /// </summary>
+    public interface IPreProcessMetadata
+    {
+        void PreProcessMetadata(MemoryStream stream, PluginPreProcessMetadataEventInfo data);
+    }
+
     /// <summary>
     /// Process global-metadata.dat after it has been loaded into a Metadata object
     /// </summary>
     public interface IPostProcessMetadata
     {
-        void PostProcessMetadata(Metadata metadata);
+        void PostProcessMetadata(Metadata metadata, PluginPostProcessMetadataEventInfo data);
     }
 }

Il2CppInspector.Common/Plugins/API/V100/PluginEventInfo.cs

@@ -0,0 +1,92 @@
+/*
+    Copyright 2020 Katy Coe - http://www.djkaty.com - https://github.com/djkaty
+
+    All rights reserved.
+*/
+
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Il2CppInspector.PluginAPI.V100
+{
+    public interface IPluginEventInfo
+    {
+        public bool IsHandled { get; set; }
+        public bool IsInvalid { get; set; }
+        public bool IsDataModified { get; set; }
+        public bool IsStreamModified { get; set; }
+        public PluginErrorEventArgs Error { get; set; }
+    }
+
+    /// <summary>
+    /// Object which allows plugins to report on what has happened during a call
+    /// Changes made to this object propagate to the next plugin in the call chain until IsHandled is set to true
+    /// </summary>
+    public class PluginEventInfo<T> : IPluginEventInfo where T : new()
+    {
+        /// <summary>
+        /// A plugin should set this if it has processed the supplied data in such a way that no further processing is required by other plugins
+        /// Generally, this will prevent other plugins from processing the data
+        /// Note that this should be set even if the processed data was invalid (<seealso cref="IsInvalid"/>)
+        /// If this is not set, the same event will be raised on the next available plugin
+        /// Note that you can still do processing but set IsHandled to false to allow additional processing from other plugins
+        /// </summary>
+        public bool IsHandled { get; set; } = false;
+
+        /// <summary>
+        /// A plugin should set this when IsHandled = true but the data it processed was invalid, for example if the processing gave an unexpected result
+        /// </summary>
+        public bool IsInvalid { get; set; } = false;
+
+        /// <summary>
+        /// A plugin should set this when it has directly modified the provided data structure (object)
+        /// This can be set even if IsHandled = false to indicate that changes have been made but more plugins can still be called
+        /// Should be set to false if you have only queried (performed reads) on the data without changing it
+        /// </summary>
+        public bool IsDataModified { get; set; } = false;
+
+        /// <summary>
+        /// A plugin should set this when it has directly modified the supplied or underlying stream for the metadata or binary
+        /// This can be set even if IsHandled = false to indicate that changes have been made but more plugins can still be called
+        /// Should be set to false if you have only queried (performed reads) on the stream without changing it
+        /// </summary>
+        public bool IsStreamModified { get; set; } = false;
+
+        /// <summary>
+        /// Event-specific additional options and controls. See the documentation for each event for more details.
+        /// </summary>
+        public T AdditionalData { get; } = new T();
+
+        /// <summary>
+        /// This wiil be set automatically by Il2CppInspector to the last exception thrown by a plugin for the current event
+        /// </summary>
+        public PluginErrorEventArgs Error { get; set; } = null;
+    }
+
+    /// <summary>
+    /// Generic event info with no additional paramters
+    /// </summary>
+    public class PluginEventInfo : PluginEventInfo<object> { }
+
+    /// <summary>
+    /// Event info for PreProcessMetadata
+    /// </summary>
+    public class PluginPreProcessMetadataEventInfo : PluginEventInfo<PluginPreProcessMetadataEventData> { }
+
+    /// <summary>
+    /// Event info for PostProcessMetadata
+    /// </summary>
+    public class PluginPostProcessMetadataEventInfo : PluginEventInfo { }
+
+    /// <summary>
+    /// Additional data for PreProcessMetadata
+    /// </summary>
+    public class PluginPreProcessMetadataEventData
+    {
+        /// <summary>
+        /// Set to true to disable some validation checks by Il2CppInspector that the metadata is valid
+        /// </summary>
+        public bool SkipValidation { get; set; }
+    }
+}

Il2CppInspector.Common/Plugins/PluginHooks.cs

@@ -5,6 +5,7 @@
 */
 
 // This is the ONLY line to update when the API version changes
+using System.IO;
 using Il2CppInspector.PluginAPI.V100;
 
 namespace Il2CppInspector
@@ -12,6 +13,13 @@ namespace Il2CppInspector
     // Hooks we provide to plugins which can choose whether or not to provide implementations
     internal static class PluginHooks
     {
-        public static void PostProcessMetadata(Metadata metadata) => PluginManager.Try<IPostProcessMetadata>(p => p.PostProcessMetadata(metadata));
+        public static PluginPostProcessMetadataEventInfo PostProcessMetadata(Metadata metadata)
+            => PluginManager.Try<IPostProcessMetadata, PluginPostProcessMetadataEventInfo>((p, e) => p.PostProcessMetadata(metadata, e));
+
+        public static PluginPreProcessMetadataEventInfo PreProcessMetadata(MemoryStream stream)
+            => PluginManager.Try<IPreProcessMetadata, PluginPreProcessMetadataEventInfo>((p, e) => {
+                    stream.Position = 0;
+                    p.PreProcessMetadata(stream, e);
+                });
     }
 }

Il2CppInspector.Common/Plugins/PluginManager.cs

@@ -209,15 +209,24 @@ namespace Il2CppInspector
 
         // Try to cast each enabled plugin to a specific interface type, and for those supporting the interface, execute the supplied delegate
         // Errors will be forwarded to the error handler
-        internal static void Try<I>(Action<I> action) {
+        internal static E Try<I, E>(Action<I, E> action) where E : IPluginEventInfo, new()
+        {
+            var eventInfo = new E();
+
             foreach (var plugin in EnabledPlugins)
                 if (plugin is I p)
                     try {
-                        action(p);
+                        action(p, eventInfo);
+
+                        if (eventInfo.IsHandled)
+                            break;
                     }
                     catch (Exception ex) {
-                        ErrorHandler?.Invoke(AsInstance, new PluginErrorEventArgs { Plugin = plugin, Exception = ex, Operation = typeof(I).Name });
+                        eventInfo.Error = new PluginErrorEventArgs { Plugin = plugin, Exception = ex, Operation = typeof(I).Name };
+                        ErrorHandler?.Invoke(AsInstance, eventInfo.Error);
                     }
+
+            return eventInfo;
         }
 
         // Process an incoming status update