This is an automated email from the ASF dual-hosted git repository.
GitToTheHub pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-ios.git
The following commit(s) were added to refs/heads/master by this push:
new 30d53bec chore(doc): document deprecation of
`CDVPluginResult.associatedObject` with samples (#1682)
30d53bec is described below
commit 30d53bec6c436be4d192463bea83482c3bc7e693
Author: Manuel Beck <[email protected]>
AuthorDate: Mon Aug 24 17:45:20 2026 +0200
chore(doc): document deprecation of `CDVPluginResult.associatedObject` with
samples (#1682)
- Document in plugin's upgrade guide
`CordovaLib/CordovaLib.docc/upgrading-8.md`
- Document on `CordovaLib/include/Cordova/CDVPluginResult.h`
Generated-By: GPT-5.3-Codex
---
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 e260da58..470f3b93 100644
--- a/CordovaLib/CordovaLib.docc/upgrading-8.md
+++ b/CordovaLib/CordovaLib.docc/upgrading-8.md
@@ -190,6 +190,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]
