Alternate implementation, deprecate the confusing API

contrib/platform/src/com/sun/jna/platform/win32/WTypes.java

@@ -24,15 +24,14 @@
  */
 package com.sun.jna.platform.win32;
 
-import java.io.UnsupportedEncodingException;
-
 import com.sun.jna.Memory;
 import com.sun.jna.Native;
 import com.sun.jna.Pointer;
 import com.sun.jna.PointerType;
 import com.sun.jna.Structure;
 import com.sun.jna.platform.win32.WinDef.USHORT;
 import com.sun.jna.ptr.ByReference;
+import java.io.UnsupportedEncodingException;
 
 /**
  * Constant defined in WTypes.h
@@ -151,42 +150,86 @@ public String toString() {
     }
 
     public class BSTRByReference extends ByReference {
-
-        private BSTR bstr = null;
-
         public BSTRByReference() {
             super(Native.POINTER_SIZE);
         }
 
+        /**
+         * Create a reference to a {@link BSTR} specified by its pointer. The user is
+         * responsible for allocating and releasing memory for the {@link BSTR}.
+         *
+         * @param p
+         *            A pointer to BSTR to be referenced obtained using
+         *            {@link BSTR#getPointer()}.
+         */
+        public BSTRByReference(Pointer p) {
+            this();
+            setValue(p);
+        }
+
+        /**
+         * Set a reference to a {@link BSTR} specified by its pointer. This method does
+         * not maintain a reference to the object passed as an argument. New
+         * applications should instantiate using the value from
+         * {@link BSTR#getPointer()} instead.
+         *
+         * @param value
+         *            The BSTR to be referenced. Only the pointer is stored as a
+         *            reference.
+         * @deprecated Use {@link BSTRByReference(Pointer)}
+         */
+        @Deprecated
         public BSTRByReference(BSTR value) {
             this();
-            setValue(value);
-        }
-
+            setValue(value.getPointer());
+        }
+
+        /**
+         * Store a reference to the specified {@link BSTR}. This method does not
+         * maintain a reference to the object passed as an argument. New applications
+         * should use {@link #setValue(Pointer)} to set the value from
+         * {@link BSTR#getPointer()} instead.
+         *
+         * @param value
+         *            The BSTR to be referenced. Only the pointer is stored as a
+         *            reference.
+         * @deprecated Use {@link BSTRByReference(Pointer)}
+         */
+        @Deprecated
+        public void setValue(Pointer p) {
+            this.getPointer().setPointer(0, p);
+        }
+
+        /**
+         * Set a reference to a {@link BSTR} specified by its pointer. The user is
+         * responsible for allocating and releasing memory for the {@link BSTR}.
+         *
+         * @param p
+         *            A pointer to BSTR to be referenced obtained using
+         *            {@link BSTR#getPointer()}.
+         * @deprecated Use {@link #setValue(Pointer)}
+         */
+        @Deprecated
         public void setValue(BSTR value) {
-            // Save a local reference to prevent losing value's memory
-            this.bstr = value;
             this.getPointer().setPointer(0, value.getPointer());
         }
 
+        /**
+         * @deprecated Use {@link #getBSTR()}
+         */
+        @Deprecated
         public BSTR getValue() {
-            // If memory address hasn't changed, return the stored BSTR
-            if (bstr != null) {
-                if (getPointer().getPointer(0).equals(bstr.getPointer())) {
-                    return bstr;
-                }
-                // The stored memory has been changed, memory is tracked elsewhere.
-                // Clean up unneeded reference.
-                bstr = null;
-            }
-            // Null check the pointer
-            Pointer p = getPointer().getPointer(0);
-            return p != null ? new BSTR(p) : null;
+            return new BSTR(getPointer().getPointer(0));
+        }
+
+        public BSTR getBSTR() {
+            Pointer p = getPointer();
+            return p == null ? null : new BSTR(p.getPointer(0));
         }
 
         public String getString() {
-            BSTR b = this.getValue();
-            return b != null ? b.getValue() : null;
+            BSTR b = this.getBSTR();
+            return b == null ? null : b.getValue();
         }
     }
 

contrib/platform/test/com/sun/jna/platform/ByReferencePlatformToStringTest.java

@@ -84,7 +84,8 @@ public void testPlatformToStrings() {
         BOOLByReference boolbr = new BOOLByReference(new BOOL(true));
         parseAndTest(boolbr.toString(), "BOOL", "true");
 
-        BSTRByReference bstrbr = new BSTRByReference(new BSTR("bstr"));
+        BSTR b = new BSTR("bstr");
+        BSTRByReference bstrbr = new BSTRByReference(b.getPointer());
         parseAndTest(bstrbr.toString(), "BSTR", "bstr");
 
         CHARByReference cbr = new CHARByReference(new CHAR(42));