feat!: Add hint support to scope-level event capture

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 - Attachment APIs now use `sentry_value_t` and `sentry_uuid_t` instead of `sentry_attachment_t *` handles. Most attachment APIs, function names and arguments, are otherwise unchanged. ([#1974](https://github.com/getsentry/sentry-native/pull/1974))
 - `sentry_init()` now consumes `<db>/last_crash` after caching its value, aligning crashed-last-run behavior with other Sentry SDKs. ([#2023](https://github.com/getsentry/sentry-native/pull/2023))
+- Change the `hint` parameter of `before_send` callbacks (`sentry_event_function_t`) from `void *` to `sentry_hint_t *`. Update callbacks registered with `sentry_options_set_before_send` to use the new parameter type. ([#2099](https://github.com/getsentry/sentry-native/pull/2099))
+- Add a `sentry_hint_t *hint` argument to `sentry_scope_capture_event`. Pass `NULL` if no hint is needed. ([#2099](https://github.com/getsentry/sentry-native/pull/2099))
 - Remove `sentry_options_get/set_enable_logs` and `sentry_options_get/set_enable_metrics`. ([#1980](https://github.com/getsentry/sentry-native/pull/1980))
   > Structured logs and metrics have been enabled by default since `0.13`, and the options were deprecated and made no-ops in `0.16`.
   >
@@ -16,6 +18,8 @@
 - Add `sentry_attachment_from_file/bytes` (and their wide-string variants) for creating attachment values that can be fully configured before they are added. ([#2079](https://github.com/getsentry/sentry-native/pull/2079))
 - Add `sentry_add_attachment`, `sentry_scope_add_attachment`, and `sentry_hint_add_attachment` for adding configured attachments to the global scope, a specific scope, or a hint. These functions consume and freeze the attachment value. ([#2079](https://github.com/getsentry/sentry-native/pull/2079), [#1974](https://github.com/getsentry/sentry-native/pull/1974))
 - Add `sentry_start_new_trace()` as a clearer name for starting a new trace. ([#2095](https://github.com/getsentry/sentry-native/pull/2095))
+- Add hint support to `sentry_scope_capture_event` to pass event-specific attachments. The hint is also passed to `before_send`, which can modify attachments before the event is sent. ([#2099](https://github.com/getsentry/sentry-native/pull/2099))
+- Add `sentry_hint_get_attachments`, `sentry_hint_remove_attachment`, and `sentry_hint_clear_attachments`. ([#2099](https://github.com/getsentry/sentry-native/pull/2099))
 
 **Fixes**:
 

examples/example.c

@@ -127,7 +127,7 @@ traces_sampler_callback(const sentry_transaction_context_t *transaction_ctx,
 }
 
 static sentry_value_t
-before_send_callback(sentry_value_t event, void *hint, void *user_data)
+before_send_callback(sentry_value_t event, sentry_hint_t *hint, void *user_data)
 {
     (void)hint;
     (void)user_data;
@@ -142,7 +142,7 @@ before_send_callback(sentry_value_t event, void *hint, void *user_data)
 
 static sentry_value_t
 discarding_before_send_callback(
-    sentry_value_t event, void *hint, void *user_data)
+    sentry_value_t event, sentry_hint_t *hint, void *user_data)
 {
     (void)hint;
     (void)user_data;
@@ -1247,7 +1247,7 @@ main(int argc, char **argv)
             sentry_scope_add_attachment(scope, bytes);
         }
 
-        sentry_scope_capture_event(scope, event);
+        sentry_scope_capture_event(scope, event, NULL);
     }
 
     if (has_arg(argc, argv, "capture-multiple")) {

include/sentry.h

@@ -1478,6 +1478,13 @@ SENTRY_API void sentry_options_set_send_default_pii(
     sentry_options_t *opts, int value);
 #endif
 
+/**
+ * A hint that can be passed to capture functions to provide additional context,
+ * such as attachments.
+ */
+struct sentry_hint_s;
+typedef struct sentry_hint_s sentry_hint_t;
+
 /**
  * Type of the `before_send` callback.
  *
@@ -1486,6 +1493,9 @@ SENTRY_API void sentry_options_set_send_default_pii(
  * call `sentry_value_decref` on the provided event and return a
  * `sentry_value_new_null()` instead.
  *
+ * The hint is always provided and can be used to modify attachments on the
+ * event.
+ *
  * If you have set an `on_crash` callback (independent of whether it discards or
  * retains the event), `before_send` will no longer be invoked for crash-events,
  * which allows you to better distinguish between crashes and all other events
@@ -1510,7 +1520,7 @@ SENTRY_API void sentry_options_set_send_default_pii(
  * though a crash report will be sent.
  */
 typedef sentry_value_t (*sentry_event_function_t)(
-    sentry_value_t event, void *hint, void *user_data);
+    sentry_value_t event, sentry_hint_t *hint, void *user_data);
 
 /**
  * Sets the `before_send` callback.
@@ -2592,15 +2602,18 @@ SENTRY_API sentry_uuid_t sentry_scope_get_last_event_id(
 SENTRY_API sentry_uuid_t sentry_capture_event(sentry_value_t event);
 
 /**
- * Sends a sentry event with a scope.
+ * Sends a sentry event with a scope and a hint.
+ *
+ * This function takes ownership of the event and hint, which will be freed
+ * automatically. The hint may be NULL.
  *
  * If `scope` is a local scope (`sentry_local_scope_new`), this takes ownership
  * of it and frees it. If `scope` is user-owned (`sentry_scope_new` or
  * `sentry_scope_clone`), it is applied but not freed, so it can be reused; free
  * it yourself with `sentry_scope_free`.
  */
 SENTRY_API sentry_uuid_t sentry_scope_capture_event(
-    sentry_scope_t *scope, sentry_value_t event);
+    sentry_scope_t *scope, sentry_value_t event, sentry_hint_t *hint);
 
 /**
  * Deprecated alias for `sentry_scope_capture_event`. Note the reversed argument
@@ -4139,16 +4152,7 @@ SENTRY_API sentry_value_t sentry_value_new_feedback_n(const char *message,
 SENTRY_API void sentry_capture_feedback(sentry_value_t user_feedback);
 
 /**
- * A hint that can be passed to capture functions to provide additional context,
- * such as attachments.
- */
-struct sentry_hint_s;
-typedef struct sentry_hint_s sentry_hint_t;
-
-/**
- * Creates a new hint to be passed into
- * - `sentry_capture_feedback_with_hint`
- * - `sentry_scope_capture_feedback`
+ * Creates a new hint to be passed into capture functions.
  */
 SENTRY_API sentry_hint_t *sentry_hint_new(void);
 
@@ -4202,6 +4206,24 @@ SENTRY_API sentry_uuid_t sentry_hint_attach_bytesw_n(sentry_hint_t *hint,
     size_t filename_len);
 #endif
 
+/**
+ * Returns a borrowed list of attachments in the hint, or a null value if the
+ * hint is NULL.
+ */
+SENTRY_API sentry_value_t sentry_hint_get_attachments(
+    const sentry_hint_t *hint);
+
+/**
+ * Removes an attachment from the hint by its ID. Does not modify scopes.
+ */
+SENTRY_API void sentry_hint_remove_attachment(
+    sentry_hint_t *hint, sentry_uuid_t attachment_id);
+
+/**
+ * Removes all attachments from the hint. Does not modify scopes.
+ */
+SENTRY_API void sentry_hint_clear_attachments(sentry_hint_t *hint);
+
 /**
  * Captures a manually created feedback with a hint and sends it to Sentry.
  *
@@ -4237,7 +4259,8 @@ SENTRY_API sentry_uuid_t sentry_scope_capture_feedback(
  * callback needs to call `sentry_value_decref` on the provided event and
  * return a `sentry_value_new_null()` instead.
  *
- * The hint is always provided and can be used to add attachments to the event.
+ * The hint is always provided and can be used to modify attachments on the
+ * event.
  *
  * Feedback events do not go through the `before_send` callback.
  */

src/backends/sentry_backend_breakpad.cpp

@@ -183,8 +183,8 @@ breakpad_backend_callback(const google_breakpad::MinidumpDescriptor &descriptor,
             }
 #endif
 
-            sentry_envelope_t *envelope = sentry__prepare_event(
-                options, event, nullptr, !options->on_crash_func, nullptr);
+            sentry_envelope_t *envelope = sentry__prepare_event(options, event,
+                nullptr, !options->on_crash_func, nullptr, nullptr);
             if (envelope) {
                 event_id = sentry__envelope_get_event_id(envelope);
             }

src/backends/sentry_backend_crashpad.cpp

@@ -564,9 +564,8 @@ crashpad_handler(int signum, siginfo_t *info, ucontext_t *user_context)
             crash_event = options->on_crash_func(
                 &uctx, crash_event, options->on_crash_data);
         } else if (options->before_send_func) {
-            SENTRY_DEBUG("invoking `before_send` hook");
-            crash_event = options->before_send_func(
-                crash_event, nullptr, options->before_send_data);
+            crash_event
+                = sentry__invoke_before_send(options, crash_event, nullptr);
         }
 
         sentry__transport_suspend(options->transport);

src/backends/sentry_backend_inproc.c

@@ -1102,7 +1102,7 @@ process_ucontext_deferred(const sentry_ucontext_t *uctx,
 #endif
 
             sentry_envelope_t *envelope = sentry__prepare_event(options, event,
-                NULL, !options->on_crash_func && !skip_hooks, NULL);
+                NULL, !options->on_crash_func && !skip_hooks, NULL, NULL);
             if (envelope) {
                 event_id = sentry__envelope_get_event_id(envelope);
             }

src/backends/sentry_backend_native.c

@@ -1368,9 +1368,7 @@ native_backend_except(sentry_backend_t *backend, const sentry_ucontext_t *uctx)
         if (should_handle) {
             // Apply before_send hook if on_crash wasn't set
             if (!options->on_crash_func && options->before_send_func) {
-                SENTRY_DEBUG("invoking `before_send` hook");
-                event = options->before_send_func(
-                    event, NULL, options->before_send_data);
+                event = sentry__invoke_before_send(options, event, NULL);
                 should_handle = !sentry_value_is_null(event);
             }
 

src/sentry_app_hang_monitor.c

@@ -81,7 +81,7 @@ app_hang_capture(uint64_t hang_time_ms, uint64_t tid)
         return false;
     }
     sentry_value_t event = sentry__app_hang_make_event(ips, n, hang_time_ms);
-    sentry__capture_event(event, NULL);
+    sentry__capture_event(event, NULL, NULL);
     return true;
 }