File.OpenHandle Method

Definition

Namespace:

System.IO

Assembly:

System.Runtime.dll

Source:

File.cs

Initializes a new instance of the SafeFileHandle class with the specified path, creation mode, read/write and sharing permission, the access other SafeFileHandles can have to the same file, additional file options and the allocation size.

public static Microsoft.Win32.SafeHandles.SafeFileHandle OpenHandle (string path, System.IO.FileMode mode = System.IO.FileMode.Open, System.IO.FileAccess access = System.IO.FileAccess.Read, System.IO.FileShare share = System.IO.FileShare.Read, System.IO.FileOptions options = System.IO.FileOptions.None, long preallocationSize = 0);

static member OpenHandle : string * System.IO.FileMode * System.IO.FileAccess * System.IO.FileShare * System.IO.FileOptions * int64 -> Microsoft.Win32.SafeHandles.SafeFileHandle

Public Shared Function OpenHandle (path As String, Optional mode As FileMode = System.IO.FileMode.Open, Optional access As FileAccess = System.IO.FileAccess.Read, Optional share As FileShare = System.IO.FileShare.Read, Optional options As FileOptions = System.IO.FileOptions.None, Optional preallocationSize As Long = 0) As SafeFileHandle

Parameters

path

String

A relative or absolute path for the file that the current SafeFileHandle instance will encapsulate.

mode

FileMode

One of the enumeration values that determines how to open or create the file. The default value is Open

access

FileAccess

A bitwise combination of the enumeration values that determines how the file can be accessed. The default value is Read

share

FileShare

A bitwise combination of the enumeration values that determines how the file will be shared by processes. The default value is Read.

options

FileOptions

An object that describes optional SafeFileHandle parameters to use.

preallocationSize

Int64

The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created, overwritten, or replaced. Negative values are not allowed. In other cases (including the default 0 value), it's ignored.

Returns

SafeFileHandle

A SafeFileHandle instance.

Exceptions

ArgumentNullException

path is null.

ArgumentException

path is an empty string (""), contains only white space, or contains one or more invalid characters. -or- path refers to a non-file device, such as CON:, COM1:, LPT1:, etc. in an NTFS environment.

NotSupportedException

path refers to a non-file device, such as CON:, COM1:, LPT1:, etc. in a non-NTFS environment.

ArgumentOutOfRangeException

preallocationSize is negative. -or- mode, access, or share contain an invalid value.

FileNotFoundException

The file cannot be found, such as when mode is Truncate or Open, and the file specified by path does not exist. The file must already exist in these modes.

IOException

An I/O error, such as specifying CreateNew when the file specified by path already exists, occurred. -or- The disk was full (when preallocationSize was provided and path was pointing to a regular file). -or- The file was too large (when preallocationSize was provided and path was pointing to a regular file).

SecurityException

The caller does not have the required permission.

DirectoryNotFoundException

The specified path is invalid, such as being on an unmapped drive.

UnauthorizedAccessException

The access requested is not permitted by the operating system for the specified path, such as when access is Write or ReadWrite and the file or directory is set for read-only access. -or- Encrypted is specified for options, but file encryption is not supported on the current platform.

PathTooLongException

The specified path, file name, or both exceed the system-defined maximum length.