WindowsRuntimeStorageExtensions.CreateSafeFileHandle Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Creates and returns a reference to a safe file handle for the IStorage instance that is being extended.
Overloads
| CreateSafeFileHandle(IStorageFolder, String, FileMode) |
Creates a safe file handle for a file that is in the current storage folder instance. |
| CreateSafeFileHandle(IStorageFile, FileAccess, FileShare, FileOptions) |
Creates a safe file handle for a the current storage file instance. |
| CreateSafeFileHandle(IStorageFolder, String, FileMode, FileAccess, FileShare, FileOptions) |
Creates a safe file handle for a file that is in the current storage folder instance. |
Remarks
With the Windows 10 Anniversary Update, new interfaces were added to IStorageFolder and 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 FileStream around an IStorageItem or IStorageFolder when you are running in an AppContainer. 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 FileStream. Using a path will often throw AccessViolationException in these cases.
CreateSafeFileHandle(IStorageFolder, String, FileMode)
Important
This API is not CLS-compliant.
Creates a safe file handle for a file that is in the current storage folder instance.
public:
[System::Runtime::CompilerServices::Extension]
static Microsoft::Win32::SafeHandles::SafeFileHandle ^ CreateSafeFileHandle(Windows::Storage::IStorageFolder ^ rootDirectory, System::String ^ relativePath, System::IO::FileMode mode);[System.CLSCompliant(false)]
public static Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle (this Windows.Storage.IStorageFolder rootDirectory, string relativePath, System.IO.FileMode mode);[<System.CLSCompliant(false)>]
static member CreateSafeFileHandle : Windows.Storage.IStorageFolder * string * System.IO.FileMode -> Microsoft.Win32.SafeHandles.SafeFileHandle<Extension()>
Public Function CreateSafeFileHandle (rootDirectory As IStorageFolder, relativePath As String, mode As FileMode) As SafeFileHandleParameters
- rootDirectory
- IStorageFolder
The current storage folder instance.
- relativePath
- String
The name of the file that you want to get a handle to.
- mode
- FileMode
The mode in which the operating system should open the file.
Returns
A safe file handle instance if the operation succeeds; null if the conversion of the rootDirectory to an IStorageFolderHandleAccess returns null.
- Attributes
Exceptions
Remarks
When calling this method, if the specified mode is FileMode.Append, the file will be opened with FileAccess.Read access permission. For any other modes, the file will be opened with FileAccess.ReadWrite access permission.
Additionally, this method will open the file with FileShare.Read stream sharing access and with FileOptions.None advanced file creation options.
Applies to
CreateSafeFileHandle(IStorageFile, FileAccess, FileShare, FileOptions)
Important
This API is not CLS-compliant.
Creates a safe file handle for a the current storage file instance.
[System.CLSCompliant(false)]
public static Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle (this Windows.Storage.IStorageFile windowsRuntimeFile, System.IO.FileAccess access = System.IO.FileAccess.ReadWrite, System.IO.FileShare share = System.IO.FileShare.Read, System.IO.FileOptions options = System.IO.FileOptions.None);[<System.CLSCompliant(false)>]
static member CreateSafeFileHandle : Windows.Storage.IStorageFile * System.IO.FileAccess * System.IO.FileShare * System.IO.FileOptions -> Microsoft.Win32.SafeHandles.SafeFileHandle<Extension()>
Public Function CreateSafeFileHandle (windowsRuntimeFile As IStorageFile, Optional access As FileAccess = System.IO.FileAccess.ReadWrite, Optional share As FileShare = System.IO.FileShare.Read, Optional options As FileOptions = System.IO.FileOptions.None) As SafeFileHandleParameters
- windowsRuntimeFile
- IStorageFile
A storage file instance.
- access
- FileAccess
The kind of access that should be used when opening the file. The default value is ReadWrite.
- share
- FileShare
The kind of stream sharing access other FileStream objects can have to the same file. The default value is Read.
- options
- FileOptions
Advanced options for creating the FileStream object. The default value is None.
Returns
A safe file handle instance if the operation succeeds; null if the conversion of the windowsRuntimeFile to an IStorageItemHandleAccess returns null.
- Attributes
Exceptions
windowsRuntimeFile is null.
Applies to
CreateSafeFileHandle(IStorageFolder, String, FileMode, FileAccess, FileShare, FileOptions)
Important
This API is not CLS-compliant.
Creates a safe file handle for a file that is in the current storage folder instance.
[System.CLSCompliant(false)]
public static Microsoft.Win32.SafeHandles.SafeFileHandle CreateSafeFileHandle (this Windows.Storage.IStorageFolder rootDirectory, string relativePath, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share = System.IO.FileShare.Read, System.IO.FileOptions options = System.IO.FileOptions.None);[<System.CLSCompliant(false)>]
static member CreateSafeFileHandle : Windows.Storage.IStorageFolder * string * System.IO.FileMode * System.IO.FileAccess * System.IO.FileShare * System.IO.FileOptions -> Microsoft.Win32.SafeHandles.SafeFileHandle<Extension()>
Public Function CreateSafeFileHandle (rootDirectory As IStorageFolder, relativePath As String, mode As FileMode, access As FileAccess, Optional share As FileShare = System.IO.FileShare.Read, Optional options As FileOptions = System.IO.FileOptions.None) As SafeFileHandleParameters
- rootDirectory
- IStorageFolder
The current storage folder instance.
- relativePath
- String
The name of the file that you want to get a handle to.
- mode
- FileMode
The mode in which the operating system should open the file.
- access
- FileAccess
The kind of access that should be used when opening the file.
- share
- FileShare
The kind of stream sharing access other FileStream objects can have to the same file. The default value is Read.
- options
- FileOptions
Advanced options for creating the FileStream object. The default value is None.
Returns
A safe file handle instance if the operation succeeds; null if the conversion of the rootDirectory to an IStorageFolderHandleAccess returns null.
- Attributes
Exceptions
Applies to
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for