From 5caa8d1a88ddde8aaf75f02ee4ce18ee969630ae Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Fri, 26 Jul 2019 16:32:39 -0700 Subject: [PATCH 1/5] Document System.IO.WindowsRuntimeStorageExtensions --- .../WindowsRuntimeStorageExtensions.xml | 83 ++++++++++++++----- 1 file changed, 63 insertions(+), 20 deletions(-) diff --git a/xml/System.IO/WindowsRuntimeStorageExtensions.xml b/xml/System.IO/WindowsRuntimeStorageExtensions.xml index f5cdf0c6436..4a66876b94f 100644 --- a/xml/System.IO/WindowsRuntimeStorageExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStorageExtensions.xml @@ -52,6 +52,28 @@ The next example shows the XAML code that is associated with the previous exampl + + + System.Runtime.WindowsRuntime + 4.0.14.0 + + + Creates and returns a safe file handle for the IStorage instance that is being extended. + + + and 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. + +Getting the Win32 handle allows richer interoperability with both .NET and other existing libraries. You can, for example, go straight to a without complicated and potentially performance-sapping wrappers. + + ]]> + + + + @@ -78,12 +100,27 @@ The next example shows the XAML code that is associated with the previous exampl - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The current storage folder instance. + The name of the file that you want to get a handle to. + The mode in which the operating system should open the file. + Creates a safe file handle for a file that is in the current storage folder instance. + A safe file handle instance if the operation succeeds; if the conversion of the to an IStorageFolderHandleAccess returns . + + , the file will be opened with access permission. For any other modes, the file will be opened with access permission. + +Additionally, this method will open the file with stream sharing access and with advanced file creation options. + + ]]> + + is . + + -or- + + is . @@ -112,13 +149,14 @@ The next example shows the XAML code that is associated with the previous exampl - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + A storage file instance. + The kind of access that should be used when opening the file. The default value is . + The kind of stream sharing access other objects can have to the same file. The default value is . + Advanced options for creating the object. The default value is . + Creates a safe file handle for a the current storage file instance. + A safe file handle instance if the operation succeeds; if the conversion of the to an IStorageItemHandleAccess returns . To be added. + is . @@ -149,15 +187,20 @@ The next example shows the XAML code that is associated with the previous exampl - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The current storage folder instance. + The name of the file that you want to get a handle to. + The mode in which the operating system should open the file. + The kind of access that should be used when opening the file. + The kind of stream sharing access other objects can have to the same file. The default value is . + Advanced options for creating the object. The default value is . + Creates a safe file handle for a file that is in the current storage folder instance. + A safe file handle instance if the operation succeeds; if the conversion of the to an IStorageFolderHandleAccess returns . To be added. + is . + + -or- + + is . From c819795a640f0f0daff78b1fd8e84ecd16ca4adc Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Mon, 29 Jul 2019 09:32:16 -0700 Subject: [PATCH 2/5] suggestions by JeremyKuhne --- xml/System.IO/WindowsRuntimeStorageExtensions.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/xml/System.IO/WindowsRuntimeStorageExtensions.xml b/xml/System.IO/WindowsRuntimeStorageExtensions.xml index 4a66876b94f..b39724047cd 100644 --- a/xml/System.IO/WindowsRuntimeStorageExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStorageExtensions.xml @@ -58,16 +58,17 @@ The next example shows the XAML code that is associated with the previous exampl 4.0.14.0 - Creates and returns a safe file handle for the IStorage instance that is being extended. + Creates and returns a reference to a safe file handle for the IStorage instance that is being extended. and 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. +With the Windows 10 Anniversary Update, new interfaces were added to and 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. Getting the Win32 handle allows richer interoperability with both .NET and other existing libraries. You can, for example, go straight to a without complicated and potentially performance-sapping wrappers. +The key thing here is that you can get a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. ]]> @@ -427,4 +428,4 @@ The next example shows the XAML code that is associated with the previous exampl - \ No newline at end of file + From 89de275d7cbd18e75d473dbb90bed21ec1488264 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Tue, 30 Jul 2019 09:27:42 -0700 Subject: [PATCH 3/5] Fixed broken xref, fully qualified enum names --- xml/System.IO/WindowsRuntimeStorageExtensions.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.IO/WindowsRuntimeStorageExtensions.xml b/xml/System.IO/WindowsRuntimeStorageExtensions.xml index b39724047cd..1a7a852e06a 100644 --- a/xml/System.IO/WindowsRuntimeStorageExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStorageExtensions.xml @@ -68,7 +68,7 @@ The next example shows the XAML code that is associated with the previous exampl With the Windows 10 Anniversary Update, new interfaces were added to and 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. Getting the Win32 handle allows richer interoperability with both .NET and other existing libraries. You can, for example, go straight to a without complicated and potentially performance-sapping wrappers. -The key thing here is that you can get a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. +The key thing here is that you can get a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. ]]> @@ -111,9 +111,9 @@ The key thing here is that you can get a brokered `SafeFileHandle`. This is crit ## Remarks -When calling this method, if the specified mode is , the file will be opened with access permission. For any other modes, the file will be opened with access permission. +When calling this method, if the specified mode is , the file will be opened with access permission. For any other modes, the file will be opened with access permission. -Additionally, this method will open the file with stream sharing access and with advanced file creation options. +Additionally, this method will open the file with stream sharing access and with advanced file creation options. ]]> From fcfa0a5a1e637886beded273f81af9386d35b57d Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 1 Aug 2019 19:22:27 -0700 Subject: [PATCH 4/5] thing->benefit --- xml/System.IO/WindowsRuntimeStorageExtensions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.IO/WindowsRuntimeStorageExtensions.xml b/xml/System.IO/WindowsRuntimeStorageExtensions.xml index 1a7a852e06a..7acd21f6980 100644 --- a/xml/System.IO/WindowsRuntimeStorageExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStorageExtensions.xml @@ -68,7 +68,7 @@ The next example shows the XAML code that is associated with the previous exampl With the Windows 10 Anniversary Update, new interfaces were added to and 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. Getting the Win32 handle allows richer interoperability with both .NET and other existing libraries. You can, for example, go straight to a without complicated and potentially performance-sapping wrappers. -The key thing here is that you can get a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. +The key benefit of the API is access to a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. ]]> From 161e9cc3f04cbd9029108b7c2551c879a123700c Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 1 Aug 2019 19:25:11 -0700 Subject: [PATCH 5/5] remove 2 sentences --- xml/System.IO/WindowsRuntimeStorageExtensions.xml | 1 - 1 file changed, 1 deletion(-) diff --git a/xml/System.IO/WindowsRuntimeStorageExtensions.xml b/xml/System.IO/WindowsRuntimeStorageExtensions.xml index 7acd21f6980..0e3aca8be59 100644 --- a/xml/System.IO/WindowsRuntimeStorageExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStorageExtensions.xml @@ -67,7 +67,6 @@ The next example shows the XAML code that is associated with the previous exampl With the Windows 10 Anniversary Update, new interfaces were added to and 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. -Getting the Win32 handle allows richer interoperability with both .NET and other existing libraries. You can, for example, go straight to a without complicated and potentially performance-sapping wrappers. The key benefit of the API is access to a brokered `SafeFileHandle`. This is critically important if you want to create a around an or 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 . Using a path will often throw in these cases. ]]>