Skip to content

Commit 4e590ee

Browse files
Fix a doc details about loading Native DLLs
- Note that `NativeLibrary.Load()` etc. must return the actual OS handle - Note that `AssemblyLoadContext.LoadUnmanagedDllFromPath()` also returns the OS handle (also fix its exceptions).
1 parent 21c1f6d commit 4e590ee

File tree

2 files changed

+17
-10
lines changed

2 files changed

+17
-10
lines changed

xml/System.Runtime.InteropServices/NativeLibrary.xml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
</Parameters>
3939
<Docs>
4040
<param name="handle">The native library handle to be freed.</param>
41-
<summary>Frees a given a loaded library handle, or takes no action if the input handle is <see cref="F:System.IntPtr.Zero" />.</summary>
41+
<summary>Frees a loaded library given its OS handle, or takes no action if the input handle is <see cref="F:System.IntPtr.Zero" />.</summary>
4242
<remarks>To be added.</remarks>
4343
</Docs>
4444
</Member>
@@ -62,7 +62,7 @@
6262
<Parameter Name="name" Type="System.String" />
6363
</Parameters>
6464
<Docs>
65-
<param name="handle">The native library handle.</param>
65+
<param name="handle">The native library OS handle.</param>
6666
<param name="name">The name of the exported symbol.</param>
6767
<summary>Gets the address of an exported symbol.</summary>
6868
<returns>The address of the symbol.</returns>
@@ -99,7 +99,7 @@ This is a simple wrapper around OS calls and does not perform any name mangling.
9999
<Docs>
100100
<param name="libraryPath">The name of the native library to be loaded.</param>
101101
<summary>Provides a simple API for loading a native library that wraps the OS loader and uses default flags.</summary>
102-
<returns>The handle for the loaded native library.</returns>
102+
<returns>The OS handle for the loaded native library.</returns>
103103
<remarks>To be added.</remarks>
104104
<exception cref="T:System.ArgumentNullException">
105105
<paramref name="libraryPath" /> is <see langword="null" />.</exception>
@@ -131,7 +131,7 @@ This is a simple wrapper around OS calls and does not perform any name mangling.
131131
<param name="assembly">The assembly loading the native library.</param>
132132
<param name="searchPath">The search path.</param>
133133
<summary>Provides a high-level API for loading a native library.</summary>
134-
<returns>The handle for the loaded library.</returns>
134+
<returns>The OS handle for the loaded library.</returns>
135135
<remarks>
136136
<format type="text/markdown"><![CDATA[
137137
@@ -208,7 +208,7 @@ Only one resolver can be registered per assembly. Trying to register a second re
208208
<Parameter Name="address" Type="System.IntPtr" RefType="out" />
209209
</Parameters>
210210
<Docs>
211-
<param name="handle">The native library handle.</param>
211+
<param name="handle">The native library OS handle.</param>
212212
<param name="name">The name of the exported symbol.</param>
213213
<param name="address">When the method returns, contains the symbol address, if it exists.</param>
214214
<summary>Gets the address of an exported symbol and returns a value that indicates whether the method call succeeded.</summary>
@@ -240,7 +240,7 @@ Only one resolver can be registered per assembly. Trying to register a second re
240240
</Parameters>
241241
<Docs>
242242
<param name="libraryPath">The name of the native library to be loaded.</param>
243-
<param name="handle">When the method returns, the handle of the loaded native library.</param>
243+
<param name="handle">When the method returns, the OS handle of the loaded native library.</param>
244244
<summary>Provides a simple API for loading a native library and returns a value that indicates whether the operation succeeded.</summary>
245245
<returns>
246246
<see langword="true" /> if the native library was loaded successful; otherwise, <see langword="false" />.</returns>
@@ -273,7 +273,7 @@ Only one resolver can be registered per assembly. Trying to register a second re
273273
<param name="libraryName">The name of the native library to be loaded.</param>
274274
<param name="assembly">The assembly loading the native library.</param>
275275
<param name="searchPath">The search path.</param>
276-
<param name="handle">When the method returns, the handle of the loaded native library.</param>
276+
<param name="handle">When the method returns, the OS handle of the loaded native library.</param>
277277
<summary>Provides a high-level API that loads a native library and returns a value that indicates whether the operation succeeded.</summary>
278278
<returns>
279279
<see langword="true" /> if the load operation was successful; otherwise, <see langword="false" />.</returns>

xml/System.Runtime.Loader/AssemblyLoadContext.xml

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -774,12 +774,19 @@ Each <xref:System.Runtime.Loader.AssemblyLoadContext> can load only:
774774
<Docs>
775775
<param name="unmanagedDllPath">The path to the unmanaged library.</param>
776776
<summary>Loads an unmanaged library from the specified path.</summary>
777-
<returns>A handle to the loaded library.</returns>
778-
<remarks>To be added.</remarks>
777+
<returns>The OS handle for the loaded native library.</returns>
778+
<remarks>
779+
<format type="text/markdown"><![CDATA[
780+
781+
The OS handle returned by this method can be used with methods of <xref:System.Runtime.InteropServices.NativeLibrary?displayProperty=nameWithType> class.
782+
783+
]]></format>
784+
</remarks>
779785
<exception cref="T:System.ArgumentNullException">
780786
<paramref name="unmanagedDllPath" /> is <see langword="null" />.</exception>
781787
<exception cref="T:System.ArgumentException">The <paramref name="unmanagedDllPath" /> argument is not an absolute path.</exception>
782-
<exception cref="T:System.IO.FileNotFoundException">The unmanaged library cannot be found.</exception>
788+
<exception cref="T:System.DllNotFoundException">The library can't be found.</exception>
789+
<exception cref="T:System.BadImageFormatException">The library is not valid.</exception>
783790
</Docs>
784791
</Member>
785792
<Member MemberName="Name">

0 commit comments

Comments
 (0)