Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

CreateFile (kernel32)
 
.
Summary

C# Signature:

  /// <summary>
  /// The CreateFile function creates or opens a file, file stream, directory, physical disk, volume, console buffer, tape drive,
  /// communications resource, mailslot, or named pipe. The function returns a handle that can be used to access an object.
  /// </summary>
  /// <param name="lpFileName"></param>
  /// <param name="dwDesiredAccess"> access to the object, which can be read, write, or both</param>
  /// <param name="dwShareMode">The sharing mode of an object, which can be read, write, both, or none</param>
  /// <param name="SecurityAttributes">A pointer to a SECURITY_ATTRIBUTES structure that determines whether or not the returned handle can
  /// be inherited by child processes. Can be null</param>
  /// <param name="dwCreationDisposition">An action to take on files that exist and do not exist</param>
  /// <param name="dwFlagsAndAttributes">The file attributes and flags. </param>
  /// <param name="hTemplateFile">A handle to a template file with the GENERIC_READ access right. The template file supplies file attributes
  /// and extended attributes for the file that is being created. This parameter can be null</param>
  /// <returns>If the function succeeds, the return value is an open handle to a specified file. If a specified file exists before the function
  /// all and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS, even when the function
  /// succeeds. If a file does not exist before the call, GetLastError returns 0 (zero).
  /// If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
  /// </returns>
[DllImport("kernel32.dll", CharSet = CharSet.Auto, CallingConvention = CallingConvention.StdCall, SetLastError = true)]
  public static extern SafeFileHandle CreateFile(
        string lpFileName,
        uint dwDesiredAccess,
        uint dwShareMode,
        IntPtr SecurityAttributes,
        uint dwCreationDisposition,
        uint dwFlagsAndAttributes,
        IntPtr hTemplateFile
        );

C# Signature:

[DllImport("kernel32.dll", SetLastError=true, CharSet=CharSet.Auto)]
public static extern IntPtr CreateFile(
   string lpFileName,
   EFileAccess dwDesiredAccess,
   EFileShare dwShareMode,
   IntPtr lpSecurityAttributes,
   ECreationDisposition dwCreationDisposition,
   EFileAttributes dwFlagsAndAttributes,
   IntPtr hTemplateFile);

C# Signature:

[DllImport("Kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
public static extern IntPtr CreateFile(
   string fileName,
   [MarshalAs(UnmanagedType.U4)] FileAccess fileAccess,
   [MarshalAs(UnmanagedType.U4)] FileShare fileShare,
   IntPtr securityAttributes,
   [MarshalAs(UnmanagedType.U4)] FileMode creationDisposition,
   int flags,
   IntPtr template);

VB.Net Signature:

    ''' <summary>
    ''' Creates or opens a file or I/O device. The most commonly used I/O devices are as follows: file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource,
    ''' mailslot, and pipe. The function returns a handle that can be used to access the file or device for various types of I/O depending on the file or device and the flags and attributes specified.
    ''' To perform this operation as a transacted operation, which results in a handle that can be used for transacted I/O, use the CreateFileTransacted function.
    ''' </summary>
    ''' <param name="lpFileName">The name of the file or device to be created or opened.
    ''' In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path.
    ''' For more information, see Naming a File.
    ''' For information on special device names, see Defining an MS-DOS Device Name.
    ''' To create a file stream, specify the name of the file, a colon, and then the name of the stream. For more information, see File Streams.</param>
    ''' <param name="dwDesiredAccess">The requested access to the file or device, which can be summarized as read, write, both or neither (zero).
    ''' The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both (GENERIC_READ | GENERIC_WRITE). For more information, see Generic Access Rights and File Security and Access Rights.
    ''' If this parameter is zero, the application can query certain metadata such as file, directory, or device attributes without accessing that file or device, even if GENERIC_READ access would have been
    ''' denied.
    ''' You cannot request an access mode that conflicts with the sharing mode that is specified by the dwShareMode parameter in an open request that already has an open handle.
    ''' For more information, see the Remarks section of this topic and Creating and Opening Files.</param>
    ''' <param name="dwShareMode">The requested sharing mode of the file or device, which can be read, write, both, delete, all of these, or none (refer to the following table). Access requests to attributes or
    ''' extended attributes are not affected by this flag.
    ''' If this parameter is zero and CreateFile succeeds, the file or device cannot be shared and cannot be opened again until the handle to the file or device is closed. For more information, see the Remarks
    ''' section.
    ''' You cannot request a sharing mode that conflicts with the access mode that is specified in an existing request that has an open handle. CreateFile would fail and the GetLastError function would return
    ''' ERROR_SHARING_VIOLATION.
    ''' To enable a process to share a file or device while another process has the file or device open, use a compatible combination of one or more of the following values. For more information about valid
    ''' combinations of this parameter with the dwDesiredAccess parameter, see Creating and Opening Files.
    ''' Note:  The sharing options for each open handle remain in effect until that handle is closed, regardless of process context.</param>
    ''' <param name="lpSecurityAttributes">A pointer to a SECURITY_ATTRIBUTES structure that contains two separate but related data members: an optional security descriptor, and a Boolean value that determines
    ''' whether the returned handle can be inherited by child processes.
    ''' This parameter can be NULL.
    ''' If this parameter is NULL, the handle returned by CreateFile cannot be inherited by any child processes the application may create and the file or device associated with the returned handle gets a
    ''' default security descriptor.
    ''' The lpSecurityDescriptor member of the structure specifies a SECURITY_DESCRIPTOR for a file or device. If this member is NULL, the file or device associated with the returned handle is assigned a default
    ''' security descriptor.
    ''' CreateFile ignores the lpSecurityDescriptor member when opening an existing file or device, but continues to use the bInheritHandle member.
    ''' The bInheritHandle member of the structure specifies whether the returned handle can be inherited.
    ''' For more information, see the Remarks section.</param>
    ''' <param name="dwCreationDisposition">An action to take on a file or device that exists or does not exist.
    ''' For devices other than files, this parameter is usually set to OPEN_EXISTING.
    ''' For more information, see the Remarks section.
    ''' This parameter must be one of the following values, which cannot be combined:</param>
    ''' <param name="dwFlagsAndAttributes">The file or device attributes and flags, FILE_ATTRIBUTE_NORMAL being the most common default value for files.
    ''' This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL.
    ''' This parameter can also contain combinations of flags (FILE_FLAG_*) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any FILE_ATTRIBUTE_*
    ''' values.
    ''' This parameter can also contain Security Quality of Service information by specifying the SECURITY_SQOS_PRESENT flag. Additional SQOS-related flags information is presented in the table following the
    ''' attributes and flags tables.
    ''' Note:  When CreateFile opens an existing file, it generally combines the file flags with the file attributes of the existing file, and ignores any file attributes supplied as part of
    ''' dwFlagsAndAttributes. Special cases are detailed in Creating and Opening Files.
    ''' Some of the following file attributes and flags may only apply to files and not necessarily all other types of devices that CreateFile can open. For additional information, see the Remarks section of
    ''' this topic and Creating and Opening Files.
    ''' For more advanced access to file attributes, see SetFileAttributes.</param>
    ''' <param name="hTemplateFile">A valid handle to a template file with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file that is being created.
    ''' This parameter can be NULL.
    ''' When opening an existing file, CreateFile ignores this parameter.
    ''' When opening a new encrypted file, the file inherits the discretionary access control list from its parent directory. For additional information, see File Encryption</param>
    ''' <returns>If the function succeeds, the return value is an open handle to the specified file, device, named pipe, or mail slot.
    ''' If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.</returns>
    ''' <remarks></remarks>
    <System.Runtime.InteropServices.DllImport("kernel32.dll", SetLastError:=True, CharSet:=System.Runtime.InteropServices.CharSet.Auto)> _
    Friend Function CreateFile(ByVal lpFileName As String, _
    ByVal dwDesiredAccess As EFileAccess, _
    ByVal dwShareMode As EFileShare, _
    ByVal lpSecurityAttributes As IntPtr, _
    ByVal dwCreationDisposition As ECreationDisposition, _
    ByVal dwFlagsAndAttributes As EFileAttributes, _
    ByVal hTemplateFile As IntPtr) As Microsoft.Win32.SafeHandles.SafeFileHandle
    End Function

User-Defined Types:

[Flags]
public enum EFileAccess : uint
{
   /// <summary>
   ///
   /// </summary>
   GenericRead = 0x80000000,
   /// <summary>
   ///
   /// </summary>
   GenericWrite = 0x40000000,
   /// <summary>
   ///
   /// </summary>
   GenericExecute = 0x20000000,
   /// <summary>
   ///
   /// </summary>
   GenericAll = 0x10000000
}

[Flags]
public enum EFileShare : uint
{
   /// <summary>
   ///
   /// </summary>
   None = 0x00000000,
   /// <summary>
   /// Enables subsequent open operations on an object to request read access.
   /// Otherwise, other processes cannot open the object if they request read access.
   /// If this flag is not specified, but the object has been opened for read access, the function fails.
   /// </summary>
   Read = 0x00000001,
   /// <summary>
   /// Enables subsequent open operations on an object to request write access.
   /// Otherwise, other processes cannot open the object if they request write access.
   /// If this flag is not specified, but the object has been opened for write access, the function fails.
   /// </summary>
   Write = 0x00000002,
   /// <summary>
   /// Enables subsequent open operations on an object to request delete access.
   /// Otherwise, other processes cannot open the object if they request delete access.
   /// If this flag is not specified, but the object has been opened for delete access, the function fails.
   /// </summary>
   Delete = 0x00000004
}

public enum ECreationDisposition : uint
{
   /// <summary>
   /// Creates a new file. The function fails if a specified file exists.
   /// </summary>
   New = 1,
   /// <summary>
   /// Creates a new file, always.
   /// If a file exists, the function overwrites the file, clears the existing attributes, combines the specified file attributes,
   /// and flags with FILE_ATTRIBUTE_ARCHIVE, but does not set the security descriptor that the SECURITY_ATTRIBUTES structure specifies.
   /// </summary>
   CreateAlways = 2,
   /// <summary>
   /// Opens a file. The function fails if the file does not exist.
   /// </summary>
   OpenExisting = 3,
   /// <summary>
   /// Opens a file, always.
   /// If a file does not exist, the function creates a file as if dwCreationDisposition is CREATE_NEW.
   /// </summary>
   OpenAlways = 4,
   /// <summary>
   /// Opens a file and truncates it so that its size is 0 (zero) bytes. The function fails if the file does not exist.
   /// The calling process must open the file with the GENERIC_WRITE access right.
   /// </summary>
   TruncateExisting = 5
}

[Flags]
public enum EFileAttributes : uint
{
   Readonly         = 0x00000001,
   Hidden           = 0x00000002,
   System           = 0x00000004,
   Directory        = 0x00000010,
   Archive          = 0x00000020,
   Device           = 0x00000040,
   Normal           = 0x00000080,
   Temporary        = 0x00000100,
   SparseFile       = 0x00000200,
   ReparsePoint     = 0x00000400,
   Compressed       = 0x00000800,
   Offline          = 0x00001000,
   NotContentIndexed= 0x00002000,
   Encrypted        = 0x00004000,
   Write_Through    = 0x80000000,
   Overlapped       = 0x40000000,
   NoBuffering      = 0x20000000,
   RandomAccess     = 0x10000000,
   SequentialScan   = 0x08000000,
   DeleteOnClose    = 0x04000000,
   BackupSemantics  = 0x02000000,
   PosixSemantics   = 0x01000000,
   OpenReparsePoint = 0x00200000,
   OpenNoRecall     = 0x00100000,
   FirstPipeInstance= 0x00080000
}

User-Defined Types (VB2008 style):

    Friend Structure STORAGE_DEVICE_NUMBER
    Friend DeviceType As Integer
    Friend DeviceNumber As Integer
    Friend PartitionNumber As Integer
    End Structure

    Friend Enum EFileAccess As System.Int32
    ''
    ''  The following are masks for the predefined standard access types
    ''

    DELETE = &H10000
    READ_CONTROL = &H20000
    WRITE_DAC = &H40000
    WRITE_OWNER = &H80000
    SYNCHRONIZE = &H100000

    STANDARD_RIGHTS_REQUIRED = &HF0000
    STANDARD_RIGHTS_READ = READ_CONTROL
    STANDARD_RIGHTS_WRITE = READ_CONTROL
    STANDARD_RIGHTS_EXECUTE = READ_CONTROL
    STANDARD_RIGHTS_ALL = &H1F0000
    SPECIFIC_RIGHTS_ALL = &HFFFF

    ''
    '' AccessSystemAcl access type
    ''

    ACCESS_SYSTEM_SECURITY = &H1000000

    ''
    '' MaximumAllowed access type
    ''

    MAXIMUM_ALLOWED = &H2000000

    ''
    ''  These are the generic rights.
    ''

    GENERIC_READ = &H80000000
    GENERIC_WRITE = &H40000000
    GENERIC_EXECUTE = &H20000000
    GENERIC_ALL = &H10000000
    End Enum

    Friend Enum EFileShare
    FILE_SHARE_NONE = &H0
    FILE_SHARE_READ = &H1
    FILE_SHARE_WRITE = &H2
    FILE_SHARE_DELETE = &H4
    End Enum

    Friend Enum ECreationDisposition
    ''' <summary>
    ''' Creates a new file, only if it does not already exist.
    ''' If the specified file exists, the function fails and the last-error code is set to ERROR_FILE_EXISTS (80).
    ''' If the specified file does not exist and is a valid path to a writable location, a new file is created.
    ''' </summary>
    CREATE_NEW = 1

    ''' <summary>
    ''' Creates a new file, always.
    ''' If the specified file exists and is writable, the function overwrites the file, the function succeeds, and last-error code is set to ERROR_ALREADY_EXISTS (183).
    ''' If the specified file does not exist and is a valid path, a new file is created, the function succeeds, and the last-error code is set to zero.
    ''' For more information, see the Remarks section of this topic.
    ''' </summary>
    CREATE_ALWAYS = 2

    ''' <summary>
    ''' Opens a file or device, only if it exists.
    ''' If the specified file or device does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2).
    ''' For more information about devices, see the Remarks section.
    ''' </summary>
    OPEN_EXISTING = 3

    ''' <summary>
    ''' Opens a file, always.
    ''' If the specified file exists, the function succeeds and the last-error code is set to ERROR_ALREADY_EXISTS (183).
    ''' If the specified file does not exist and is a valid path to a writable location, the function creates a file and the last-error code is set to zero.
    ''' </summary>
    OPEN_ALWAYS = 4

    ''' <summary>
    ''' Opens a file and truncates it so that its size is zero bytes, only if it exists.
    ''' If the specified file does not exist, the function fails and the last-error code is set to ERROR_FILE_NOT_FOUND (2).
    ''' The calling process must open the file with the GENERIC_WRITE bit set as part of the dwDesiredAccess parameter.
    ''' </summary>
    TRUNCATE_EXISTING = 5
    End Enum

    Friend Enum EFileAttributes
    FILE_ATTRIBUTE_READONLY = &H1
    FILE_ATTRIBUTE_HIDDEN = &H2
    FILE_ATTRIBUTE_SYSTEM = &H4
    FILE_ATTRIBUTE_DIRECTORY = &H10
    FILE_ATTRIBUTE_ARCHIVE = &H20
    FILE_ATTRIBUTE_DEVICE = &H40
    FILE_ATTRIBUTE_NORMAL = &H80
    FILE_ATTRIBUTE_TEMPORARY = &H100
    FILE_ATTRIBUTE_SPARSE_FILE = &H200
    FILE_ATTRIBUTE_REPARSE_POINT = &H400
    FILE_ATTRIBUTE_COMPRESSED = &H800
    FILE_ATTRIBUTE_OFFLINE = &H1000
    FILE_ATTRIBUTE_NOT_CONTENT_INDEXED = &H2000
    FILE_ATTRIBUTE_ENCRYPTED = &H4000
    FILE_ATTRIBUTE_VIRTUAL = &H10000
    End Enum

Instead of the enum "EFileAttributes" supplied on this page, you can also use "System.IO.FileAttributes". The enum values are identical up to "Encrypted".

This is NOT true for "EFileAccess" and "System.IO.FileAccess"!

Notes:

None.

Tips & Tricks:

You can use the IntPtr from Createfile with FileStream. This is usefull for opening devices such as Com1:, Lpt1: and Prn.

Unlike the FileStream ctor, CreateFile also allows you to open or create Windows 2000 sub-streams (e.g. "C:\Temp.dat:SubStream1").

For example:

IntPtr ptr = CreateFile(filename,access, share,0, mode,0, IntPtr.Zero);
/* Is bad handle? INVALID_HANDLE_VALUE */
if (ptr.ToInt32() == -1)
{
    /* ask the framework to marshall the win32 error code to an exception */
    Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());
}
else
{
    return new FileStream(ptr,access);
}

Microsoft .NET Framework 2.0 Changes

If you are using version 2.0 of the .NET framework, you will need to make a few changes because of obsolete methods in the release for OpenFile. You can no longer try the good old

    return new FileStream(hDrv, FileAccess.Read);

unless the hDrv is of the new SafeFileHandle type.

Simply replace the IntPtr's with SafeFileHandle - the updated signature is:

    [DllImport("Kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
    static extern SafeFileHandle CreateFile(
        string fileName,
        [MarshalAs(UnmanagedType.U4)] FileAccess fileAccess,
        [MarshalAs(UnmanagedType.U4)] FileShare fileShare,
        IntPtr securityAttributes,
        [MarshalAs(UnmanagedType.U4)] FileMode creationDisposition,
        [MarshalAs(UnmanagedType.U4)] FileAttributes flags,
        IntPtr template);

And call it like:

    SafeFileHandle handle = CreateFile(Path,GENERIC_WRITE,0,
        IntPtr.Zero,OPEN_EXISTING,0,IntPtr.Zero);
    if (handle.IsInvalid)
        Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());

And also make sure that you import Microsoft.Win32.SafeHandles. The other code as below in the Alternative Managed API will work the same.

Alternative Managed API:

Do you know one? Please contribute it!

Documentation
CreateFile on MSDN
Documentation
FileStream on MSDN
Documentation
Marshal on MSDN

You're doing this the hard way. Just define it like this:

    [DllImport("Kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
    static extern IntPtr CreateFile(
        string fileName,
        [MarshalAs(UnmanagedType.U4)] FileAccess fileAccess,
        [MarshalAs(UnmanagedType.U4)] FileShare fileShare,
        int securityAttributes,
        [MarshalAs(UnmanagedType.U4)] FileMode creationDisposition,
        int flags,
        IntPtr template);

Now you can use the normal .NET enums that people are familiar with

Thought I post a sample code to help out anyone else who may need help : )

/// Sample code provided as is.
/// Sample Composed by Wijaya "Wi" T
/// References:
/// http://www.dotnettalk.net/Needed_help_on_printing_from_C_and_printer-6941579-1297-a.html
/// http://www.dotnet247.com/247reference/msgs/16/84730.aspx
/// http://www.groupsrv.com/dotnet/viewtopic.php?t=72572
/// http://www.pinvoke.net/default.aspx/kernel32.CreateFile
///    Usage:  
///        Initialize this class in your main code (see below),
///        and walla you are now printing!
///        
///        e.g.:
///        PrintFactory objPrintFactory = new PrintFactory();
///    Thank you:
///        Thank you all who have been contributing to printing to LPT port.
///        God Bless you! : )
///    Addt'l info:
///        Don't forget to reference:
///            using System.Runtime.InteropServices;
///            using System.IO;
///            
public class PrintFactory
{
   public const short FILE_ATTRIBUTE_NORMAL = 0x80;
   public const short INVALID_HANDLE_VALUE = -1;
   public const uint GENERIC_READ = 0x80000000;
   public const uint GENERIC_WRITE = 0x40000000;
   public const uint CREATE_NEW = 1;
   public const uint CREATE_ALWAYS = 2;
   public const uint OPEN_EXISTING = 3;        

   [DllImport("kernel32.dll", SetLastError=true)]
   static extern IntPtr CreateFile(string lpFileName, uint dwDesiredAccess,
       uint dwShareMode, IntPtr lpSecurityAttributes, uint dwCreationDisposition,
       uint dwFlagsAndAttributes, IntPtr hTemplateFile);

   public PrintFactory()
   {
      IntPtr ptr = CreateFile("LPT1", GENERIC_WRITE, 0,
               IntPtr.Zero, OPEN_EXISTING, 0, IntPtr.Zero);

      /* Is bad handle? INVALID_HANDLE_VALUE */
      if (ptr.ToInt32() == -1)
      {
     /* ask the framework to marshall the win32 error code to an exception */
     Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());
      }
      else
      {                                    
     String Temp = "This is a test print";
     //This is the cut command on Star TSP 600 Printer
     char[] prnCmdCut = {(char)27, (char)100, (char)51};                
     FileStream lpt = new FileStream(ptr,FileAccess.ReadWrite);
     Byte[] Buff = new Byte[1024];
     //Check to see if your printer support ASCII encoding or Unicode.
     //If unicode is supported, use the following:
     //Buff = System.Text.Encoding.Unicode.GetBytes(Temp);
     Buff = System.Text.Encoding.ASCII.GetBytes(Temp);
     lpt.Write(Buff,0,Buff.Length);                     
     Buff = System.Text.Encoding.ASCII.GetBytes(prnCmdCut);
     lpt.Write(Buff,0,Buff.Length);
     lpt.Close();
       }
    }
}

***********

Where is the secutityAttributes?! It's not to uncommon to want a file handle to be inheritable (e.g. you want to pass a handle to a server component like something running as a "servicedComponent" or a service...) and by using the securityAttributes this can be done...

***********

Note that on win98, mapping the parameters to FileAccess and FileShare will cause CreateFileA to fail. I found this out the hard way, banging my head against a very slow win98 machine across an even slow connection. Instead use the EFileAccess, and EFileShare enumeration constants that match the windows constants ( as mentioned earlier in the article ).

***********

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions