Skip to content

Commit 0d8c72c

Browse files
AaronRobinsonMSFTAaronRobinsonMSFT
authored
Marshal and SafeBuffer doc updates (#3941)
* Docs for Marshal class. - PtrToStringUTF8 - StringToCoTaskMemUTF8 - ZeroFreeCoTaskMemUTF8 * Docs for SafeBuffer class. - IsInvalid * Review feedback.
1 parent 18345c6 commit 0d8c72c

File tree

2 files changed

+64
-19
lines changed

2 files changed

+64
-19
lines changed

‎xml/System.Runtime.InteropServices/Marshal.xml

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6585,10 +6585,18 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
65856585
<Parameter Name="ptr" Type="System.IntPtr" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
65866586
</Parameters>
65876587
<Docs>
6588-
<param name="ptr">To be added.</param>
6589-
<summary>To be added.</summary>
6590-
<returns>To be added.</returns>
6591-
<remarks>To be added.</remarks>
6588+
<param name="ptr">The address of the first character of the unmanaged string.</param>
6589+
<summary>Allocates a managed <see cref="T:System.String" /> and copies all characters up to the first null character from an unmanaged UTF-8 string into it.</summary>
6590+
<returns>A managed string that holds a copy of the unmanaged string if the value of the <paramref name="ptr" /> parameter is not <see langword="null" />; otherwise, this method returns <see langword="null" />.</returns>
6591+
<remarks>
6592+
<format type="text/markdown"><![CDATA[
6593+
6594+
## Remarks
6595+
<xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A> is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A?displayProperty=nameWithType> methods.
6596+
]]></format>
6597+
6598+
</remarks>
6599+
<altmember cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" />
65926600
</Docs>
65936601
</Member>
65946602
<Member MemberName="PtrToStringUTF8">
@@ -6626,11 +6634,19 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
66266634
<Parameter Name="byteLen" Type="System.Int32" Index="1" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
66276635
</Parameters>
66286636
<Docs>
6629-
<param name="ptr">To be added.</param>
6630-
<param name="byteLen">To be added.</param>
6631-
<summary>To be added.</summary>
6632-
<returns>To be added.</returns>
6633-
<remarks>To be added.</remarks>
6637+
<param name="ptr">The address of the first character of the unmanaged string.</param>
6638+
<param name="byteLen">The number of bytes to copy.</param>
6639+
<summary>Allocates a managed <see cref="T:System.String" /> and copies a specified number of bytes from an unmanaged UTF8 string into it.</summary>
6640+
<returns>A managed string that holds a copy of the unmanaged string if the value of the <paramref name="ptr" /> parameter is not <see langword="null" />; otherwise, this method returns <see langword="null" />.</returns>
6641+
<remarks>
6642+
<format type="text/markdown"><![CDATA[
6643+
6644+
## Remarks
6645+
<xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A> is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A?displayProperty=nameWithType> methods.
6646+
6647+
]]></format>
6648+
</remarks>
6649+
<altmember cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" />
66346650
</Docs>
66356651
</Member>
66366652
<MemberGroup MemberName="PtrToStructure">
@@ -9477,10 +9493,22 @@ There is a difference in the behavior of the `GetLastWin32Error` method on .NET
94779493
<Parameter Name="s" Type="System.String" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
94789494
</Parameters>
94799495
<Docs>
9480-
<param name="s">To be added.</param>
9481-
<summary>To be added.</summary>
9482-
<returns>To be added.</returns>
9483-
<remarks>To be added.</remarks>
9496+
<param name="s">A managed string to be copied.</param>
9497+
<summary>Copies the contents of a managed <see cref="T:System.String" /> to a block of memory allocated from the unmanaged COM task allocator.</summary>
9498+
<returns>An integer representing a pointer to the block of memory allocated for the string, or 0 if <paramref name="s" /> is <see langword="null" />.</returns>
9499+
<remarks>
9500+
<format type="text/markdown"><![CDATA[
9501+
9502+
## Remarks
9503+
<xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A> is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string including a null terminator, always free the memory by calling <xref:System.Runtime.InteropServices.Marshal.FreeCoTaskMem%2A?displayProperty=nameWithType>. This method provides the opposite functionality of <xref:System.Runtime.InteropServices.Marshal.PtrToStringUTF8%2A?displayProperty=nameWithType>. The characters of the string are copied as UTF-8 characters.
9504+
9505+
]]></format>
9506+
</remarks>
9507+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="s" /> parameter exceeds the maximum length allowed by the operating system.</exception>
9508+
<exception cref="T:System.OutOfMemoryException">There is insufficient memory available.</exception>
9509+
<altmember cref="M:System.Runtime.InteropServices.Marshal.FreeCoTaskMem(System.IntPtr)" />
9510+
<altmember cref="M:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemUTF8(System.IntPtr)" />
9511+
<altmember cref="M:System.Runtime.InteropServices.Marshal.PtrToStringUTF8(System.IntPtr,System.Int32)" />
94849512
</Docs>
94859513
</Member>
94869514
<Member MemberName="StringToHGlobalAnsi">
@@ -11871,9 +11899,16 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo)
1187111899
<Parameter Name="s" Type="System.IntPtr" Index="0" FrameworkAlternate="netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1;netcore-3.1" />
1187211900
</Parameters>
1187311901
<Docs>
11874-
<param name="s">To be added.</param>
11875-
<summary>To be added.</summary>
11876-
<remarks>To be added.</remarks>
11902+
<param name="s">The address of the unmanaged string to free.</param>
11903+
<summary>Frees an unmanaged string pointer that was allocated using the <see cref="M:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8(System.String)" /> method.</summary>
11904+
<remarks>
11905+
<format type="text/markdown"><![CDATA[
11906+
11907+
## Remarks
11908+
The <xref:System.Runtime.InteropServices.Marshal.ZeroFreeCoTaskMemUTF8%2A> method first zeros out and then frees unmanaged memory that was allocated using the <xref:System.Runtime.InteropServices.Marshal.StringToCoTaskMemUTF8%2A> method.
11909+
11910+
]]></format>
11911+
</remarks>
1187711912
</Docs>
1187811913
</Member>
1187911914
<Member MemberName="ZeroFreeGlobalAllocAnsi">

‎xml/System.Runtime.InteropServices/SafeBuffer.xml

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -447,9 +447,19 @@ finally {
447447
<ReturnType>System.Boolean</ReturnType>
448448
</ReturnValue>
449449
<Docs>
450-
<summary>To be added.</summary>
451-
<value>To be added.</value>
452-
<remarks>To be added.</remarks>
450+
<summary>Gets a value that indicates whether the handle is invalid.</summary>
451+
<value>
452+
<see langword="true" /> if the handle is not valid; otherwise, <see langword="false" />.</value>
453+
<remarks>
454+
<format type="text/markdown"><![CDATA[
455+
456+
## Remarks
457+
The common language runtime uses this property to determine whether critical finalization is required.
458+
459+
]]></format>
460+
</remarks>
461+
<altmember cref="P:Microsoft.Win32.SafeHandles.SafeHandleMinusOneIsInvalid.IsInvalid" />
462+
<altmember cref="T:Microsoft.Win32.SafeHandles.SafeHandleMinusOneIsInvalid" />
453463
</Docs>
454464
</Member>
455465
<Member MemberName="Read&lt;T&gt;">

0 commit comments

Comments
 (0)