Skip to content

Document System.IO.WindowsRuntimeStorageExtensions #2846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 5, 2019
Merged

Document System.IO.WindowsRuntimeStorageExtensions #2846

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5caa8d1
Document System.IO.WindowsRuntimeStorageExtensions
carlossanlop Jul 26, 2019
c819795
suggestions by JeremyKuhne
carlossanlop Jul 29, 2019
89de275
Fixed broken xref, fully qualified enum names
Jul 30, 2019
fcfa0a5
thing->benefit
carlossanlop Aug 2, 2019
161e9cc
remove 2 sentences
carlossanlop Aug 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 64 additions & 21 deletions xml/System.IO/WindowsRuntimeStorageExtensions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,28 @@ The next example shows the XAML code that is associated with the previous exampl
</remarks>
</Docs>
<Members>
<MemberGroup MemberName="CreateSafeFileHandle">
<AssemblyInfo>
<AssemblyName>System.Runtime.WindowsRuntime</AssemblyName>
<AssemblyVersion>4.0.14.0</AssemblyVersion>
</AssemblyInfo>
<Docs>
<summary>Creates and returns a reference to a safe file handle for the IStorage instance that is being extended.</summary>
<remarks>
<format type="text/markdown">
<![CDATA[

## Remarks

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.

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.

]]>
</format>
</remarks>
</Docs>
</MemberGroup>
<Member MemberName="CreateSafeFileHandle">
<MemberSignature Language="C#" Value="public static Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle (this Windows.Storage.IStorageFolder rootDirectory, string relativePath, System.IO.FileMode mode);" />
<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" />
Expand All @@ -78,12 +100,27 @@ The next example shows the XAML code that is associated with the previous exampl
<Parameter Name="mode" Type="System.IO.FileMode" Index="2" FrameworkAlternate="dotnet-plat-ext-3.0" />
</Parameters>
<Docs>
<param name="rootDirectory">To be added.</param>
<param name="relativePath">To be added.</param>
<param name="mode">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="rootDirectory">The current storage folder instance.</param>
<param name="relativePath">The name of the file that you want to get a handle to.</param>
<param name="mode">The mode in which the operating system should open the file.</param>
<summary>Creates a safe file handle for a file that is in the current storage folder instance.</summary>
<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>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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.

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.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="rootDirectory" /> is <see langword="null" />.

-or-

<paramref name="relativePath" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="CreateSafeFileHandle">
Expand Down Expand Up @@ -112,13 +149,14 @@ The next example shows the XAML code that is associated with the previous exampl
<Parameter Name="options" Type="System.IO.FileOptions" Index="3" FrameworkAlternate="dotnet-plat-ext-3.0" />
</Parameters>
<Docs>
<param name="windowsRuntimeFile">To be added.</param>
<param name="access">To be added.</param>
<param name="share">To be added.</param>
<param name="options">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="windowsRuntimeFile">A storage file instance.</param>
<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>
<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>
<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>
<summary>Creates a safe file handle for a the current storage file instance.</summary>
<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>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="windowsRuntimeFile" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="CreateSafeFileHandle">
Expand Down Expand Up @@ -149,15 +187,20 @@ The next example shows the XAML code that is associated with the previous exampl
<Parameter Name="options" Type="System.IO.FileOptions" Index="5" FrameworkAlternate="dotnet-plat-ext-3.0" />
</Parameters>
<Docs>
<param name="rootDirectory">To be added.</param>
<param name="relativePath">To be added.</param>
<param name="mode">To be added.</param>
<param name="access">To be added.</param>
<param name="share">To be added.</param>
<param name="options">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="rootDirectory">The current storage folder instance.</param>
<param name="relativePath">The name of the file that you want to get a handle to.</param>
<param name="mode">The mode in which the operating system should open the file.</param>
<param name="access">The kind of access that should be used when opening the file.</param>
<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>
<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>
<summary>Creates a safe file handle for a file that is in the current storage folder instance.</summary>
<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>
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="rootDirectory" /> is <see langword="null" />.

-or-

<paramref name="relativePath" /> is <see langword="null" />.</exception>
</Docs>
</Member>
<Member MemberName="OpenStreamForReadAsync">
Expand Down Expand Up @@ -384,4 +427,4 @@ The next example shows the XAML code that is associated with the previous exampl
</Docs>
</Member>
</Members>
</Type>
</Type>