Revert BSTRByReference, add javadoc and null check

java-native-access · Jan 29, 2021 · 036f917 · 036f917
1 parent 9855882
commit 036f917
Showing 1 changed file with 23 additions and 48 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
@@ -24,14 +24,15 @@
  */
 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
@@ -173,80 +174,54 @@ public BSTRByReference() {
         }
 
         /**
-         * 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.
+         * Store a reference to the specified {@link BSTR}. This method does not
+         * maintain a reference to the object passed as an argument. The user is
+         * responsible for allocating and freeing the memory associated with this
+         * {@link BSTR}.
          *
          * @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.getPointer());
+            setValue(value);
         }
 
         /**
          * 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.
+         * maintain a reference to the object passed as an argument. The user is
+         * responsible for allocating and freeing the memory associated with this
+         * {@link BSTR}.
          *
          * @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) {
             this.getPointer().setPointer(0, value.getPointer());
         }
 
         /**
-         * @deprecated Use {@link #getBSTR()}
+         * Returns a copy of the {@link BSTR} referenced by this object. The memory
+         * associated with the {@link BSTR} may be referenced by other objects/threads
+         * which may also free the underlying native memory.
+         *
+         * @return A new {@link BSTR} object corresponding to the memory referenced by
+         *         this object.
          */
-        @Deprecated
         public BSTR getValue() {
             return new BSTR(getPointer().getPointer(0));
         }
 
-        public BSTR getBSTR() {
-            Pointer p = getPointer();
-            return p == null ? null : new BSTR(p.getPointer(0));
-        }
-
+        /**
+         * Returns the String represented by the referenced {@link BSTR}.
+         *
+         * @return the referenced String, if the reference is not {@code null},
+         *         {@code null} otherwise.
+         */
         public String getString() {
-            BSTR b = this.getBSTR();
+            BSTR b = this.getValue();
             return b == null ? null : b.getValue();
         }
     }