WindowsRuntimeStorageExtensions.CreateSafeFileHandle Method

Definition

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 SafeFileHandle

Parameters

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

SafeFileHandle

A safe file handle instance if the operation succeeds; null if the conversion of the rootDirectory to an IStorageFolderHandleAccess returns null.

Attributes

Exceptions

rootDirectory is null.

-or-

relativePath is null.

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

Product Introduced

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 SafeFileHandle

Parameters

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

SafeFileHandle

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

Product Introduced

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 SafeFileHandle

Parameters

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

SafeFileHandle

A safe file handle instance if the operation succeeds; null if the conversion of the rootDirectory to an IStorageFolderHandleAccess returns null.

Attributes

Exceptions

rootDirectory is null.

-or-

relativePath is null.

Applies to

Product Introduced