Skip to content

Commit 30c78db

Browse files
carlossanlopmairaw
carlossanlop
authored and
mairaw
committed
Document System.IO.WindowsRuntimeStorageExtensions (#2846)
* Document System.IO.WindowsRuntimeStorageExtensions * suggestions by JeremyKuhne * Fixed broken xref, fully qualified enum names * thing->benefit * remove 2 sentences
1 parent b562787 commit 30c78db

File tree

1 file changed

+64
-21
lines changed

1 file changed

+64
-21
lines changed

‎xml/System.IO/WindowsRuntimeStorageExtensions.xml

Lines changed: 64 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,28 @@ The next example shows the XAML code that is associated with the previous exampl
5252
</remarks>
5353
</Docs>
5454
<Members>
55+
<MemberGroup MemberName="CreateSafeFileHandle">
56+
<AssemblyInfo>
57+
<AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
58+
<AssemblyVersion>4.0.14.0</AssemblyVersion>
59+
</AssemblyInfo>
60+
<Docs>
61+
<summary>Creates and returns a reference to a safe file handle for the IStorage instance that is being extended.</summary>
62+
<remarks>
63+
<format type="text/markdown">
64+
<![CDATA[
65+
66+
## Remarks
67+
68+
With the Windows 10 Anniversary Update, new interfaces were added to <xref:Windows.Storage.IStorageFolder> and <xref:Windows.Storage.IStorageFile> that allow creating a standard Win32 file handle: `IStorageFolderHandleAccess` and `IStorageItemHandleAccess`. The `CreateSafeFileHandle` group of extension methods take advantage of the `Create` methods of these interfaces.
69+
70+
The key benefit of the API is access to a brokered `SafeFileHandle`. This is critically important if you want to create a <xref:System.IO.FileStream> around an <xref:Windows.Storage.IStorageItem> or <xref:Windows.Storage.IStorageFolder> when you are running in an [AppContainer](https://docs.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation). When running in an AppContainer, the application has very limited file access rights. Things like picture and document folders require the native file handle to be proxied via `RuntimeBroker.exe`, as the application process itself doesn't have rights to most files. This API gets the proxied handle. If accessing user data folders or using a file picker, this API should always be used to create <xref:System.IO.FileStream>. Using a path will often throw <xref:System.AccessViolationException> in these cases.
71+
72+
]]>
73+
</format>
74+
</remarks>
75+
</Docs>
76+
</MemberGroup>
5577
<Member MemberName="CreateSafeFileHandle">
5678
<MemberSignature Language="C#" Value="public static Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle (this Windows.Storage.IStorageFolder rootDirectory, string relativePath, System.IO.FileMode mode);" />
5779
<MemberSignature Language="ILAsm" Value=".method public static hidebysig class Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle(class Windows.Storage.IStorageFolder rootDirectory, string relativePath, valuetype System.IO.FileMode mode) cil managed" />
@@ -78,12 +100,27 @@ The next example shows the XAML code that is associated with the previous exampl
78100
<Parameter Name="mode" Type="System.IO.FileMode" Index="2" FrameworkAlternate="dotnet-plat-ext-3.0" />
79101
</Parameters>
80102
<Docs>
81-
<param name="rootDirectory">To be added.</param>
82-
<param name="relativePath">To be added.</param>
83-
<param name="mode">To be added.</param>
84-
<summary>To be added.</summary>
85-
<returns>To be added.</returns>
86-
<remarks>To be added.</remarks>
103+
<param name="rootDirectory">The current storage folder instance.</param>
104+
<param name="relativePath">The name of the file that you want to get a handle to.</param>
105+
<param name="mode">The mode in which the operating system should open the file.</param>
106+
<summary>Creates a safe file handle for a file that is in the current storage folder instance.</summary>
107+
<returns>A safe file handle instance if the operation succeeds; <see langword="null" /> if the conversion of the <paramref name="rootDirectory" /> to an IStorageFolderHandleAccess returns <see langword="null" />.</returns>
108+
<remarks>
109+
<format type="text/markdown"><![CDATA[
110+
111+
## Remarks
112+
113+
When calling this method, if the specified mode is <xref:System.IO.FileMode.Append?displayProperty=nameWithType>, the file will be opened with <xref:System.IO.FileAccess.Read?displayProperty=nameWithType> access permission. For any other modes, the file will be opened with <xref:System.IO.FileAccess.ReadWrite?displayProperty=nameWithType> access permission.
114+
115+
Additionally, this method will open the file with <xref:System.IO.FileShare.Read?displayProperty=nameWithType> stream sharing access and with <xref:System.IO.FileOptions.None?displayProperty=nameWithType> advanced file creation options.
116+
117+
]]></format>
118+
</remarks>
119+
<exception cref="T:System.ArgumentNullException"><paramref name="rootDirectory" /> is <see langword="null" />.
120+
121+
-or-
122+
123+
<paramref name="relativePath" /> is <see langword="null" />.</exception>
87124
</Docs>
88125
</Member>
89126
<Member MemberName="CreateSafeFileHandle">
@@ -112,13 +149,14 @@ The next example shows the XAML code that is associated with the previous exampl
112149
<Parameter Name="options" Type="System.IO.FileOptions" Index="3" FrameworkAlternate="dotnet-plat-ext-3.0" />
113150
</Parameters>
114151
<Docs>
115-
<param name="windowsRuntimeFile">To be added.</param>
116-
<param name="access">To be added.</param>
117-
<param name="share">To be added.</param>
118-
<param name="options">To be added.</param>
119-
<summary>To be added.</summary>
120-
<returns>To be added.</returns>
152+
<param name="windowsRuntimeFile">A storage file instance.</param>
153+
<param name="access">The kind of access that should be used when opening the file. The default value is <see cref="F:System.IO.FileAccess.ReadWrite" />.</param>
154+
<param name="share">The kind of stream sharing access other <see cref="T:System.IO.FileStream" /> objects can have to the same file. The default value is <see cref="F:System.IO.FileShare.Read" />.</param>
155+
<param name="options">Advanced options for creating the <see cref="T:System.IO.FileStream" /> object. The default value is <see cref="F:System.IO.FileOptions.None" />.</param>
156+
<summary>Creates a safe file handle for a the current storage file instance.</summary>
157+
<returns>A safe file handle instance if the operation succeeds; <see langword="null" /> if the conversion of the <paramref name="windowsRuntimeFile" /> to an IStorageItemHandleAccess returns <see langword="null" />.</returns>
121158
<remarks>To be added.</remarks>
159+
<exception cref="T:System.ArgumentNullException"><paramref name="windowsRuntimeFile" /> is <see langword="null" />.</exception>
122160
</Docs>
123161
</Member>
124162
<Member MemberName="CreateSafeFileHandle">
@@ -149,15 +187,20 @@ The next example shows the XAML code that is associated with the previous exampl
149187
<Parameter Name="options" Type="System.IO.FileOptions" Index="5" FrameworkAlternate="dotnet-plat-ext-3.0" />
150188
</Parameters>
151189
<Docs>
152-
<param name="rootDirectory">To be added.</param>
153-
<param name="relativePath">To be added.</param>
154-
<param name="mode">To be added.</param>
155-
<param name="access">To be added.</param>
156-
<param name="share">To be added.</param>
157-
<param name="options">To be added.</param>
158-
<summary>To be added.</summary>
159-
<returns>To be added.</returns>
190+
<param name="rootDirectory">The current storage folder instance.</param>
191+
<param name="relativePath">The name of the file that you want to get a handle to.</param>
192+
<param name="mode">The mode in which the operating system should open the file.</param>
193+
<param name="access">The kind of access that should be used when opening the file.</param>
194+
<param name="share">The kind of stream sharing access other <see cref="T:System.IO.FileStream" /> objects can have to the same file. The default value is <see cref="F:System.IO.FileShare.Read" />.</param>
195+
<param name="options">Advanced options for creating the <see cref="T:System.IO.FileStream" /> object. The default value is <see cref="F:System.IO.FileOptions.None" />.</param>
196+
<summary>Creates a safe file handle for a file that is in the current storage folder instance.</summary>
197+
<returns>A safe file handle instance if the operation succeeds; <see langword="null" /> if the conversion of the <paramref name="rootDirectory" /> to an IStorageFolderHandleAccess returns <see langword="null" />.</returns>
160198
<remarks>To be added.</remarks>
199+
<exception cref="T:System.ArgumentNullException"><paramref name="rootDirectory" /> is <see langword="null" />.
200+
201+
-or-
202+
203+
<paramref name="relativePath" /> is <see langword="null" />.</exception>
161204
</Docs>
162205
</Member>
163206
<Member MemberName="OpenStreamForReadAsync">
@@ -384,4 +427,4 @@ The next example shows the XAML code that is associated with the previous exampl
384427
</Docs>
385428
</Member>
386429
</Members>
387-
</Type>
430+
</Type>

0 commit comments

Comments
 (0)