CreateFile

// C/C++
HANDLE CreateFile(LPCTSTR lpFileName, 
                  DWORD dwDesiredAccess, 
                  DWORD dwShareMode, 
                  LPSECURITY_ATTRIBUTES lpSecurityAttributes, 
                  DWORD dwCreationDistribution, 
                  DWORD dwFlagsAndAttributes, 
                  HANDLE hTemplateFile);

// Delphi
CreateFile(lpFileName: PChar;
     dwDesiredAccess: Integer;
     dwShareMode: Integer;
     lpSecurityAttributes: PSecurityAttributes;
     dwCreationDisposition: LongWord;
     dwFlagsAndAttributes: LongWord;
     hTemplateFile: THandle;
): THandle; 

Funkcja tworzy lub otwiera plik, urządzenie komunikacyjne, urządzenie dyskowe itp. Zwraca uchwyt, który może być użyty w celu uzyskania dostępu do danego obiektu. Funkcja może również otworzyć, a następnie zwrócić uchwyt do katalogu. Jeżeli aplikacja nie dokonuje już żadnych operacji na danym obiekcie, należy wywołać funkcje CloseHandle, która zamyka uchwyt danego obiektu.

Parametry:

lpFileName
Wskaźnik do ciągu znaków zakończonych zerowym ogranicznikiem (C ? łańcucha). Specyfikuje nazwę pliku, zasobów komunikacyjnych, potoku, urządzenia dyskowego (NT), połączenia sieciowego typu konsoli. Jeżeli parametr lpFileName reprezentuje ścieżkę dostępu, wówczas wartość domyślana długości łańcucha jest ograniczona do MAX_PATH znaków. Pracując w Win NT można pokonać ograniczenie co do długości omawianego ciągu znaków posługując się konwencją nazewnictwa katalogów UNC (ang. Universal Naming Convention). Zgodnie z nią do identyfikowania nazwy komputera stosowany jest podwójny ukośnik wsteczny \ (ang. backslash), natomiast pojedynczy ukośnik wsteczny wskazuje katalog na dysku tego komputera np. "\?\C:\katalog1\katalog2" co zostanie zinterpretowane jako "C:\katalog1\katalog2" lub "\?\UNC\katalog1\katalog2\katalog3", który to zapis będzie zinterpretowany następująco: "\katalog1\katalog2\katalog3".

dwDesiredAccess
Specyfikacja rodzaju dostępu do obiektu. Parametr ten może być kombinacją następujących wartości:
0 ? przyznanie aplikacji aktualnego rodzaju dostępu.
GENERIC_READ ? dostęp do odczytu.
GENERIC_WRITE ? dostęp do zapisu.

dwShareMode
Wyszczególnia, w jaki sposób dany obiekt (plik) może być współdzielony:
0 ? obiekt nie może być współdzielony.
FILE_SHARE_DELETE ? współdzielenie z operacjami usuwania (Win NT).
FILE_SHARE_READ ? tryb współdzielenia z operacjami czytania.
FILE_SHARE_WRITE ? tryb współdzielenia z operacjami zapisu.

lpSecurityAttributes
Wskaźnik do struktury SECURITY_ATTRIBUTES zawierającej deskryptor zabezpieczeń obiektu i określającej, czy zwracany identyfikator jest dziedziczony.

typedef struct _SECURITY_ATTRIBUTES {   
    DWORD  nLength; 
    LPVOID lpSecurityDescriptor; 
    BOOL   bInheritHandle; 
} SECURITY_ATTRIBUTES;

nLength ? rozmiar struktury w bajtach.
lpSecurityDescriptor ? wskaźnik do deskryptora zabezpieczeń obiektu (Win NT). Jeżeli ustalono NULL zostanie wybrana wartość domyślna.
bInheritHandle ? wyszczególnia, czy zwracany przez CreateFile identyfikator jest dziedziczony przy tworzeniu nowego procesu. Wartość TRUE oznacza, że nowy proces dziedziczy ten identyfikator.

DwCreationDistribution
Rodzaje operacji wykonywanych na pliku:
CREATE_NEW ? utworzenie nowego pliku. Funkcja nie będzie wykonana pomyślnie, jeżeli plik już istnieje.
CREATE_ALWAYS ? utworzenie nowego pliku niezależnie od tego czy już istnieje. Jeżeli plik istnieje, nowy zostanie zapisany na istniejącym.
OPEN_EXISTING ? otwarcie istniejącego pliku. Jeżeli plik nie istnieje funkcja nie będzie wykonana pomyślnie.
OPEN_ALWAYS ? otwarcie istniejącego pliku. Jeżeli takowy nie istnieje, zostanie stworzony identycznie jak przy pomocy CREATE_NEW.
TRUNCATE_EXISTING ? tuż po otwarciu plik jest okrojony do rozmiaru 0 bajtów. Wymagane jest wcześniejsze jego utworzenie przynajmniej z rodzajem dostępu GENERIC_WRITE. Funkcja nie będzie wykonana pomyślnie jeżeli plik nie istnieje.

dwFlagsAndAttributes
Określenie atrybutów i flag pliku.
Atrybut:
FILE_ATTRIBUTE_ARCHIVE ? plik powinien zostać zarchiwizowany.
FILE_ATTRIBUTE_COMPRESSED ? plik lub katalog jest skompresowany.
FILE_ATTRIBUTE_HIDDEN ? plik ukryty.
FILE_ATTRIBUTE_NORMAL ? plik nie posiada innych atrybutów. Atrybut jest ważny tylko wówczas, gdy jest używany indywidualnie (bez innych).
FILE_ATTRIBUTE_OFFLINE ? dane zawarte w pliku nie są bezpośrednio udostępniane.
FILE_ATTRIBUTE_READONLY ? plik tylko do odczytu.
FILE_ATTRIBUTE_SYSTEM ? plik jest częścią lub jest używany wyłącznie przez system operacyjny.
FILE_ATTRIBUTE_TEMPORARY ? plik jest używany do czasowego przechowywania. Powinien być usunięty jeżeli nie jest wykorzystywany.

Flaga:
FILE_FLAG_WRITE_THROUGH ? zawartość pliku zostaje zapisana pośrednio poprzez bufor.
FILE_FLAG_OVERLAPPED ? w przypadku operacji realizowanych w znaczącym przedziale czasu przez funkcje ReadFile, WriteFile, ConnectNamedPipe i TransactNamedPipe, można oczekiwać komunikatu ERROR_IO_PENDING ? realizowana jest operacja nakładanego wejścia/ wyjścia. W tym kontekście musi nastąpić odwołanie do struktury OVERLAPPED zawierającej informacje używane w operacjach nakładanego wejścia/wyjścia.

typedef struct _OVERLAPPED {   
    DWORD  Internal; 
    DWORD  InternalHigh; 
    DWORD  Offset; 
    DWORD  OffsetHigh; 
    HANDLE hEvent; 
} OVERLAPPED;

Internal ? zarezerwowane dla systemu operacyjnego. Człon ten staje się istotny, gdy funkcja GetOverlappedResult zwróci rezultat wykonanej operacji nakładanego wejścia/wyjścia w przypadku pliku, potoku lub urządzenia zewnętrznego.
InternalHigh ? zarezerwowane dla systemu. Specyfikuje długość transferowanych danych. Staje się istotny, gdy funkcja GetOverlappedResult zwraca wartość TRUE.
Offset ? określa wskaźnik położenia (w)pliku przeznaczonym do transferu. Traktowany jest jako offset wyznaczony w stosunku do początku pliku.
OffsetHigh? część bardziej znacząca offsetu.
hEvent ? wyszczególnienie sposobu określenia końca transferu danych.

FILE_FLAG_NO_BUFFERING ? instruuje system operacyjny aby otworzył plik bez pośredniego buforowania jego zawartości. Aplikacja musi spełniać pewne wymagania pracując z plikiem tak otwartym. Najważniejszym z nich jest to, by dane zawarte w pliku były odczytywane w porcjach będących całkowitą wielokrotnością rozmiaru sektora wolumenu . Dla przykładu przy rozmiarze sektora 512 bajtów dane mogą być czytane w porcjach po 512, 1024, 2048 ... bajtów. Uzyskanie informacji o rozmiarze sektora wolumenu może być dostępne dzięki funkcji Win32 API GetDiskFreeSpace. Przy otwarciu pliku adres bufora używanego do operacji czytania i zapisywania musi być przedstawiony w postaci całkowitej wielokrotności rozmiaru sektora wolumenu. W celu określenia bufora można użyć funkcji VirtualAlloc ustalającej adres w postaci całkowitej wielokrotności rozmiaru strony pamięci używanej przez system operacyjny.
FILE_FLAG_RANDOM_ACCESS ? sygnalizuje plik o swobodnym sposobie dostępu. Dostęp do każdego jego elementu możliwy jest przez bezpośrednie wskazanie odpowiedniego adresu danego elementu.
FILE_FLAG_SEQUENTIAL_SCAN ? sygnalizuje plik o sekwencyjnym sposobie dostępu.
FILE_FLAG_DELETE_ON_CLOSE ? system natychmiast usuwa z pamięci plik po tym jak przydzielony mu identyfikator zostanie zwolniony. Późniejsze operacje otwarcia pliku nie będą wykonywane pomyślnie, chyba że wcześniej tryb współdzielenia został ustalony jako FILE_SHARE_DELETE.
FILE_FLAG_BACKUP_SEMANTICS ? podaje czy plik jest otwierany lub utworzony jako kopia zapasowa SE_BACKUP_NAME lub jako plik odzyskany SE_RESTORE_NAME.
FILE_FLAG_POSIX_SEMANTICS ? wyszczególnienie rodzaju dostępu do pliku zgodnie z zasadami POSIX. Funkcja CreateFile prawidłowo wywołana zwraca identyfikator pliku. Jeżeli plik już istnieje przed wywołaniem funkcji z CREATE_ALWAYS lub OPEN_ALWAYS przypisanymi do dwCreationDistribution, funkcja GetLastError zwróci wartość ERROR_ALREADY_EXISTS. Jeżeli plik nie istnieje GetLastError zwraca 0. W przypadku gdy funkcja CreateFile nie została wykonana pomyślnie należy oczekiwać wartości INVALID_HANDLE_VALUE.

Uwagi
Windows 95/98/Me: Wersja Unicode funkcji (CreateFileW) jest wspierana przez Warstwę Unicode (Microsoft Layer for Unicode) - MSLU. Aby użyć funkcji w wersji Unicode, należy dokonać pewnych zmian w aplikacji wedle wskazówek nakreślonych w Microsoft Layer for Unicode on Windows 95/98/Me Systems (eng)