This is an automated email from the ASF dual-hosted git repository. GitToTheHub pushed a commit to branch pr-doc-deprecation-of-associatedObject in repository https://gitbox.apache.org/repos/asf/cordova-ios.git
commit 25ebd9eca868ebcf72f794ee8a3bd0554a3fdda6 Author: Manuel Beck <[email protected]> AuthorDate: Fri Jul 31 22:44:22 2026 +0200 chore(doc): document deprecation of `CDVPluginResult.associatedObject` with samples - Document in plugin's upgrade guide `CordovaLib/CordovaLib.docc/upgrading-8.md` - Document on `CordovaLib/include/Cordova/CDVPluginResult.h` --- CordovaLib/CordovaLib.docc/upgrading-8.md | 37 ++++++++++++++++++++++++++++ CordovaLib/include/Cordova/CDVPluginResult.h | 21 ++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/CordovaLib/CordovaLib.docc/upgrading-8.md b/CordovaLib/CordovaLib.docc/upgrading-8.md index c628f7ff..e84aa335 100644 --- a/CordovaLib/CordovaLib.docc/upgrading-8.md +++ b/CordovaLib/CordovaLib.docc/upgrading-8.md @@ -187,6 +187,43 @@ result?.setKeepCallbackAs(true) self.commandDelegate.send(result, callbackId: callback) ``` +### Deprecating `CDVPluginResult.associatedObject` + +The `associatedObject` property on ``CDVPluginResult`` is now deprecated. + +Historically, this was commonly used as a lifetime-retention helper for legacy + Objective-C patterns such as constructing a string with + `initWithBytesNoCopy:...`, where the created `NSString` could depend on an + external `NSData` buffer remaining alive. + +In modern plugin code, prefer APIs that do not rely on external buffer + lifetimes. + +```objc +// Old code +NSString* payload = [[NSString alloc] initWithBytesNoCopy:(void*)[data bytes] + length:[data length] + encoding:NSUTF8StringEncoding + freeWhenDone:NO]; +CDVPluginResult* result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK + messageAsString:payload]; +result.associatedObject = data; +``` + +```objc +// New code +NSString* payload = [[NSString alloc] initWithData:data + encoding:NSUTF8StringEncoding]; +CDVPluginResult* result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK + messageAsString:payload]; +``` + +For binary payloads, prefer message constructors that accept `NSData` directly, + such as `resultWithStatus:messageAsArrayBuffer:`. + +If you must retain auxiliary state, keep it in your plugin instance until after + sending the result, rather than attaching it to `CDVPluginResult`. + ## Other Major Changes ### Deprecating AppDelegate category extensions diff --git a/CordovaLib/include/Cordova/CDVPluginResult.h b/CordovaLib/include/Cordova/CDVPluginResult.h index b0b55844..abf8c09b 100644 --- a/CordovaLib/include/Cordova/CDVPluginResult.h +++ b/CordovaLib/include/Cordova/CDVPluginResult.h @@ -131,6 +131,27 @@ NS_ASSUME_NONNULL_BEGIN } */ @property (nonatomic, strong) NSNumber *keepCallback; +/** + Deprecated helper previously used to retain an auxiliary object for the lifetime + of this plugin result. + + A common legacy usage was retaining an `NSData` object when constructing a + `NSString` with `initWithBytesNoCopy:...`, where the string depended on the + original byte buffer remaining valid. + + Prefer APIs that do not require external lifetime management (for example, + `[[NSString alloc] initWithData:encoding:]` or a message constructor that + accepts `NSData` directly, such as + ``resultWithStatus:messageAsArrayBuffer:``). + + If you still need to retain additional state, hold it in your plugin instance + until after `sendPluginResult:callbackId:` returns rather than attaching it to + ``CDVPluginResult``. + + @Metadata { + @Available(Cordova, introduced: "4.5.0", deprecated: "8.0.0") + } + */ @property (nonatomic, strong) id associatedObject CDV_DEPRECATED(8.0.0, ""); - (instancetype)init; --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
