Skip to content

Commit 5f17ca6

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
coreclr: Automatic port of triple slash from System.Runtime.InteropServices (dotnet#2712)
* coreclr: Automatic port of triple slash from System.Runtime.InteropServices * Update DllImportResolver.xml * Update NativeLibrary.xml
1 parent 87c6687 commit 5f17ca6

File tree

2 files changed

+78
-39
lines changed

2 files changed

+78
-39
lines changed

‎xml/System.Runtime.InteropServices/DllImportResolver.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
<param name="libraryName">To be added.</param>
2525
<param name="assembly">To be added.</param>
2626
<param name="searchPath">To be added.</param>
27-
<summary>To be added.</summary>
27+
<summary>Provides a delegate used to resolve native libraries via callback.</summary>
2828
<returns>To be added.</returns>
2929
<remarks>To be added.</remarks>
3030
</Docs>
31-
</Type>
31+
</Type>

‎xml/System.Runtime.InteropServices/NativeLibrary.xml‎

Lines changed: 76 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
17+
<summary>Provides APIs for managing native libraries.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -37,8 +37,8 @@
3737
<Parameter Name="handle" Type="System.IntPtr" />
3838
</Parameters>
3939
<Docs>
40-
<param name="handle">To be added.</param>
41-
<summary>To be added.</summary>
40+
<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>
4242
<remarks>To be added.</remarks>
4343
</Docs>
4444
</Member>
@@ -62,11 +62,19 @@
6262
<Parameter Name="name" Type="System.String" />
6363
</Parameters>
6464
<Docs>
65-
<param name="handle">To be added.</param>
66-
<param name="name">To be added.</param>
67-
<summary>To be added.</summary>
68-
<returns>To be added.</returns>
69-
<remarks>To be added.</remarks>
65+
<param name="handle">The native library handle.</param>
66+
<param name="name">The name of the exported symbol.</param>
67+
<summary>Gets the address of an exported symbol.</summary>
68+
<returns>The address of the symbol.</returns>
69+
<remarks>
70+
<format type="text/markdown"><![CDATA[
71+
72+
This is a simple wrapper around OS calls and does not perform any name mangling.
73+
74+
]]></format>
75+
</remarks>
76+
<exception cref="T:System.ArgumentNullException"><paramref name="handle" /> or <paramref name="name" /> is <see langword="null" />.</exception>
77+
<exception cref="T:System.EntryPointNotFoundException">The symbol is not found.</exception>
7078
</Docs>
7179
</Member>
7280
<Member MemberName="Load">
@@ -88,10 +96,13 @@
8896
<Parameter Name="libraryPath" Type="System.String" />
8997
</Parameters>
9098
<Docs>
91-
<param name="libraryPath">To be added.</param>
92-
<summary>To be added.</summary>
93-
<returns>To be added.</returns>
99+
<param name="libraryPath">The name of the native library to be loaded.</param>
100+
<summary>Provides a simple API for loading a native library that wraps the OS loader and uses default flags.</summary>
101+
<returns>The handle for the loaded native library.</returns>
94102
<remarks>To be added.</remarks>
103+
<exception cref="T:System.ArgumentNullException"><paramref name="libraryPath" /> is <see langword="null" />.</exception>
104+
<exception cref="T:System.DllNotFoundException">The library can't be found.</exception>
105+
<exception cref="T:System.BadImageFormatException">The library is not valid.</exception>
95106
</Docs>
96107
</Member>
97108
<Member MemberName="Load">
@@ -114,12 +125,26 @@
114125
<Parameter Name="searchPath" Type="System.Nullable&lt;System.Runtime.InteropServices.DllImportSearchPath&gt;" />
115126
</Parameters>
116127
<Docs>
117-
<param name="libraryName">To be added.</param>
118-
<param name="assembly">To be added.</param>
119-
<param name="searchPath">To be added.</param>
120-
<summary>To be added.</summary>
121-
<returns>To be added.</returns>
122-
<remarks>To be added.</remarks>
128+
<param name="libraryName">The name of the native library to be loaded.</param>
129+
<param name="assembly">The assembly loading the native library.</param>
130+
<param name="searchPath">The search path.</param>
131+
<summary>Provides a high-level API for loading a native library.</summary>
132+
<returns>The handle for the loaded library.</returns>
133+
<remarks>
134+
<format type="text/markdown"><![CDATA[
135+
136+
Given a library name, this method searches specific paths based on the runtime configuration, input parameters, and attributes of the calling assembly. If the `searchPath` parameter is non-null, the flags in this enumeration are used. Otherwise, the flags specified by the <xref:System.Runtime.InteropServices.DefaultDllImportSearchPathsAttribute> on the calling assembly, if any are present, are used. This method does not invoke the following managed callbacks for native library resolution:
137+
138+
- The per-assembly registered callback.
139+
- <xref:System.Runtime.Loader.AssemblyLoadContext.LoadUnmanagedDll%2A?displayProperty=nameWithType>.
140+
- <xref:System.Runtime.Loader.AssemblyLoadContext.ResolvingUnmanagedDllEvent?displayProperty=nameWithType>.
141+
142+
]]></format>
143+
</remarks>
144+
<exception cref="T:System.ArgumentNullException"><paramref name="libraryName" /> or <paramref name="assembly" /> is <see langword="null" />.</exception>
145+
<exception cref="T:System.ArgumentException"><paramref name="assembly" /> is not a <see langword="RuntimeAssembly" />.</exception>
146+
<exception cref="T:System.DllNotFoundException">The library can't be found.</exception>
147+
<exception cref="T:System.BadImageFormatException">The library is not valid.</exception>
123148
</Docs>
124149
</Member>
125150
<Member MemberName="SetDllImportResolver">
@@ -141,10 +166,20 @@
141166
<Parameter Name="resolver" Type="System.Runtime.InteropServices.DllImportResolver" />
142167
</Parameters>
143168
<Docs>
144-
<param name="assembly">To be added.</param>
145-
<param name="resolver">To be added.</param>
146-
<summary>To be added.</summary>
147-
<remarks>To be added.</remarks>
169+
<param name="assembly">The assembly for which the resolver is registered.</param>
170+
<param name="resolver">The resolver callback to register.</param>
171+
<summary>Sets a callback for resolving native library imports from an assembly.</summary>
172+
<remarks>
173+
<format type="text/markdown"><![CDATA[
174+
175+
This per-assembly resolver is the first attempt to resolve native library loads initiated by this assembly.
176+
177+
Only one resolver can be registered per assembly. Trying to register a second resolver fails with an <xref:System.InvalidOperationException>.
178+
179+
]]></format>
180+
</remarks>
181+
<exception cref="T:System.ArgumentNullException"><paramref name="assembly" /> or paramref name="resolver" /> is <see langword="null" />.</exception>
182+
<exception cref="T:System.ArgumentException">A resolver is already set for this assembly.</exception>
148183
</Docs>
149184
</Member>
150185
<Member MemberName="TryGetExport">
@@ -168,12 +203,13 @@
168203
<Parameter Name="address" Type="System.IntPtr" RefType="out" />
169204
</Parameters>
170205
<Docs>
171-
<param name="handle">To be added.</param>
172-
<param name="name">To be added.</param>
173-
<param name="address">To be added.</param>
174-
<summary>To be added.</summary>
175-
<returns>To be added.</returns>
206+
<param name="handle">The native library handle.</param>
207+
<param name="name">The name of the exported symbol.</param>
208+
<param name="address">When the method returns, contains the symbol address, if it exists.</param>
209+
<summary>Gets the address of an exported symbol and returns a value that indicates whether the method call succeeded.</summary>
210+
<returns><see langword="true" /> if the method returned successfully; otherwise, <see langword="false" />.</returns>
176211
<remarks>To be added.</remarks>
212+
<exception cref="T:System.ArgumentNullException"><paramref name="handle" /> or <paramref name="name" /> is <see langword="null" />.</exception>
177213
</Docs>
178214
</Member>
179215
<Member MemberName="TryLoad">
@@ -196,11 +232,12 @@
196232
<Parameter Name="handle" Type="System.IntPtr" RefType="out" />
197233
</Parameters>
198234
<Docs>
199-
<param name="libraryPath">To be added.</param>
200-
<param name="handle">To be added.</param>
201-
<summary>To be added.</summary>
202-
<returns>To be added.</returns>
235+
<param name="libraryPath">The name of the native library to be loaded.</param>
236+
<param name="handle">When the method returns, the handle of the loaded native library.</param>
237+
<summary>Provides a simple API for loading a native library and returns a value that indicates whether the operation succeeded.</summary>
238+
<returns><see langword="true" /> if the native library was loaded successful; otherwise, <see langword="false" />.</returns>
203239
<remarks>To be added.</remarks>
240+
<exception cref="T:System.ArgumentNullException"><paramref name="libraryPath" /> is <see langword="null" />.</exception>
204241
</Docs>
205242
</Member>
206243
<Member MemberName="TryLoad">
@@ -224,14 +261,16 @@
224261
<Parameter Name="handle" Type="System.IntPtr" RefType="out" />
225262
</Parameters>
226263
<Docs>
227-
<param name="libraryName">To be added.</param>
228-
<param name="assembly">To be added.</param>
229-
<param name="searchPath">To be added.</param>
230-
<param name="handle">To be added.</param>
231-
<summary>To be added.</summary>
232-
<returns>To be added.</returns>
264+
<param name="libraryName">The name of the native library to be loaded.</param>
265+
<param name="assembly">The assembly loading the native library.</param>
266+
<param name="searchPath">The search path.</param>
267+
<param name="handle">When the method returns, the handle of the loaded native library.</param>
268+
<summary>Provides a high-level API that loads a native library and returns a value that indicates whether the operation succeeded.</summary>
269+
<returns><see langword="true" /> if the load operation was successful; otherwise, <see langword="false" />.</returns>
233270
<remarks>To be added.</remarks>
271+
<exception cref="T:System.ArgumentNullException"><paramref name="libraryPath" /> or <paramref name="assembly" /> is <see langword="null" />.</exception>
272+
<exception cref="T:System.ArgumentException"><paramref name="assembly" /> is not a <see langword="RuntimeAssembly" />.</exception>
234273
</Docs>
235274
</Member>
236275
</Members>
237-
</Type>
276+
</Type>

0 commit comments

Comments
 (0)