File Processing: Win32

File Creation

In your VCL applications, even on console applications created on the Microsoft Windows operating system, besides the C, the C++, and the VCL means of saving and opening files, the Win32 library provides its mechanism of file processing.

In order to use a file, you must obtain a handle for it. You can obtain a file handle by calling the CreateFile() function. Its syntax is:

HANDLE CreateFile(
	LPCTSTR lpFileName,
	DWORD dwDesiredAccess,
	DWORD dwShareMode,
	LPSECURITY_ATTRIBUTES lpSecurityAttributes,
	DWORD dwCreationDisposition,
	DWORD dwFlagsAndAttributes,
	HANDLE hTemplateFile
);

The lpFileName argument is a null-terminated string that represents the name of the file. You can explicitly specify it as a double-quoted string. If you want the user to save the current file or to open an existing file by the user specifying the name of the file, you can use an OpenDialog or a SaveDialog objects. In this case the lpFileName can be obtained with the TOpenDialog::FileName or the TSaveDialog::FileName member variables.

The dwDesiredAccess argument specifies the type of operation that will be performed on the file. It can have one or a combination of the following values:

• 0: Information about a device (floppy, CD, DVD, hard disk, etc) will be retrieved without a file being accessed
• DELETE: The file can be deleted
• READ_CONTROL: The read rights of the file can be accessed or read from
• STANDARD_RIGHTS_EXECUTE: Same as READ_CONTROL
• STANDARD_RIGHTS_READ: Same as READ_CONTROL
• STANDARD_RIGHTS_WRITE: Same as READ_CONTROL
• SYNCHRONIZE: The file can be synchronized
• WRITE_DAC: The discretionary access control list (DACL) can be modified
• WRITE_OWNER: The owner of the file can be changed
• FILE_EXECUTE: The file can be executed. For example, if the file being accessed is an application, it can be launched
• FILE_READ_DATA: The data of the file can be read from
• FILE_WRITE_DATA: Data can be written to the file
• FILE_APPEND_DATA: data can be added to end of the file
• FILE_READ_ATTRIBUTES: The attributes of the file can be accessed or viewed
• FILE_READ_EA: The extended attributes of the file can be read from
• FILE_WRITE_ATTRIBUTES: The attributes of the file can be modified
• FILE_WRITE_EA: The extended attributes of the file can be written to
• STANDARD_RIGHTS_READ: The read rights of the file can be read
• STANDARD_RIGHTS_WRITE: The write rights of the file can be modified

Omitting the 0 value, the above flags can be combined using the bitwise OR operator. Alternatively, you can pass one of the following values for a combination of flags:

• STANDARD_RIGHTS_REQUIRED: Combines DELETE, READ_CONTROL, WRITE_DAC, and WRITE_OWNER 
• STANDARD_RIGHTS_ALL: Combines DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER, and SYNCHRONIZE
• FILE_ALL_ACCESS: The user will be able to perform any allowed operation on the file
• GENERIC_EXECUTE: combines FILE_READ_ATRIBUTES, STANDARD_RIGHTS_EXECUTE, and SYNCHRONIZE
• GENERIC_READ: combines FILE_READ_ATRIBUTES, FILE_READ_DATA, FILE_READ_EA, STANDARD_RIGHTS_READ, and SYNCHRONIZE
• GENERIC_WRITE: combines FILE_APPEND_DATA, FILE_WRITE_ATRIBUTES, FILE_WRITE_DATA, FILE_WRITE_EA, STANDARD_RIGHTS_WRITE, and SYNCHRONIZE

The dwShareMode argument controls how the file can be shared. Its possible values are:

• 0: The file will not be shared
• FILE_SHARE_DELETE: (Available only on Windows NT and 2000) The file can be shared and accessed by more than one user. Also, a user can request to delete it. If a user attempts to delete this file, his or her access rights will be checked
• FILE_SHARE_READ: The file can be accessed only if the user is allowed to read from it
• FILE_SHARE_WRITE: The file can be accessed only if the user is allowed to write to it

The lpSecurityAttributes argument specifies some security attributes used when creating the file. Such attributes are defined as SECURITY_ATTRIBUTES value. You can pass this argument as NULL, in which case the security attributes would be ignored.

The dwCreationDisposition argument specifies the behavior to adopt whether the file already exists or is just being created. It can have one of the following values:

• CREATE_ALWAYS: If the file does not exist, it will be created. If the file exists already, it will be destroyed and replaced by a new one with an attribute of Archive
• CREATE_NEW: If the file does not exist, it will be created. If the file already exists, the CreateFile() function would fail
• OPEN_ALWAYS: If the file does not exist, it will be created. If the file already exists, it would be opened
• OPEN_EXISTING: If the file does not exist, the CreateFile() function would fail. If the file already exists, it would be opened
• TRUNCATE_EXISTING: If the file does not exist, the CreateFile() function would fail. If the file already exists, it must be opened with a GENERIC_WRITE dwDesiredAccess flag and subsequently, its size would be reduced to 0 bytes

The dwFlagsAndAtributes argument specifies the attribute(s) to apply to the file. It can have one or a combination of the following values:

• FILE_ATTRIBUTE_ARCHIVE: The file will be marked as Archive
• FILE_ATTRIBUTE_ENCRYPTED: The file will be encrypted
• FILE_ATTRIBUTE_HIDDEN: The file will be marked as Hidden and consequently cannot display in Windows Explorer, My Computer, or any file viewing tool
• FILE_ATTRIBUTE_NORMAL: The flag must be used by itself and means that the file has ordinary attributes
• FILE_ATTRIBUTE_NOT_CONTENT_INDEXED: The file will not be indexed
• FILE_ATTRIBUTE_OFFLINE: The file will be accessed offline
• FILE_ATTRIBUTE_READONLY: The file will be marked as Read-Only. Users can open and read its contents but cannot modify or delete it
• FILE_ATTRIBUTE_SYSTEM: The file is part of the operating system
• FILE_ATTRIBUTE_TEMPORARY: The file will be marked as a temporary object

The above attributes can also be combined with the following values:

• FILE_FLAG_BACKUP_SEMANTICS
• FILE_FLAG_DELETE_ON_CLOSE
• FILE_FLAG_NO_BUFFERING
• FILE_FLAG_OPEN_NO_RECALL
• FILE_FLAG_OPEN_REPARSE_POINT
• FILE_FLAG_OVERLAPPED
• FILE_FLAG_POSIX_SEMANTICS
• FILE_FLAG_RANDOM_ACCESS
• FILE_FLAG_SEQUENTIAL_SCAN
• FILE_FLAG_WRITE_THROUGH

The hTemplateFile argument is a handle to a template file. If you do not have or cannot use a file template (for example they are not supported on home operating systems), pass this argument as NULL.

If the CreateFile() function succeeds, it returns a handle to the file and you can use it as you see fit, to analyze it, to read its contents if allowed, or to write data to it if permitted. If this function fails, it returns INVALID_HANDLE_VALUE.

1. Start a new application with its default form
2. To save it, on the Standard toolbar, click the Save button
3. Locate your exercises folder and display it in the Save In combo box
4. Click the Create New Folder button. Type FastFood3 and press Enter twice to display it in the Save In combo box
5. Save the unit as Exercise and the project as FastFood3
6. Design the form as follows:
    

   Control Name Caption/Text Other Properties Bevel       Label   Processed By:   Edit edtProcessedBy     Label   Order Date:   MaskEdit     EditMask: !99/99/0000;1;_ GroupBox   Bread   RadioButton rdoBun B&un Alignment: taLeftJustify RadioButton rdoRoll &Roll Alignment: taLeftJustify GroupBox   Ingredients   CheckBox chkRegulars Re&gulars Alignment: taLeftJustify CheckBox chkSweetener S&weetener Alignment: taLeftJustify Checked: true CheckBox chkCheese Ch&eese Alignment: taLeftJustify CheckBox chkBacon B&acon Alignment: taLeftJustify GroupBox   Options   BitBtn btnIngredients &Ingredients   RadioButton rdoMayonnaise &Mayonnaise Alignment: taLeftJustify RadioButton rdoKetchup &Ketchup Alignment: taLeftJustify RadioButton rdoMustard Mus&tard Alignment: taLeftJustify BitBtn     Kind: bkClose Label   Total Price:   Edit edtTotalPrice $2.35   Bevel       BitBtn btnSave &Save   BitBtn btnOpen &Open

7. In the header file of the form, create a structure called TCustomerOrder and declare its instance in the private section of the form’s class:
    

   //--------------------------------------------------------------------------- struct TCustomerOrder { char strClerk[20]; TDateTime dteOrderDate; Integer iBread; Integer iMeat; Boolean bLettuce; Boolean bOnion; Boolean bTomato; Boolean bPickles; Integer iIngredients; Boolean bCheese; Boolean bBacon; }; //--------------------------------------------------------------------------- class TfrmMain : public TForm { __published: // IDE-managed Components . . . private: void __fastcall EvaluatePrice(); TCustomerOrder CustOrder; // User declarations public: // User declarations __fastcall TfrmMain(TComponent* Owner); }; //---------------------------------------------------------------------------

8. Save all
9. To add another form, on the main menu, click File -> New -> Form
10. Design the form as follows
     

    Control Name Caption/Text Other Properties Bevel       CheckBox chkLettuce &Lettuce Alignment: taLeftJustify CheckBox chkOnion &Onion Alignment: taLeftJustify CheckBox chkTomato &Tomato Alignment: taLeftJustify CheckBox chkPickles &Pickles Alignment: taLeftJustify Button   OK ModalResult: mrOk Button   Cancel ModalResult: mrCancel Form     Ingredients BorderStyle: bsDialog Position: poScreenCenter

11. Save the unit as Ingredients

As its name suggests, the CreateFile() function is used to create a stream. Actually, it initiates a file object. After calling it, since it returns a file handle, your next action is to decide what to do with this handle and one of the actions you can take is to store a newly created file into a drive.

To save a file in Win32, you can call the WriteFile() function. Of course, in order to save a file, you must first retrieve the value to be saved. This value can be made of a single variable or a complex class. Therefore, you must know what the value to save is made of because it must be supplied to the WriteFile() function. The syntax of this function is:

BOOL WriteFile(HANDLE hFile,
                         LPCVOID lpBuffer,
                         DWORD nNumberOfBytesToWrite,
                         LPDWORD lpNumberOfBytesWritten,
                         LPOVERLAPPED lpOverlapped);

The hFile argument is the handle to the file. It is typically the return value of a call to the CreateFile() function. Since in this case we are trying to save a file, the file should/must have been created with at least the GENERIC_WRITE flag for the dwDesiredAccess argument of the CreateFile() function.

The lpBuffer argument is the object that will be saved. As you can see, it is defined as a pointer to VOID, meaning that its type is not known to the function, which leaves it up to you to decide what type of value is being saved. It can be a C/C++ generic type (integer, character, floating-point value, or their variants). It can be a VCL or a Win32 type of object. It can also be a completely new type that you create as a simple C structure or a more elaborate C++, VCL, or Win32 class.

The nNumberOfBytesToWrite argument is the number of bytes to save. As the DWORD type indicates, it must be a positive integer.

The lpNumberOfBytesWritten argument is a positive integer returned by the function as the number of bytes that were written.

The lpOverlapped argument is necessary only if the file was created with the FILE_FLAG_OVERLAPPED flag for the dwFlagsAndAtributes argument of the CreateFile() function.

1. From the Dialogs tab of the Component Palette, click the SaveDialog button and click on the form
2. Change its properties as follows:
   DefaultExt: fst
   Filter: Fast Food Files (*.fst)|*.fst|Text Files (*.txt)|*.txt|All Files
   Title: Save Customer's Order
3. On the form, double-click the Save button and implement its OnClick() event as follows:
    

   //--------------------------------------------------------------------------- void __fastcall TfrmMain::btnSaveClick(TObject *Sender) { HANDLE hFile; DWORD dFileSize, dBytesWritten; BOOL bResult; if( SaveDialog1->Execute() ) { __try { hFile = CreateFile(SaveDialog1->FileName.c_str(), GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_FLAG_RANDOM_ACCESS, NULL); if( hFile == INVALID_HANDLE_VALUE ) { ShowMessage("There was a problem saving the customer order"); return; } dFileSize = sizeof(CustOrder); if( dFileSize == 0xFFFFFFFF ) { ShowMessage("Invalid file size"); return; } strcpy(CustOrder.strClerk, edtClerk->Text.c_str()); CustOrder.dteOrderDate = edtOrderDate->Text; if( rdoBun->Checked ) CustOrder.iBread = 0; else if( rdoRoll->Checked ) CustOrder.iBread = 1; if( rdoBeefPatty->Checked ) CustOrder.iMeat = 0; else if( rdoGrilledChicken->Checked ) CustOrder.iMeat = 1; else if( rdoChickenBreast->Checked ) CustOrder.iMeat = 2; CustOrder.bLettuce = dlgIngredients->chkLettuce->Checked; CustOrder.bOnion = dlgIngredients->chkOnion->Checked; CustOrder.bTomato = dlgIngredients->chkTomato->Checked; CustOrder.bPickles = dlgIngredients->chkPickles->Checked; CustOrder.bCheese = chkCheese->Checked; CustOrder.bBacon = chkBacon->Checked; if( rdoMayonnaise->Checked ) CustOrder.iIngredients = 0; else if( rdoKetchup->Checked ) CustOrder.iIngredients = 1; else if( rdoMustard->Checked ) CustOrder.iIngredients = 2; bResult = WriteFile( hFile, &CustOrder, dFileSize, &dBytesWritten, NULL ); if( bResult == FALSE ) { ShowMessage("The file could not be saved"); return; } } __finally { if( hFile != INVALID_HANDLE_VALUE ) CloseHandle(hFile); } } } //---------------------------------------------------------------------------

4. Test the application with a customer order and save it
    
   
5. Close the form and return to Bcb
6. Save All

Besides saving a file, another operation you can perform on streams using the Win32 approach is to open an existing file. Reading a file is performed sing the ReadFile() function. Its syntax is:

BOOL ReadFile(HANDLE hFile,
              LPVOID lpBuffer,
              DWORD nNumberOfBytesToRead,
              LPDWORD lpNumberOfBytesRead,
              LPOVERLAPPED lpOverlapped);

The hFile parameter is a handle to the file to be opened. It can be the return value of a previous call to the CreateFile() function.

The lpBuffer parameter is the object or value to be opened. As its type suggests, it can be anything and it is up to you to define what type of value is being opened.

The nNumberOfBytesToRead parameter is the number of bytes to read.

The lpNumberOfBytesRead parameter is a returned value of the function, indicating the number of bytes that were read.

The lpOverlapped parameter is used if the file is being opened as “overlapped”, in which case the lpOverlapped argument of the CreateFile() function would have received the FILE_FLAG_OVERLAPPED flag.

Practical Learning: Opening a File