Home

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.

Practical Learning Practical Learning: Processing Files with Win32

  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 GroupBox   Bread  
    RadioButton RadioButton rdoBun B&un Alignment: taLeftJustify
    RadioButton RadioButton rdoRoll &Roll Alignment: taLeftJustify
    GroupBox GroupBox   Ingredients  
    CheckBox CheckBox chkRegulars Re&gulars Alignment: taLeftJustify
    CheckBox CheckBox chkSweetener S&weetener Alignment: taLeftJustify
    Checked: true
    CheckBox CheckBox chkCheese Ch&eese Alignment: taLeftJustify
    CheckBox CheckBox chkBacon B&acon Alignment: taLeftJustify
    GroupBox GroupBox   Options  
    BitBtn btnIngredients &Ingredients  
    RadioButton RadioButton rdoMayonnaise &Mayonnaise Alignment: taLeftJustify
    RadioButton RadioButton rdoKetchup &Ketchup Alignment: taLeftJustify
    RadioButton 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

File Saving

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.

Practical Learning Practical Learning: Saving a File

  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

File Opening

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 Practical Learning: Opening a File

  1. Display the main form. From the Dialogs tab of the Component Palette, click the OpenDialog button and click the form
  2. Change its properties as follows:
    DefaultExt: fst
    Filter: Fast Food Files (*.fst)|*.fst|Text Files (*.txt)|*.txt|All Files
    Title: Open a Previous Order

     
  3. On the form, double-click the Open button and implement its OnClick event as follows:
     
    //---------------------------------------------------------------------------
    void __fastcall TfrmMain::btnOpenClick(TObject *Sender)
    {
    	HANDLE hFile;
    	DWORD dFileSize, dBytesRead;
    	BOOL bResult;
    
    	if( OpenDialog1->Execute() == True )
    	{
    		__try {
    	hFile = CreateFile(OpenDialog1->FileName.c_str(), GENERIC_READ,
    				0, NULL, OPEN_EXISTING,
    				FILE_ATTRIBUTE_NORMAL, NULL);
    			if( hFile == INVALID_HANDLE_VALUE )
    			{
    			ShowMessage("There was a problem opening the file");
    				return;
    			}
    
    			dFileSize = GetFileSize(hFile, NULL);
    			if( dFileSize == 0xFFFFFFFF )
    			{
    				ShowMessage("Invalid file size");
    				return;
    			}
    
    	bResult = ReadFile(hFile, &CustOrder, dFileSize, &dBytesRead, NULL);
    
    			if( bResult == FALSE )
    			{
    				ShowMessage("The file could not be read");
    				return;
    			}
    
    			edtClerk->Text = CustOrder.strClerk;
    			edtOrderDate->Text = CustOrder.dteOrderDate;
    			if( CustOrder.iBread == 0 )
    				rdoBun->Checked = True;
    			else if( CustOrder.iBread == 1 )
    				rdoRoll->Checked = True;
    
    			if( CustOrder.iMeat == 0 )
    				rdoBeefPatty->Checked = True;
    			else if( CustOrder.iMeat == 1 )
    				rdoGrilledChicken->Checked = True;
    			else if( CustOrder.iMeat == 2 )
    				rdoChickenBreast->Checked = True;
    
    			bLettuce = CustOrder.bLettuce;
    			bOnion = CustOrder.bOnion;
    			bTomato = CustOrder.bTomato;
    			bPickles = CustOrder.bPickles;
    
    			if( (bLettuce == False) &&
    			    (bOnion == False) &&
    			    (bTomato == False) &&
    			    (bPickles == False) )
    				chkRegulars->State = cbUnchecked;
    			else if( (bLettuce == True) &&
    				 (bOnion == True) &&
    				 (bTomato == True) &&
    				 (bPickles == True) )
    				chkRegulars->State = cbChecked;
    			else
    				chkRegulars->State = cbGrayed;
    
    			chkCheese->Checked = CustOrder.bCheese;
    			chkBacon->Checked = CustOrder.bBacon;
    			if( CustOrder.iIngredients == 0 )
    				rdoMayonnaise->Checked = True;
    			else if( CustOrder.iIngredients == 1 )
    				rdoKetchup->Checked = True;
    			else if( CustOrder.iIngredients == 2 )
    				rdoMustard->Checked = True;
    
    			chkSweetenerClick(Sender);
    			EvaluatePrice();
    		}
    		__finally
    		{
    			if( hFile != INVALID_HANDLE_VALUE )
    				CloseHandle(hFile);
    		}
    	}
    }
    //---------------------------------------------------------------------------
  4. Test the application and open the previous order saved to file
  5. After using the form, close it and return to Bcb
  6. Save All
Home Copyright © 2005-2007 FunctionX, Inc.