CREATEFILE()

this function is used to create or open files, directories, physical disks, or other I/O devices.

HANDLE CreateFile(
    LPCSTR lpFileName,                           // File name
    DWORD dwDesiredAccess,                       // Access mode (read, write, etc.)
    DWORD dwShareMode,                           // Share mode
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,  // Security attributes
    DWORD dwCreate,                              // Action to take on file creation
    DWORD dwFlagsAndAttributes,                  // File attributes and flags
    HANDLE hTemplateFile                         // Template file handle
);

 * this returns a "HANDLE" to an open file object, or "INVALID_HANDLE_VALUE" in case of
   failure 
 * dw describes DWORD which is a 32bit unsigned integer
 * lpsz means a long pointer to a zero-terminated string (AKA lp)
 * lpctstr is a data type (think of this as a string data type)

OPTIONS

 * lpFileName is the name of the file or device to be created or opened.
    - it is a pointer to the null-terminated string that names the file, pipe, etc

 * dwDesiredAccess specifies the access mode; the values can be combined with a
   bitwise "OR" operator (|) to open a file for read AND write access
    - GENERIC_READ | GENERIC_WRITE
    
    - OPTIONS:
       - GENERIC_READ
       - GENERIC_WRITE
 

 * dwShareMode specifies the sharing mode; can use bitwise O to combine options
    - FILE_SHARE_READ | FILE_SHARE_WRITE
    
    - OPTIONS
       - 0                //file can't be shared; also, not even this process can open
                          //a second HANDLE on the specified file
                          
       - FILE_SHARE_READ  //other processes, including the one making the call, can open
                          //the specified file for concurrent read access
                          
       - FILE_SHARE_WRITE //allows concurrent writing to the specified file

 * lpSecurityAttributes is a pointer to a SECURITY_ATTRIBUTES structure which can be 
   NULL for default security
   

 * dwCreate: Specifies the action to take; create a new file, overwrite an existing
   file, etc
   
    - OPTIONS:
       - CREATE_NEW            //create a new file; fails if specified file already exists
       - CREATE_ALWAYS         //create a new file, or overwrite existing file
       - OPEN_EXISTING         //opens an existing file; fails if file doesn't exist
       - OPEN_ALWAYS           //opens the specified file and creates it if it doesn't exist
       - TRUNCATE_EXISTING     //sets the file length to zero; destroys all contents if the
                               //specified file exists; fails if it doesn't exist
                               //dwCreate must specify at least GENERIC_WRITE for this option
                               //to be used

 * dwFlagsAndAttributes specifies file attributes and flags; there are 32 flags & attributes
    - attributes are the characteristics of the file
 
 
    - OPTIONS: 
       - FILE_ATTRIBUTE_NORMAL          //can only be used when no other attributes are set; flags can be set, however
       - FILE_ATTRIBUTE_READONLY        //applications can neither write to nor delete the file
       
       - FILE_FLAG_DELETE_ON_CLOSE      //useful for temporary files. Windows deletes the file when the last open HANDLE is closed
       - FILE_FLAG_OVERLAPPED           //an attribute flag that is important for asynchronous I/O
       
       //the below flags specify how a file is processed and help the windows implementation optimize performance and file integrity
       FILE_FLAG_RANDOM_ACCESS          //intended for random access; windows will attempt to optimize file caching
       FILE_FLAG_SEQUENTIAL_SCAN        //used for sequential access; windows will optimize caching accordingly
       FILE_FLAG_WRITE_THROUGH          //advanced flag that are useful in some advanced applications
       FILE_FLAG_NO_BUFFERING           //advanced flag that are useful in some advanced applications
    F
    

 * hTemplateFile is a handle to a template file; it is the HANDLE of an open GENERIC_READ file
   that specifies extended attributes to apply to an newly created file, ignoring dwFlagsAndAttributes
    - it is used for file attributes and can be NULL
       - windows ignores hTemplateFile when an existing file is opened
          - this parameter can be used to set the attributes of a new file to be the same as those of an existing file

USAGE

#include <windows.h>
#include <stdio.h

#define BUFFER_SIZE 256

int main(int argc, LPTSTR argv[])
{
  HANDLE handlerIn = NULL;
  HANDLE handlerOut = NULL;
  DWORD bytesIn, bytesOut;
  char received[BUFFER_SIZE];
  
  if(argc != 3){
    printf("Usage: copyFile source destination\n");
    return 1;
  }
  
  handlerIn = CreateFile(argv[1], GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
  if(handlerIn == INVALID_HANDLE_VALUE){
    printf("Can't open input file. Error: %x\n", GetLastError());
    return 2;
  }
  
  handlerOut = CreateFile(argv[2], GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
  if(handlerOut == INVALID_HANDLE_VALUE){
    printf("Can't open output file. Error: %x\n", GetLastError());
    return 3;
  }
  
  while(ReadFile(handlerIn, received, BUFFER_SIZE, &handlerIn, NULL) && handlerIn > 0){
    WriteFile(handlerOut, received, handlerIn, &handlerOut, NULL);
    if(handlerIn != handlerOut){
      printf("Fatal write error: %x\n", GetLastError());
      return 4;
    }
  }
  CloseHandle(handlerIn);
  CloseHandle(handlerOut);
  return 0;
  
}

 * the windows.h is always necessary and contains all Windows function definitions and 
   data types.