|< C & Win32 programming 7 | Main | ANSI, Multibyte, Unicode and Localization 1 >| Site Index | Download |

MODULE F1

WIN32 AND C PROGRAMMING 8

What are in this Module?

Mounting And Unmounting Volume
Program Examples
Volume Management Functions
File Management: File Management Functions
File Management Control Codes
File Management Structures
File Management Enumeration Types

My Training Period: xx hours. Before you begin, read some instruction here.

Abilities that supposed to be acquired:

Be familiar and play around with the Win32 programming.
Able to find and collect information about volume management functions.
Able to understand and use the collected information about the functions in programs.

Mounting And Unmounting Volume

Mounting a volume is a two-step process:

Call GetVolumeNameForVolumeMountPoint() with the DOS drive letter of the volume you want to mount.

Then use the returned unique volume name and the directory where you want to mount the volume in a call to SetVolumeMountPoint().

Your application can designate any directory on a volume other than the root as a volume mount point. Instead of making the root directory a volume mount point, your application should create a subdirectory and make that a volume mount point.
When a volume is mounted, volume mount points see the drive, not the medium in the drive. Thus, you need not unmount and mount volumes to change removable media.
You can set multiple volume mount points to see the same physical drive. For example, you might have a volume mount point for each of several compact discs, all of which share one CD-ROM drive.
Each point refers to the same physical CD-ROM drive, and you can access any disc in the drive from any of the volume mount points. The advantage of setting multiple volume mount points is that the different paths make clear the difference between different CDs' applications, for example between a word processor and a game.
If a volume fails, paths that cross the failed drive break. Thus, it is best to mount all volumes to the boot drive (usually drive C). It is a useful mnemonic for system administrators to use one directory as the volume mount point for all volumes on the system, but nothing in the volume mount point design requires that you use only one directory.
A volume mount point is a directory where a volume can be mounted but not necessarily where a volume currently is mounted.
NTFS file system volume mount points are implemented by using reparse points and are subject to their restrictions.
It is not necessary to manipulate reparse points in order to use volume mount points; the volume mount point functions handle all the reparse point details for you.
Because volume mount points are directories, you can rename, remove, move, and otherwise manipulate them, like you can with directories.
Only NTFS file system volumes can hold a volume mount point, although any local drive can be mounted on one.
It is not an error to attempt to mount a volume at a volume mount point at which a volume is already mounted. In this case, the system unmounts the preceding volume without sending notifications before attempting to mount the new volume.
It is an error to attempt to mount a volume on a directory that has any files or subdirectories in it. This error occurs for system and hidden directories as well as other directories, and it occurs for system and hidden files.
When mount points are created in a clustered drive, they may be unexpectedly deleted under certain circumstances.
The following Table lists the needed information in order to use the GetVolumeNameForVolumeMountPoint() function.

Information	Description
The function	GetVolumeNameForVolumeMountPoint().
The use	Takes a volume mount point or root directory and returns the corresponding unique volume name.
The prototype	BOOL GetVolumeNameForVolumeMountPoint( LPCTSTR lpszVolumeMountPoint, LPTSTR lpszVolumeName, DWORD cchBufferLength);
Example	#define BUFSIZE MAX_PATH char Buf[BUFSIZE]; GetVolumeNameForVolumeMountPoint( argv[2], // input volume mount point or directory Buf, // output volume name buffer BUFSIZE); // size of volume name buffer
The parameters	lpszVolumeMountPoint - [in] Pointer to a string that contains either the path of a volume mount point with a trailing backslash (\) or a drive letter indicating a root directory in the form "D:\". lpszVolumeName - [out] Pointer to a string that receives the volume name. This name is a unique volume name of the form "\\?\Volume{GUID}\" where GUID is the GUID that identifies the volume. cchBufferLength - [in] Length of the output buffer, in TCHARs. A reasonable size for the buffer to accommodate the largest possible volume name is 50 characters.
The return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
The header file	<windows.h>
Table 9: GetVolumeNameForVolumeMountPoint() information.

The lpszVolumeMountPoint parameter may be a drive letter with appended backslash (\), such as "D:\". Alternatively, it may be a path to a volume mount point, again with appended backslash (\), such as "c:\mnt\edrive\".
Use GetVolumeNameForVolumeMountPoint() to obtain unique volume names for use with other functions that work with volume mount points and volume mounting.
The following Table lists the needed information in order to use the SetVolumeMountPoint() function.

Information	Description
The function	SetVolumeMountPoint().
The use	Mounts the specified volume at the specified volume mount point.
The prototype	BOOL SetVolumeMountPoint( LPCTSTR lpszVolumeMountPoint, LPCTSTR lpszVolumeName );
Example	char Buf[BUFSIZE]; SetVolumeMountPoint( argv[1], // mount point Buf); // volume to be mounted
The parameters	lpszVolumeMountPoint - [in] Pointer to a string that indicates the volume mount point where the volume is to be mounted. This may be a root directory (X:\) or a directory on a volume (X:\mnt\). The string must end with a trailing backslash ('\'). lpszVolumeName - [in] Pointer to a string that indicates the volume to be mounted. This string must be a unique volume name of the form "\\?\Volume{GUID}\" where GUID is a GUID that identifies the volume. The \\?\ turns off path parsing and is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private".
The return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
The header file	<windows.h>
Table10: SetVolumeMountPoint() information.

By Passing a specified path, GetVolumePathName() returns the path to the volume mount point. In other words, it returns the root of the volume where the end point of the specified path resides.
For example, assume you have volume D mounted at C:\Mnt\Ddrive and volume E mounted at C:\Mnt\Ddrive\Mnt\Edrive. Assume you have a file with the path E:\Dir\Subdir\MyFile.txt. If you pass GetVolumePathName() the following input string:

"C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile.txt"

It will return the output path "C:\Mnt\Ddrive\Mnt\Edrive".
If the specified path traverses a junction point, GetVolumePathName() returns the volume to which the junction point refers.
For example, if W:\Adir is a junction point that points to C:\Adir, then GetVolumePathName() invoked on W:\Adir\Afile returns "C:\". If the specified path traverses multiple junction points, the entire chain is followed, so that GetVolumePathName() returns the volume to which the last junction point in the chain refers.
The length of the path returned by this call always is less than or equal to that of the path passed in. A slower but safer way to set the size of the return buffer is to call the GetFullPathName() function and then make sure that the buffer is at least as big as the full path GetFullPathName() returns.
The following Table lists the needed information in order to use the GetVolumePathName() function.

Information	Description
The function	GetVolumePathName().
The use	Retrieves the volume mount point at which the specified path is mounted.
The prototype	BOOL GetVolumePathName( LPCTSTR lpszFileName, LPTSTR lpszVolumePathName, DWORD cchBufferLength);
Example	char lpszFileName[100] = "F:\\...\\..."; char lpszVolumePathName[100]; DWORD cchBufferLength = 100; GetVolumePathName( lpszFileName, lpszVolumePathName, cchBufferLength);
The parameters	lpszFileName - [in] Pointer to the input path string. Both absolute and relative file and directory names, such as ".", are acceptable in this path. lpszVolumePathName - [out] Pointer to a string that receives the volume mount point for the input path. cchBufferLength - [in] Length of the output buffer, in TCHARs.
The return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
The header file	<windows.h>
Table 11: GetVolumePathName() information.

The following program example demonstrates how to mount a file system. This example uses GetVolumeNameForVolumeMountPoint(), SetVolumeMountPoint() and GetVolumePathName() functions.
It has been run at command prompt and make sure you have created the mount point before running the program.
For this program example it is F:\mymntpoint and we will try to mount drive/volume I:\ at the mount point.

//*********mymount.cpp************

// you need to change the path used in this program to yours

#define _WIN32_WINNT 0x0501

#include <windows.h>

#include <stdio.h>

#define BUFSIZE MAX_PATH

int main(int argc, char *argv[ ])

{

BOOL bFlag;

// temporary buffer for volume name

char Buf[BUFSIZE];

// If not enough arguments supplied...for this example you have to create the mount point first

if(argc != 3)

{

    printf("\"%s\" command mounts a volume at a mount point.\n", argv[0]);

    printf("Usage: %s <mount point> <volume to be mounted>\n", argv[0]);

    printf("And make sure the <mount point> exists!!!\n", argv[0]);

    printf("Example: \"%s c:\\mymnt\\gdrive\\ g:\\\"\n", argv[0]);

    // just exit

    return(-1);

}

    // some verification, check the inputs validity

    bFlag = GetVolumeNameForVolumeMountPoint(

              argv[2],         // input volume mount point or directory

                  Buf,           // output volume name buffer

               BUFSIZE    // size of volume name buffer

           );

    if(bFlag != TRUE)

    {

        printf("Retrieving volume name for %s failed.\n", argv[2]);

        // just exit

        return (-2);

    }

    printf("Volume name of %s is %s\n", argv[2], Buf);

    bFlag = SetVolumeMountPoint(

              argv[1],       // mount point

                  Buf);        // volume to be mounted

    // another verification, error checking

    if(!bFlag)

        printf("Attempt to mount %s at %s failed.\n", argv[2], argv[1]);

    else

    {

        printf("%s is successfully mounted at %s\n", argv[2], argv[1]);

        char lpszFileName[100] = "F:\\mymntpoint\\projectc\\doc\\Borland.doc";

        char lpszVolumePathName[100];

        DWORD cchBufferLength = 100;

        BOOL test = GetVolumePathName( lpszFileName, lpszVolumePathName, cchBufferLength);

        printf("The Volume path name for %s is:\n %s\n", lpszFileName, lpszVolumePathName);

    }

    return (bFlag);

}

A sample output:

G:\vcnetprojek\mymount\Debug>mymount

"mymount" command mounts a volume at a mount point.

Usage: mymount <mount point> <volume to be mounted>

And make sure the <mount point> exists!!!

Example: "mymount c:\mymnt\gdrive\ g:\"

G:\vcnetprojek\mymount\Debug>mymount F:\\mymntpoint\ I:\

Volume name of I:\ is \\?\Volume{a3446edb-ebd9-11d8-a25c-806d6172696f}\

I:\ is successfully mounted at F:\\mymntpoint\

The Volume path name for F:\mymntpoint\projectc\doc\Borland.doc is:

F:\mymntpoint\

G:\vcnetprojek\mymount\Debug>

As seen in Windows explorer, the F:\mymntpoint mount point is shown below.

Windows mount a directory

The snapshot, after I:\ volume was mounted at mount point F:\mymntpoint is shown below.

Windows directory has been mounted

The following Table lists the needed information in order to use the DeleteVolumeMountPoint() function.

Information	Description
The function	DeleteVolumeMountPoint().
The use	Unmounts the volume from the specified volume mount point.
The prototype	BOOL DeleteVolumeMountPoint( LPCTSTR lpszVolumeMountPoint );
Example	DeleteVolumeMountPoint(argv[1]);
The parameters	lpszVolumeMountPoint - [in] Pointer to a string that indicates the volume mount point to be unmounted. This may be a root directory such as X:\, in which case the DOS drive letter assignment is removed or a directory on a volume such as X:\mnt\. A trailing backslash is required.
The return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError().
The header file	<windows.h>
Table 12: DeleteVolumeMountPoint() information.

It is not an error to attempt to unmount a volume from a volume mount point when there is no volume actually mounted at that volume mount point.
The following program example demonstrates how to unmount a volume mounted at a volume mount point done by the previous program example using the DeleteVolumeMountPoint() function. This program was run at command prompt.

//*******myunmount.cpp***********

// change the path used in this program to yours

#define _WIN32_WINNT 0x0501

#include <windows.h>

#include <stdio.h>

int main(int argc, char *argv[])

{

BOOL bFlag;

// if the argument for the mount point is not given...

if(argc != 2)

{

printf("%s command unmounts a volume from the volume mount point.\n", argv[0]);

printf("Usage: \"%s <the_mount_point>\n", argv[0]);

printf("Example: \"%s c:\\mymnt\\gdrive\\\"\n", argv[0]);

// just exit

return (-1);

}

// do some verification, error checking...the argv[1] is a path of the volume mount point

bFlag = DeleteVolumeMountPoint(argv[1]);

if(!bFlag)

{

printf("Unmounting the volume at %s failed!\n", argv[1]);

exit(-1);

}

else

printf("Unmounting the volume at %s successfully done!\n", argv[1]);

return (bFlag);

}

A sample output:

G:\vcnetprojek\mymount\Debug>mymount F:\mymntpoint\ I:\

Volume name of I:\ is \\?\Volume{a3446edb-ebd9-11d8-a25c-806d6172696f}\

I:\ is successfully mounted at F:\mymntpoint\

The Volume path name for F:\mymntpoint\projectc\doc\Borland.doc is:

F:\mymntpoint\

G:\vcnetprojek\mymount\Debug>cd g:\vcnetprojek\myunmount\debug

G:\vcnetprojek\myunmount\Debug>myunmount

myunmount command unmounts a volume from the volume mount point.

Usage: "myunmount <the_mount_point>

Example: "myunmount c:\mymnt\gdrive\"

G:\vcnetprojek\myunmount\Debug>myunmount F:\mymntpoint\

Unmounting the volume at F:\mymntpoint\ successfully done!

G:\vcnetprojek\myunmount\Debug>

The following Table lists the needed information in order to use the GetVolumePathNamesForVolumeName() function.

Information	Description
The function	GetVolumePathNamesForVolumeName().
The use	Retrieves a list of path names for the specified volume name.
The prototype	BOOL GetVolumePathNamesForVolumeName( LPCTSTR lpszVolumeName, LPTSTR lpszVolumePathNames, DWORD cchBufferLength, PDWORD lpcchReturnLength);
The parameters	lpszVolumeName - [in] Pointer to a string that specifies the volume name. lpszVolumePathNames - [out] Pointer to a buffer that receives the list of volume path names. The list is an array of null-terminated strings terminated by an additional NULL character. If the buffer is not large enough to hold the complete list, the buffer holds as much of the list as possible. cchBufferLength - [in] Length of the lpszVolumePathNames buffer, in TCHARs. lpcchReturnLength - [out] If the call is successful, this parameter is the number of TCHARs copied to the lpszVolumePathNames buffer. Otherwise, this parameter is the size of the buffer required to hold the complete list, in TCHARs.
The return value	If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). If the buffer is not large enough to hold the complete list, the error code is ERROR_MORE_DATA and the lpcchReturnLength parameter receives the required buffer size.
The header file	<windows.h>
Table 13: GetVolumePathNamesForVolumeName() information.

--------------------------------------------------Summary------------------------------------------------------

Windows Volume Management Functions

The following Tables are the lists of the functions for volume management and control codes, structures and enumerations used for file management. If you think you already familiar and knew how to program using those APIs, then I pass the baton to you!

The following functions are used in volume management.

Function	Description
DefineDosDevice()	Defines, redefines, or deletes MS-DOS device names.
GetDriveType()	Determines whether a disk drive is a removable, fixed, CD-ROM, RAM disk, or network drive.
GetLogicalDrives()	Returns a bitmask representing the currently available disk drives.
GetLogicalDriveStrings()	Fills a buffer with strings that specify valid drives in the system.
GetVolumeInformation()	Retrieves information about a file system and volume.
QueryDosDevice()	Retrieves information about MS-DOS device names.
SetVolumeLabel()	Sets the label of a file system volume.

The following functions are used with volume mount points.

Function	Description
DeleteVolumeMountPoint()	Unmounts the volume from the specified volume mount point.
FindFirstVolume()	Returns the name of a volume on a computer.
FindFirstVolumeMountPoint()	Returns the name of a volume mount point on the specified volume.
FindNextVolume()	Continues a volume search started by a call to FindFirstVolume().
FindNextVolumeMountPoint()	Continues a volume mount point search started by a call to FindFirstVolumeMountPoint().
FindVolumeClose()	Closes the specified volume search handle.
FindVolumeMountPointClose()	Closes the specified mount-point search handle.
GetVolumeNameForVolumeMountPoint()	Takes a volume mount point or root directory and returns the corresponding unique volume name.
GetVolumePathName()	Retrieves the volume mount point at which the specified path is mounted.
GetVolumePathNamesForVolumeName()	Retrieves a list of path names for the specified volume name.
SetVolumeMountPoint()	Mounts the specified volume at the specified volume mount point.

Windows File Management

Windows File Management Functions

The following functions are used in file management.

Function	Description
AreFileApisANSI()	Determines whether the file I/O functions are using the ANSI or OEM character set code page.
CheckNameLegalDOS8Dot3()	Determines whether the specified name can be used to create a file on the FAT file system.
CloseHandle()	Closes an open object handle.
CopyFile()	Copies an existing file to a new file.
CopyFileEx()	Copies an existing file to a new file.
CopyProgressRoutine()	An application-defined callback function used with CopyFileEx() and MoveFileWithProgress().
CreateFile()	Creates or opens a file system object.
CreateHardLink()	Establishes an NTFS hard link between an existing file and a new file.
DeleteFile()	Deletes an existing file.
FindClose()	Closes the specified search handle.
FindFirstFile()	Searches a directory for a file whose name matches the specified file name.
FindFirstFileEx()	Searches a directory for a file whose name and attributes match those specified.
FindFirstStreamW()	Enumerates the first stream in the specified file.
FindNextFile()	Continues a file search.
FindNextStreamW()	Continues a stream search.
GetBinaryType()	Determines whether a file is executable.
GetCompressedFileSize()	Retrieves the actual number of bytes of disk storage used to store a specified file.
GetFileAttributes()	Retrieves attributes for a specified file or directory.
GetFileAttributesEx()	Retrieves attributes for a specified file or directory.
GetFileInformationByHandle()	Retrieves file information for a specified file.
GetFileSize()	Retrieves the size of a specified file.
GetFileSizeEx()	Retrieves the size of a specified file.
GetFileTime()	Retrieves the date and time that a file was created, last accessed, and last modified.
GetFileType()	Retrieves the file type of the specified file.
GetFullPathName()	Retrieves the full path and file name of a specified file.
GetLongPathName()	Converts the specified path to its long form.
GetShortPathName()	Retrieves the short path form of a specified input path.
GetTempFileName()	Creates a name for a temporary file.
GetTempPath()	Retrieves the path of the directory designated for temporary files.
MoveFile()	Moves an existing file or a directory.
MoveFileEx()	Moves an existing file or a directory.
MoveFileWithProgress()	Moves a file or directory.
ReOpenFile()	Reopens the specified file system object with different access rights, sharing mode, and flags.
ReplaceFile()	Replaces one file with another file.
SearchPath()	Searches for the specified file.
SetFileApisToANSI()	Causes the file I/O functions to use the ANSI character set code page.
SetFileApisToOE

|< C & Win32 programming 7 | Main | ANSI, Multibyte, Unicode and Localization 1 >| Site Index | Download |

MODULE F1

WIN32 AND C PROGRAMMING 8

What are in this Module?

Mounting And Unmounting Volume

Program Examples

Volume Management Functions

File Management: File Management Functions

File Management Control Codes

File Management Structures

File Management Enumeration Types

Abilities that supposed to be acquired:

Be familiar and play around with the Win32 programming.

Able to find and collect information about volume management functions.

Able to understand and use the collected information about the functions in programs.

Mounting And Unmounting Volume

Windows Volume Management Functions

DefineDosDevice()

GetDriveType()

GetLogicalDrives()

GetLogicalDriveStrings()

GetVolumeInformation()

QueryDosDevice()

SetVolumeLabel()

DeleteVolumeMountPoint()

FindFirstVolume()

FindFirstVolumeMountPoint()

FindNextVolume()

FindNextVolumeMountPoint()

FindVolumeClose()

FindVolumeMountPointClose()

GetVolumeNameForVolumeMountPoint()

GetVolumePathName()

GetVolumePathNamesForVolumeName()

SetVolumeMountPoint()

Windows File Management

Windows File Management Functions

AreFileApisANSI()

CheckNameLegalDOS8Dot3()

CloseHandle()

CopyFile()

CopyFileEx()

CopyProgressRoutine()

CreateFile()

CreateHardLink()

DeleteFile()

FindClose()

FindFirstFile()

FindFirstFileEx()

FindFirstStreamW()

FindNextFile()

FindNextStreamW()

GetBinaryType()

GetCompressedFileSize()

GetFileAttributes()

GetFileAttributesEx()

GetFileInformationByHandle()

GetFileSize()

GetFileSizeEx()

GetFileTime()

GetFileType()

GetFullPathName()

GetLongPathName()

GetShortPathName()

GetTempFileName()

GetTempPath()

MoveFile()

MoveFileEx()

MoveFileWithProgress()

ReOpenFile()

ReplaceFile()

SearchPath()

SetFileApisToANSI()

SetFileApisToOE