Windows APIs File Processing Copyright © 2016 Curt Hill

Introduction In previous presentations we have seen some general Windows API items Today we consider file processing Recall two needed functions, of which we will still have need: GetLastError CloseHandle Copyright © 2016 Curt Hill

MicroSoft Files In DOS 1 MicroSoft used a control block approach The file was represented in memory by a struct This control block had different things at different times File names Disk file pointers This struct was in user memory Copyright © 2016 Curt Hill

Control Block Issues Since the control block is owned by the user it is subject to mishandling The user program may change it while the file is open accidentally or intentionally to achieve some unintended purpose This puts an undue error checking burden on the OS Or causes aborts Copyright © 2016 Curt Hill

Next In about DOS 2 MicroSoft introduces a different set of APIs These were handle based The control block is now in system memory and no longer accessible to the user The handle is a long void * pointer Whether it is a subscript or pointer is now irrelevant Range checking become easier Very difficult for user to mess with Copyright © 2016 Curt Hill

Handles The only thing we will be holding on to is a handle We will obtain this handle with CreateFile This will also open it and set direction We will do input with ReadFile and output with WriteFile CloseHandle will close the file Copyright © 2016 Curt Hill

Generalization One of the goals of an OS is to make the file interface common over many different kind of devices CreateFile does this, so it can access: Files Pipes Directories Volumes Console Network Thus it can get complicated Copyright © 2016 Curt Hill

Signature HANDLE WINAPI CreateFile( _In_ LPCTSTR lpFileName, _In_ DWORD dwDesiredAccess, _In_ DWORD dwShareMode, _In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes, _In_ DWORD dwCreationDisposition, _In_ DWORD dwFlagsAndAttributes, _In_opt_ HANDLE hTemplateFile ); Copyright © 2016 Curt Hill

File Specification First parameter is a null terminated string to indicate the file to open Either forward slashes or backslashes may be used May include directory and volume specification The string is usually ASCII Use FileCreateW for UniCode Copyright © 2016 Curt Hill

Access The second parameter is the direction of the file There are two constants: GENERIC_READ GENERIC_WRITE These may be bit stringed Ored If a zero is supplied then the program can neither read nor write, but only examine some of the attributes of the file The attributes must be consistent with the sharing mode Copyright © 2016 Curt Hill

Share Mode Third parameter is how to share the file with other threads and processes This is another bit flag item Flags: 0 – no sharing FILE_SHARE_READ FILE_SHARE_WRITE FILE_SHARE_DELETE Two processes may share a file for reading if they both have FILE_SHARE_READ Copyright © 2016 Curt Hill

Security Attributes The fourth parameter is a pointer We have seen this one in CreateProcess and CreateThread Perhaps it is time to talk about it This is a long pointer to a struct If it is NULL, the security attributes cannot be inherited by a child thread or process Copyright © 2016 Curt Hill

Security Attributes typedef struct _SECURITY_ATTRIBUTES { DWORD nLength; // Size LPVOID lpSecurityDescriptor; BOOL bInheritHandle; }; The security descriptor has its own set of API functions: InitializeSecurityDescriptor GetSecurityDescriptor SetSecurityDescriptor Among others Copyright © 2016 Curt Hill

Creation Flags The fifth parameter is a DWORD of bit flags but they may not be combined These are usually only used in writes They include CREATE_ALWAYS CREATE_NEW OPEN_ALWAYS OPEN_EXISTING TRUNCATE_EXISTING Copyright © 2016 Curt Hill

Creation and Direction Not all combinations of Creation flags and Access flags make sense Open flags and Read flags should pair as do Create or Truncate with Write Some odd combinations do exist Always use GetLastError to determine if things went well Copyright © 2016 Curt Hill

Attributes Each OS may apply file attributes For Windows these include things like: Hidden System Read-only You may specify these with the sixth parameter This only applies when writing Ignored in reading Copyright © 2016 Curt Hill

Attribute Flags Another bit flag value that can OR together several of the following constants FILE_ATTRIBUTE_NORMAL (May only be used alone.) FILE_ATTRIBUTE_READONLY FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY Not every file system supports all Copyright © 2016 Curt Hill

Other Attribute Flags There are other flags which are not applied to the file on disk but its processing FILE_FLAG_NO_BUFFERING FILE_FLAG_WRITE_THROUGH FILE_FLAG_RANDOM_ACCESS FILE_FLAG_SEQUENTIAL_SCAN Allows cache optimization FILE_FLAG_OVERLAPPED Overlap I/O with file processing There are several others including security attributes Consider buffering and caching Copyright © 2016 Curt Hill

Last Parameter Handle to template file This supplies attributes instead of using the previous parameters This may be NULL Copyright © 2016 Curt Hill

Return Values CreateFile returns a handle in either case Success: a valid handle Failure: INVALID_HANDLE_VALUE Use GetLastError if it fails Copyright © 2016 Curt Hill

I/O The only point of CreateFile is to obtain a file handle This file handle will be used to input or output data This is performed by these two functions ReadFile WriteFile We next consider them Copyright © 2016 Curt Hill

ReadFile Signature BOOL WINAPI ReadFile( _In_ HANDLE hFile, _Out_ LPVOID lpBuffer, _In_ DWORD nNumberOfBytesToRead, _Out_opt_ LPDWORD lpNumberOfBytesRead, _Inout_opt_ LPOVERLAPPED lpOverlapped ); Copyright © 2016 Curt Hill

ReadFile We pass the handle, a buffer and the number of bytes we want read It returns as the result of success or failure in the function result It changes the buffer We may optionally pass a pointer that gives us the number of bytes read If this is NULL we do not know how many bytes returned In general we want this, the buffer is not null terminated Copyright © 2016 Curt Hill

ReadFile Again There is a lot of processing that is not done by this ReadFile does not care about whitespace, line boundaries, conversion of types or even whether the file is text or binary If we ask for 500 bytes it will give us 500 bytes ReadFile will happily split a line, word or binary data in two to make this happen Only EOF or an error will return fewer Copyright © 2016 Curt Hill

ReadFile Process Often we will try to read in the entire file or a large chunk We will then process lines internally Contrast this approach with using fstreams and getline Copyright © 2016 Curt Hill

Size If CreateFile does not ask for read or write ability all that can be obtained is attributes of the file These are also available with read or write access One of these is: DWORD WINAPI GetFileSize( _In_ HANDLE hFile, _Out_opt_ LPDWORD lpFileSizeHigh ); Copyright © 2016 Curt Hill

Other Attributes You may also obtain other pieces of information from an existing file GetFileType GetFileTime Among others You may also iterate through the files in a directory with FindFirstFile FindNextFile We will not cover these unless some need arises Copyright © 2016 Curt Hill

WriteFile Signature BOOL WINAPI WriteFile( _In_ HANDLE hFile, _In_ LPCVOID lpBuffer, _In_ DWORD nNumberOfBytesToWrite, _Out_opt_ LPDWORD  lpNumberOfBytesWritten, _Inout_opt_ LPOVERLAPPED lpOverlapped ); Copyright © 2016 Curt Hill

Buffers The area to read or write is a void * pointer This could be a character string an array of integers or doubles an array of objects No conversion of any sort is performed Just take the memory and read into it or write from it Copyright © 2016 Curt Hill

Other Functions Windows provides functions to do most of the things that can be done through the command line MoveFile takes two strings: Existing name and a new name Does rename as well CopyFileEx takes two strings and BOOL Boolean is to fail if target exists DeleteFile take a string These return a Boolean for success Copyright © 2016 Curt Hill

Finally When we are done reading or writing a CloseHandle is applied This is when an output file is finalized so should not be missed Copyright © 2016 Curt Hill