From 9368effbe297cb38230b13e1c4203828bffdabc6 Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Thu, 11 Jun 2026 17:27:10 -0400 Subject: [PATCH 1/6] docs: C API and BugSplat.dll dynamic library for Windows C++ Documents the new flat C API (BugSplatC.h) and dynamic link model added in BugSplat-Git/bugsplat-windows#155: - Integration page: new "Dynamic Library" section covering when to choose the DLL (CRT independence, foreign-language bindings), linking against dynamic\BugSplat.lib, and shipping BugSplat.dll - API documentation: new "C API (BugSplatC.h)" section with linkage notes, BugSplat_Init/BugSplat_IsInitialized, a mapping table for the forwarding functions, and a usage example Co-Authored-By: Claude Opus 4.8 (1M context) --- .../integrations/desktop/cplusplus/README.md | 25 +++++++ .../bugsplat-for-windows-api-documentation.md | 67 +++++++++++++++++++ 2 files changed, 92 insertions(+) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/README.md b/introduction/getting-started/integrations/desktop/cplusplus/README.md index ae3d30f..c7ad37a 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/README.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/README.md @@ -48,6 +48,31 @@ symbol-upload-windows.exe -b your-database -a your-app -v your-version -i your-c To get complete symbolicated call stacks and variable names for each crash, you should upload all **`.exe`**, **`.dll`**, and **`.pdb`** files for your product every time you build a release version of your application for distribution or internal testing. {% endhint %} +### Dynamic Library 🔗 + +The SDK also ships as a dynamic library, **`BugSplat.dll`**, with a flat C API declared in **`BugSplatC.h`**. The DLL exposes the same crash reporting engine as `BugSplat.lib` through `BugSplat_*` functions. Choose the dynamic library when: + +* You don't want your runtime library setting (`/MT` vs `/MD`) coupled to BugSplat's — only the C ABI crosses the DLL boundary, so your application's CRT choice doesn't need to match the SDK's. +* You're calling BugSplat from another language (C#, Rust, Python, etc.) via P/Invoke or FFI. + +To integrate the dynamic library, follow the steps above with these differences: + +1. Link with the import library **`dynamic\BugSplat.lib`** instead of the static `BugSplat.lib`, and include **`BugSplatC.h`** instead of `BugSplat.h`. +2. Ship **`BugSplat.dll`** alongside your executable, in addition to `BugSplatMonitor.exe`, `BugSplatWer.dll`, and `BugSplatRc.dll`. +3. Initialize BugSplat with the C API: + +```cpp +#include "BugSplatC.h" + +BugSplat_Init(BUGSPLAT_DATABASE, APPLICATION_NAME, APPLICATION_VERSION); +BugSplat_SetUser(L"fred"); +BugSplat_SetAttribute(L"branch", L"main"); +``` + +{% hint style="info" %} +The C API is also available to static library consumers — define `BUGSPLAT_STATIC` before including `BugSplatC.h`. See the [API documentation](bugsplat-for-windows-api-documentation.md#c-api-bugsplatc.h) for the full list of `BugSplat_*` functions. +{% endhint %} + ### Verification ✅ Test your application by forcing a crash. diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index 90a782c..67e2997 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -395,6 +395,73 @@ inline void SetPerThreadCRTExceptionBehavior(); *** +### C API (BugSplatC.h) + +In addition to the `BugSplat` C++ class, the SDK exposes a flat C API declared in **`BugSplatC.h`**. The C API manages a single process-wide `BugSplat` instance and is the interface exported by the dynamic library, **`BugSplat.dll`**. Because only the C ABI crosses the DLL boundary, consumers of `BugSplat.dll` do not need to match the SDK's runtime library setting (`/MT` vs `/MD`), and any language with C FFI support (C#, Rust, Python, etc.) can call these functions directly. + +**Linkage:** + +* **Dynamic:** link the import library `dynamic\BugSplat.lib` and ship `BugSplat.dll` with your application. This is the default when including `BugSplatC.h` with no extra defines. +* **Static:** the C API is also compiled into the static `BugSplat.lib` — define `BUGSPLAT_STATIC` before including `BugSplatC.h`. + +All strings are null-terminated UTF-16 (`wchar_t*`). Boolean parameters and return values use `int` (`0`/`1`) for ABI stability. + +#### BugSplat\_Init + +```c +int BugSplat_Init(const wchar_t* database, const wchar_t* appName, const wchar_t* appVersion); +``` + +**Description:** Initializes crash reporting and installs the unhandled exception filter. Call once, early in your application's lifetime. + +**Returns:** `1` on success, `0` if already initialized or if any argument is null. + +#### BugSplat\_IsInitialized + +```c +int BugSplat_IsInitialized(void); +``` + +**Description:** Returns `1` if `BugSplat_Init` has been called successfully, `0` otherwise. + +#### Forwarding Functions + +The remaining functions forward to the equivalent `BugSplat` class methods documented above: + +| C function | Class method | +| ----------------------------------- | -------------------------- | +| `BugSplat_SetKey` | `SetKey` | +| `BugSplat_SetUser` | `SetUser` | +| `BugSplat_SetEmail` | `SetEmail` | +| `BugSplat_SetUserDescription` | `SetUserDescription` | +| `BugSplat_SetNotes` | `SetNotes` | +| `BugSplat_SetAttribute` | `SetAttribute` | +| `BugSplat_AddAttachment` | `AddAttachment` | +| `BugSplat_RemoveAttachment` | `RemoveAttachment` | +| `BugSplat_SetQuietMode` | `SetQuietMode` | +| `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | +| `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | + +#### C API Example + +```c +#include "BugSplatC.h" + +int main() { + BugSplat_Init(L"MyDatabase", L"MyApp", L"1.0.0"); + BugSplat_SetUser(L"john.doe"); + BugSplat_SetEmail(L"john.doe@example.com"); + BugSplat_SetQuietMode(1); + BugSplat_PostAllCrashesAsync(); + + // Your application code here... + + return 0; +} +``` + +*** + ### Usage Examples #### Basic Initialization From 8268e6fc4c0c3018ad80333cf904ccebb0225005 Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Mon, 15 Jun 2026 16:07:26 -0400 Subject: [PATCH 2/6] docs: document BugSplat_PostFeedback and BugSplat_CreateXmlReport Co-Authored-By: Claude Opus 4.8 (1M context) --- .../bugsplat-for-windows-api-documentation.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index 67e2997..c75743a 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -441,6 +441,29 @@ The remaining functions forward to the equivalent `BugSplat` class methods docum | `BugSplat_SetQuietMode` | `SetQuietMode` | | `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | | `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | +| `BugSplat_CreateXmlReport` | `CreateXmlReport` | + +#### BugSplat\_PostFeedback + +```c +int BugSplat_PostFeedback(const wchar_t* title, + const wchar_t* description, + const wchar_t* const* attachments, + int attachmentCount); +``` + +**Description:** Posts non-crashing user feedback such as a bug report or feature request. The title is used as the stack key for grouping feedback in the dashboard. + +**Parameters:** + +* `title` - Feedback title (also the grouping key) +* `description` - Optional description; may be `NULL` (treated as empty) +* `attachments` - Optional array of file paths, or `NULL` for none. These are included only in this feedback upload and do not affect attachments added via `BugSplat_AddAttachment` +* `attachmentCount` - Number of entries in `attachments` (0 if none) + +**Returns:** `1` on success, `0` on failure. + +**Note:** The C++ `BugSplat::PostFeedback` takes a `std::vector`, which cannot cross the DLL boundary. The C entry point takes an `(array, count)` pair instead so the C ABI stays free of STL types and remains compatible with `/MT` and non-C++ consumers. #### C API Example From 57ddd3b8b62c8ed3ce9a6f1376334f9477758e9d Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Mon, 15 Jun 2026 16:16:25 -0400 Subject: [PATCH 3/6] docs: document CreateAsanReport, SetMiniDumpType, and GenerateDump in C API Co-Authored-By: Claude Opus 4.8 (1M context) --- .../bugsplat-for-windows-api-documentation.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index c75743a..af767c7 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -442,6 +442,10 @@ The remaining functions forward to the equivalent `BugSplat` class methods docum | `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | | `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | | `BugSplat_CreateXmlReport` | `CreateXmlReport` | +| `BugSplat_CreateAsanReport` | `CreateAsanReport` | +| `BugSplat_SetMiniDumpType` | `SetMiniDumpType` | + +`BugSplat_SetMiniDumpType` takes the Windows `MINIDUMP_TYPE` flags as an `int`. `BugSplat_CreateAsanReport` takes a `const char*` (ASan reports are ASCII/UTF-8 text). #### BugSplat\_PostFeedback @@ -465,6 +469,19 @@ int BugSplat_PostFeedback(const wchar_t* title, **Note:** The C++ `BugSplat::PostFeedback` takes a `std::vector`, which cannot cross the DLL boundary. The C entry point takes an `(array, count)` pair instead so the C ABI stays free of STL types and remains compatible with `/MT` and non-C++ consumers. +#### BugSplat\_GenerateDump + +```c +void BugSplat_GenerateDump(void* exceptionPointers, int dumpType); +``` + +**Description:** Generates a crash report from caller-supplied exception information without terminating the process. Most applications do not need this — the exception filter installed by `BugSplat_Init` already captures unhandled crashes automatically. Use it only when you run your own exception handler and want to report a specific exception. + +**Parameters:** + +* `exceptionPointers` - An `EXCEPTION_POINTERS*` as provided by the OS inside an SEH `__except` filter (`GetExceptionInformation()`) or an unhandled-exception-filter callback. It is passed as `void*` so the header carries no `` dependency; it is not a value you construct. +* `dumpType` - A combination of Windows `MINIDUMP_TYPE` flags, or a negative value to use the SDK default. + #### C API Example ```c From a80290c06a65ab5c52fd2959dcc05b1de5e22c0b Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Mon, 15 Jun 2026 21:10:29 -0400 Subject: [PATCH 4/6] docs: document SetTerminateAfterCrash / BugSplat_SetTerminateAfterCrash Co-Authored-By: Claude Opus 4.8 (1M context) --- .../bugsplat-for-windows-api-documentation.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index af767c7..70966a7 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -143,6 +143,18 @@ void SetHangDetectionTimeout(int ms); * `ms` - Timeout in milliseconds (default: 5000). Use 0 to disable hang detection. +#### SetTerminateAfterCrash + +```cpp +void SetTerminateAfterCrash(bool terminate); +``` + +**Description:** Controls how the process ends after a crash report is created and uploaded. When `false` (the default), the handler calls `exit()`, which runs full C-runtime shutdown. When `true`, it calls `TerminateProcess` instead — a hard termination that avoids CRT-shutdown hangs in complex hosts (for example, a Unity standalone player whose process can hang on `exit()` after the report is sent). The dump is created and uploaded before either path, so reporting is unaffected. + +**Parameters:** + +* `terminate` - `true` to hard-terminate after a crash, `false` (default) to `exit()` + *** ### Crash Detection & Reporting @@ -440,6 +452,7 @@ The remaining functions forward to the equivalent `BugSplat` class methods docum | `BugSplat_RemoveAttachment` | `RemoveAttachment` | | `BugSplat_SetQuietMode` | `SetQuietMode` | | `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | +| `BugSplat_SetTerminateAfterCrash` | `SetTerminateAfterCrash` | | `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | | `BugSplat_CreateXmlReport` | `CreateXmlReport` | | `BugSplat_CreateAsanReport` | `CreateAsanReport` | From 6843756825d2182cc1b957619198523aa484587e Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Mon, 15 Jun 2026 21:23:31 -0400 Subject: [PATCH 5/6] docs: SetCrashCompletionBehavior (exit/terminate/continue-search) Supersedes the SetTerminateAfterCrash boolean docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../bugsplat-for-windows-api-documentation.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index 70966a7..229dd6a 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -143,17 +143,23 @@ void SetHangDetectionTimeout(int ms); * `ms` - Timeout in milliseconds (default: 5000). Use 0 to disable hang detection. -#### SetTerminateAfterCrash +#### SetCrashCompletionBehavior ```cpp -void SetTerminateAfterCrash(bool terminate); +enum class BugSplatCrashCompletion { Exit = 0, Terminate = 1, ContinueSearch = 2 }; + +void SetCrashCompletionBehavior(BugSplatCrashCompletion behavior); ``` -**Description:** Controls how the process ends after a crash report is created and uploaded. When `false` (the default), the handler calls `exit()`, which runs full C-runtime shutdown. When `true`, it calls `TerminateProcess` instead — a hard termination that avoids CRT-shutdown hangs in complex hosts (for example, a Unity standalone player whose process can hang on `exit()` after the report is sent). The dump is created and uploaded before either path, so reporting is unaffected. +**Description:** Controls what the crash handler does after the crash report has been created and uploaded. The dump is captured and sent before any of these paths, so reporting is unaffected by the choice: + +* `Exit` (default) - calls `exit()`, which runs full C-runtime shutdown. +* `Terminate` - calls `TerminateProcess`, a hard termination that avoids CRT-shutdown hangs in complex hosts (for example, a Unity standalone player whose process can hang on `exit()` after the report is sent). +* `ContinueSearch` - returns `EXCEPTION_CONTINUE_SEARCH` from the unhandled-exception filter, handing control to the operating system's default unhandled-exception handling (Windows Error Reporting, or an attached debugger) instead of ending the process itself. **Parameters:** -* `terminate` - `true` to hard-terminate after a crash, `false` (default) to `exit()` +* `behavior` - one of the `BugSplatCrashCompletion` values above (default `Exit`) *** @@ -452,7 +458,7 @@ The remaining functions forward to the equivalent `BugSplat` class methods docum | `BugSplat_RemoveAttachment` | `RemoveAttachment` | | `BugSplat_SetQuietMode` | `SetQuietMode` | | `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | -| `BugSplat_SetTerminateAfterCrash` | `SetTerminateAfterCrash` | +| `BugSplat_SetCrashCompletionBehavior` | `SetCrashCompletionBehavior` | | `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | | `BugSplat_CreateXmlReport` | `CreateXmlReport` | | `BugSplat_CreateAsanReport` | `CreateAsanReport` | From 558b1c6f0dcadc7a3d63b05440644aba25793fbd Mon Sep 17 00:00:00 2001 From: Bobby Galli Date: Mon, 15 Jun 2026 23:03:24 -0400 Subject: [PATCH 6/6] docs: document SetCrashType / BugSplat_SetCrashType (UnityNative=15) Co-Authored-By: Claude Opus 4.8 (1M context) --- .../bugsplat-for-windows-api-documentation.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md index 229dd6a..93239b5 100644 --- a/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md +++ b/introduction/getting-started/integrations/desktop/cplusplus/bugsplat-for-windows-api-documentation.md @@ -161,6 +161,18 @@ void SetCrashCompletionBehavior(BugSplatCrashCompletion behavior); * `behavior` - one of the `BugSplatCrashCompletion` values above (default `Exit`) +#### SetCrashType + +```cpp +void SetCrashType(int crashTypeId); +``` + +**Description:** Overrides the BugSplat crash type id stamped on uploaded crashes. By default native crashes are uploaded as `Native` (id `1`). Set this when a higher-level integration needs the server to process the crash differently — for example, a Unity IL2CPP integration sets `15` (`UnityNative`: "a native crash with an additional file containing the managed call stack"), which is the crash type the BugSplat backend uses to apply `LineNumberMappings.json` and symbolicate managed (C#) frames. + +**Parameters:** + +* `crashTypeId` - the BugSplat crash type id (default `1` = Native; `15` = UnityNative) + *** ### Crash Detection & Reporting @@ -459,6 +471,7 @@ The remaining functions forward to the equivalent `BugSplat` class methods docum | `BugSplat_SetQuietMode` | `SetQuietMode` | | `BugSplat_SetHangDetectionTimeout` | `SetHangDetectionTimeout` | | `BugSplat_SetCrashCompletionBehavior` | `SetCrashCompletionBehavior` | +| `BugSplat_SetCrashType` | `SetCrashType` | | `BugSplat_PostAllCrashesAsync` | `PostAllCrashesAsync` | | `BugSplat_CreateXmlReport` | `CreateXmlReport` | | `BugSplat_CreateAsanReport` | `CreateAsanReport` |