From 9855882b819d50f87d7052c4f17129665dcf3169 Mon Sep 17 00:00:00 2001
From: Daniel Widdis <widdis@gmail.com>
Date: Thu, 28 Jan 2021 21:23:34 -0800
Subject: [PATCH] Also deprecate BSTR string constructors

---
 .../src/com/sun/jna/platform/win32/WTypes.java | 18 ++++++++++++++++++
 .../ByReferencePlatformToStringTest.java       | 11 ++++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java b/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java
index 888c6558a..67b795705 100644
--- a/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java
+++ b/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java
@@ -103,15 +103,33 @@ public BSTR() {
             super(Pointer.NULL);
         }
 
+        /**
+         * Instantiate a BSTR from a pointer. The user is responsible for allocating and
+         * releasing memory for the {@link BSTR}, most commonly using
+         * {@link OleAuto#SysAllocString(String)} and
+         * {@link OleAuto#SysFreeString(BSTR)}
+         *
+         * @param pointer
+         *            A pointer to the string
+         */
         public BSTR(Pointer pointer) {
             super(pointer);
         }
 
+        /**
+         * @deprecated Use {@link OleAuto#SysAllocString(String)} and
+         *             {@link OleAuto#SysFreeString(BSTR)}
+         */
+        @Deprecated
         public BSTR(String value) {
             super();
             this.setValue(value);
         }
 
+        /**
+         * @deprecated Users should not change the value of an allocated {@link BSTR}.
+         */
+        @Deprecated
         public void setValue(String value) {
             if(value == null) {
                 value = "";
diff --git a/contrib/platform/test/com/sun/jna/platform/ByReferencePlatformToStringTest.java b/contrib/platform/test/com/sun/jna/platform/ByReferencePlatformToStringTest.java
index f55a834b7..4a2a2f990 100644
--- a/contrib/platform/test/com/sun/jna/platform/ByReferencePlatformToStringTest.java
+++ b/contrib/platform/test/com/sun/jna/platform/ByReferencePlatformToStringTest.java
@@ -28,9 +28,11 @@
 
 import org.junit.Test;
 
+import com.sun.jna.Platform;
 import com.sun.jna.Pointer;
 import com.sun.jna.platform.unix.X11.AtomByReference;
 import com.sun.jna.platform.unix.X11.WindowByReference;
+import com.sun.jna.platform.win32.OleAuto;
 import com.sun.jna.platform.win32.BaseTSD.ULONG_PTR;
 import com.sun.jna.platform.win32.BaseTSD.ULONG_PTRByReference;
 import com.sun.jna.platform.win32.HighLevelMonitorConfigurationAPI.MC_COLOR_TEMPERATURE;
@@ -84,9 +86,12 @@ public void testPlatformToStrings() {
         BOOLByReference boolbr = new BOOLByReference(new BOOL(true));
         parseAndTest(boolbr.toString(), "BOOL", "true");
 
-        BSTR b = new BSTR("bstr");
-        BSTRByReference bstrbr = new BSTRByReference(b.getPointer());
-        parseAndTest(bstrbr.toString(), "BSTR", "bstr");
+        if (Platform.isWindows()) {
+            BSTR b = OleAuto.INSTANCE.SysAllocString("bstr");
+            BSTRByReference bstrbr = new BSTRByReference(b.getPointer());
+            parseAndTest(bstrbr.toString(), "BSTR", "bstr");
+            OleAuto.INSTANCE.SysFreeString(b);
+        }
 
         CHARByReference cbr = new CHARByReference(new CHAR(42));
         parseAndTest(cbr.toString(), "CHAR", "42");