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 67b795705b..a893e8bb83 100644 --- a/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java +++ b/contrib/platform/src/com/sun/jna/platform/win32/WTypes.java @@ -24,6 +24,8 @@ */ 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; @@ -31,7 +33,6 @@ 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(); } }