> For the complete documentation index, see [llms.txt](https://docs.bugsplat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugsplat.com/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md). # BugSplat for Windows API Documentation *** ### Class: BugSplat #### Constructor ```cpp BugSplat(const wchar_t* database, const wchar_t* appName, const wchar_t* appVersion, LPTOP_LEVEL_EXCEPTION_FILTER lpTopLevelExceptionFilter = nullptr); ``` **Description:** Initializes a new BugSplat instance for crash reporting. **Parameters:** * `database` - The BugSplat database identifier * `appName` - Name of your application * `appVersion` - Version string of your application * `lpTopLevelExceptionFilter` - Optional custom top-level exception filter (default: nullptr) #### Destructor ```cpp ~BugSplat(); ``` **Description:** Cleans up BugSplat resources and restores original exception handlers. *** ### Configuration Methods #### SetQuietMode ```cpp void SetQuietMode(bool flag); ``` **Description:** Controls whether the crash report dialog is presented to the user (desktop applications only). QuietMode is off by default. **Parameters:** * `flag` - `true` to suppress the dialog, `false` to show it #### SetKey ```cpp void SetKey(const wchar_t* key); ``` **Description:** Sets the crash 'key' field for crash identification and grouping. **Parameters:** * `key` - Unique identifier string for this crash context #### SetUser ```cpp void SetUser(const wchar_t* user); ``` **Description:** Sets the default 'user' field. The crash dialog may allow users to override this value. **Parameters:** * `user` - Username or user identifier #### SetEmail ```cpp void SetEmail(const wchar_t* email); ``` **Description:** Sets the default 'email' field. The crash dialog may allow users to override this value. **Parameters:** * `email` - User's email address #### SetUserDescription ```cpp void SetUserDescription(const wchar_t* description); ``` **Description:** Sets the default 'userDescription' field. The crash dialog may allow users to override this value. **Parameters:** * `description` - User-provided description of what happened before the crash #### SetNotes ```cpp void SetNotes(const wchar_t* notes); ``` **Description:** Sets the initial value of the 'notes' field. BugSplat web application users can edit this field. **Parameters:** * `notes` - Additional notes or debugging information #### SetAttribute ```cpp void SetAttribute(const wchar_t* name, const wchar_t* value); ``` **Description:** Sets custom attributes that will be included with crash reports. **Parameters:** * `name` - Attribute name * `value` - Attribute value #### SetMiniDumpType ```cpp void SetMiniDumpType(MINIDUMP_TYPE dumpType); ``` **Description:** Configures the type of minidump to generate during crashes. **Parameters:** * `dumpType` - Windows MINIDUMP\_TYPE enumeration value #### SetHangDetectionTimeout ```cpp void SetHangDetectionTimeout(int ms); ``` **Description:** Sets the timeout used to determine if a process is hung. **Parameters:** * `ms` - Timeout in milliseconds (default: 5000). Use 0 to disable hang detection. *** ### Crash Detection & Reporting #### GenerateDump ```cpp void GenerateDump(LPEXCEPTION_POINTERS const exceptionPointers, MINIDUMP_TYPE dumpType = MINIDUMP_TYPE::MiniDumpNormal|MINIDUMP_TYPE::MiniDumpFilterTriage) const; ``` **Description:** Manually generates a BugSplat crash report with the specified exception information. **Parameters:** * `exceptionPointers` - Pointer to exception information structure * `dumpType` - Type of minidump to create (default: MiniDumpNormal|MiniDumpFilterTriage) #### CreateXmlReport ```cpp void CreateXmlReport(const wchar_t* xmlReport); ``` **Description:** Sends an XML report to BugSplat, bypassing minidump creation. Program execution continues normally after this call. **Parameters:** * `xmlReport` - XML-formatted report string **Note:** See MyConsoleCrasher.cpp for XML schema examples. #### CreateAsanReport ```cpp void CreateAsanReport(const char* asanReport); ``` **Description:** Creates a crash report specifically for AddressSanitizer (ASAN) errors. **Parameters:** * `asanReport` - ASAN error report string *** ### File Attachments #### AddAttachment ```cpp void AddAttachment(const wchar_t* filepath); ``` **Description:** Adds a file to be included with crash reports and feedback uploads. **Parameters:** * `filepath` - Full path to the file to attach #### RemoveAttachment ```cpp bool RemoveAttachment(const wchar_t* filepath); ``` **Description:** Removes a single file attachment from the attachment list. **Parameters:** * `filepath` - Full path to the file to remove **Returns:** `true` if the file was found and removed, `false` otherwise #### ClearAttachments ```cpp void ClearAttachments(); ``` **Description:** Removes all previously added file attachments. *** ### User Feedback #### PostFeedback ```cpp bool PostFeedback(const wchar_t* title, const wchar_t* description = L"", const std::vector& attachments = {}); ``` **Description:** Posts non-crashing user feedback such as bug reports or feature requests. Feedback reports appear in BugSplat with the "User Feedback" type, grouped by title. **Parameters:** * `title` - Feedback title, used as the stack key for grouping * `description` - Optional description of the feedback (default: empty string) * `attachments` - Optional list of file paths to include with the feedback (default: empty) **Returns:** `true` if the feedback was posted successfully, `false` otherwise **Note:** Attachments passed via the `attachments` parameter are automatically removed after upload. Attachments added via `AddAttachment()` are not affected. *** ### Crash Management #### PostCrash ```cpp void PostCrash(); ``` **Description:** Posts a single crash report and removes the folder after successful upload. #### PostAllCrashes ```cpp bool PostAllCrashes(); ``` **Description:** Posts all pending crash reports. This method blocks until completion. **Returns:** `true` if any crashes were posted, `false` otherwise **Note:** Should only be called on a new thread to avoid blocking the main application. #### PostAllCrashesAsync ```cpp bool PostAllCrashesAsync(); ``` **Description:** Posts all pending crash reports on a new background thread. **Returns:** Always returns `true` *** ### Utility Methods #### IsWerEnabled ```cpp bool IsWerEnabled(); ``` **Description:** Checks if Windows Error Reporting integration is currently enabled. **Returns:** `true` if WER integration is enabled, `false` otherwise #### AllocGuardMemory ```cpp void AllocGuardMemory(size_t nbytes); ``` **Description:** Allocates guard memory that is freed in the default GlobalExceptionFilter. By default, a three-megabyte guard memory block is created. **Parameters:** * `nbytes` - Number of bytes to allocate #### FreeGuardMemory ```cpp void FreeGuardMemory(); ``` **Description:** Frees previously allocated guard memory. #### GetCrashFolder ```cpp const wchar_t* GetCrashFolder(); ``` **Description:** Returns the folder path where current crash artifacts will be stored. **Returns:** Path string in format `R:\BugSplat\{unique-guid-string}` #### SetSuspendingState ```cpp void SetSuspendingState(BOOL status); ``` **Description:** Sets the suspending state for crash handling. **Parameters:** * `status` - Suspension status flag #### GetLogFilePath ```cpp const wchar_t* GetLogFilePath(); ``` **Description:** Returns the path to the BugSplat log file. **Returns:** Path string to log file #### CleanupExceptionSystem ```cpp void CleanupExceptionSystem(); ``` **Description:** Explicitly remove BugSplat's current working folder, log file, and crash state file. This function is needed on Xbox because the system terminates the monitor program and doesn't give it a chance to exit. *** ### Helper Functions #### CRT Exception Handling BugSplat provides helper functions to configure CRT (C Runtime) exception handling for comprehensive crash detection. **SetGlobalCRTExceptionBehavior** ```cpp inline void SetGlobalCRTExceptionBehavior(); ``` **Description:** Configures global CRT exception handlers. Should be called once during application initialization. **Configured Handlers:** * `set_terminate()` - Handles C++ termination * `_set_purecall_handler()` - Handles pure virtual function calls * `_set_invalid_parameter_handler()` - Handles invalid parameter errors * `_set_new_handler()` - Handles memory allocation failures **SetPerThreadCRTExceptionBehavior** ```cpp inline void SetPerThreadCRTExceptionBehavior(); ``` **Description:** Configures per-thread CRT exception handling. It should be called in each thread of your application. **Configured Handlers:** * Signal handling for SIGABRT * Abort behavior configuration *** ### Usage Examples #### Basic Initialization ```cpp #include "BugSplat.h" // Initialize BugSplat BugSplat BugSplat(L"MyDatabase", L"MyApp", L"1.0.0"); int main() { // Configure global CRT exception handling SetGlobalCRTExceptionBehavior(); // Configure per-thread CRT exception handling SetPerThreadCRTExceptionBehavior(); // Configure BugSplat options BugSplat.SetUser(L"john.doe"); BugSplat.SetEmail(L"john.doe@example.com"); BugSplat.SetKey(L"main-session"); // Your application code here... return 0; } ``` *** ### Notes and Best Practices 1. **Initialization:** Always call `SetGlobalCRTExceptionBehavior()` once during application startup. 2. **Thread Safety:** Call `SetPerThreadCRTExceptionBehavior()` in each thread that should report crashes. 3. **File Attachments:** Be mindful of file sizes when adding attachments to avoid large uploads. 4. **Custom Attributes:** Use `SetAttribute()` to add context-specific information that will help with crash analysis. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bugsplat.com/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.