// iKSCrash.h
// B4i wrapper for KSCrash 2.x (https://github.com/kstenerud/KSCrash)
//
// SETUP INSTRUCTIONS:
// 1. In Xcode, add KSCrash via SPM: https://github.com/kstenerud/KSCrash.git
//    Add products: KSCrashRecording, KSCrashInstallations, KSCrashFilters, KSCrashSinks
// 2. Compile the wrapper as a static library (arm64 slice) -> iKSCrash.a
// 3. Run B4iH2XML on this file to produce iKSCrash.xml
// 4. Copy iKSCrash.a + iKSCrash.h to the Mac server Libs folder
// 5. Copy iKSCrash.xml to the IDE Libraries folder
//
// NOTE: KSCrash itself must also be present as a compiled .a or .xcframework
// in the Mac server Libs folder (see DependsOn directives below).

#import <Foundation/Foundation.h>

//~version:1.00
//~dependsOn:libKSCrashRecording.a
//~dependsOn:libKSCrashInstallations.a
//~dependsOn:libKSCrashFilters.a
//~dependsOn:libKSCrashSinks.a

// ---------------------------------------------------------------------------
// iKSCrashInstallation
// Main entry point: install the crash reporter and send reports.
// ---------------------------------------------------------------------------
//~FullType:B4iKSCrashInstallation
//~ShortType:KSCrashInstallation
@interface B4iKSCrashInstallation : NSObject

// ---------------------------------------------------------------------------
// Install with default configuration (catches Mach exceptions + signals).
// Call once from Application_Start (or AppDelegate didFinishLaunching).
// ---------------------------------------------------------------------------
//~version:1.00
- (void) Install;

// ---------------------------------------------------------------------------
// Install with custom monitor types.
//   monitors: A comma-separated string of monitor names to enable.
//   Supported values: "machException", "signal", "cppException",
//                     "objcException", "mainThreadDeadlock", "zombie"
//   Example: "machException,signal,cppException"
// ---------------------------------------------------------------------------
//~version:1.00
- (void) InstallWithMonitors: (NSString*) monitors;

// ---------------------------------------------------------------------------
// Set the URL where crash reports will be POSTed (Standard installation).
//   reportUrl: Full URL string, e.g. "https://yourserver.com/crashes"
// ---------------------------------------------------------------------------
//~version:1.00
- (void) SetReportUrl: (NSString*) reportUrl;

// ---------------------------------------------------------------------------
// Send all pending crash reports to the configured URL.
// The event "ReportsSent" is raised when done.
//   EventName: Name used to raise the ReportsSent event in B4i.
// ---------------------------------------------------------------------------
//~version:1.00
//~event:ReportsSent(Success As Boolean, ReportCount As Int)
- (void) SendAllReports: (NSString*) EventName;

// ---------------------------------------------------------------------------
// Print all pending crash reports to the Xcode console (for debugging).
// ---------------------------------------------------------------------------
//~version:1.00
- (void) PrintAllReportsToConsole;

// ---------------------------------------------------------------------------
// Delete all pending crash reports without sending them.
// ---------------------------------------------------------------------------
//~version:1.00
- (void) DeleteAllReports;

// ---------------------------------------------------------------------------
// Set arbitrary user info that will be included in every crash report.
//   key:   A string key
//   value: A string value
// Call this as many times as needed before or after Install.
// ---------------------------------------------------------------------------
//~version:1.00
- (void) SetUserInfoKey: (NSString*) key Value: (NSString*) value;

// ---------------------------------------------------------------------------
// Remove a previously set user info key.
// ---------------------------------------------------------------------------
//~version:1.00
- (void) RemoveUserInfoKey: (NSString*) key;

// ---------------------------------------------------------------------------
// Report a custom (scripting-language) exception with a stack trace.
//   name:            Exception name
//   reason:          Human-readable reason string
//   language:        Language name (e.g. "Lua", "JavaScript")
//   lineOfCode:      Line descriptor, e.g. "myScript.lua:42"
//   stackTrace:      Newline-separated stack trace string
//   terminateApp:    Pass True to also terminate the app after recording
// ---------------------------------------------------------------------------
//~version:1.00
- (void) ReportCustomException: (NSString*) name
                        Reason: (NSString*) reason
                      Language: (NSString*) language
                    LineOfCode: (NSString*) lineOfCode
                    StackTrace: (NSString*) stackTrace
                  TerminateApp: (BOOL) terminateApp;

// ---------------------------------------------------------------------------
// Returns True if the app crashed on the previous launch.
// ---------------------------------------------------------------------------
//~version:1.00
- (BOOL) DidCrashLastLaunch;

// ---------------------------------------------------------------------------
// Returns the number of pending (unsent) crash reports.
// ---------------------------------------------------------------------------
//~version:1.00
- (int) PendingReportCount;

// ---------------------------------------------------------------------------
// Enable or disable introspection of objects in memory at crash time.
// Disabled by default to keep reports lean; enable for deeper diagnostics.
// ---------------------------------------------------------------------------
//~version:1.00
- (void) SetIntrospectMemory: (BOOL) enabled;

// ---------------------------------------------------------------------------
// Enable or disable zombie (deallocated object access) detection.
// Small runtime overhead; very helpful for dangling-pointer bugs.
// ---------------------------------------------------------------------------
//~version:1.00
- (void) SetZombieTrackingEnabled: (BOOL) enabled;

@end