| GEOS SDK TechDocs| | DiskForEach() ... | DiskSave() ...

---

DiskGetDrive()

word	DiskGetDrive(
        DiskHandle		dh);

This routine returns the drive number associated with a registered disk. Note that it will do this even if the drive is no longer usable (e.g. if a network drive has been unmapped).

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskFind(),DiskRegisterDisk().

Include: disk.h

DiskGetVolumeFreeSpace()

dword	DiskGetVolumeFreeSpace( 
        DiskHandle		dh);

This routine returns the amount of free space (measured in bytes) on the specified disk. If the disk is, by nature, not writable (e.g. a CD-ROM disk), DiskGetVolumeFreeSpace() returns zero and clears the thread's error value. If an error condition exists, DiskGetVolumeFreeSpace() returns zero and sets the thread's error value.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskGetVolumeInfo().

Include: disk.h

DiskGetVolumeInfo()

word	DiskGetVolumeInfo(  /* Returns 0 if successful */
        DiskHandle		dh,
        DiskInfoStruct		*info);			/* Routine fills this structure */

This routine returns general information about a disk. It returns the following four pieces of information:

• The size of each disk block in bytes. When space is allocated, it is rounded up to the nearest whole block.
• The number of free bytes on the disk.
• The total number of bytes on the disk; this is the total of free and used space.
• The disk's volume name. If the volume is unnamed, the current temporary name will be returned.

The information is written to the passed DiskInfoStruct . If an error condition occurs, DiskGetVolumeInfo() will return the error code and set the thread's error value; otherwise, it will return zero.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

Include: disk.h

DiskGetVolumeName()

void	DiskGetVolumeName(
        DiskHandle		dh,
        char *		buffer);			/* Must be VOLUME_NAME_LENGTH_ZT bytes
						 * long */

This routine copies the disk's volume name (as a null-terminated string) to the passed buffer. If an error occurs, it sets the thread's error value. If the volume has no name, the routine returns the current temporary name.

Warnings: DiskGetVolumeName() does not check the size of the buffer passed. If the buffer is not at least VOLUME_NAME_LENGTH_ZT bytes long, the routine may write beyond its boundaries.

Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.

See Also: DiskGetVolumeInfo(),DiskSetVolumeName().

DiskRegisterDisk()

DiskHandle 	DiskRegisterDisk(
        word	driveNumber); 

This routine registers a disk in the specified drive and assigns it a disk handle. (The disk handle persists only to the end of the current session of GEOS.) If the disk already has a handle, DiskRegisterDisk() will return it. If the disk does not have a name, GEOS will assign it a temporary name (such as "UNNAMED1") and display an alert box telling the user what the temporary name is. (This is done only the first time the disk is registered in each session.) Note that the temporary name is not written to the disk; thus, it persists only until the end of the current session of GEOS.

If this routine returns a disk handle, there's a disk in the drive; if it doesn't, there may still be a disk in the drive, but the disk is unformatted.

Tips and Tricks: There is no harm in registering the same disk several times. Thus, if you want to get the disk handle for the disk in a specific drive, you can simply call DiskRegisterDisk() .

See Also: DiskRegisterDiskSilently().

Include: disk.h

DiskRegisterDiskSilently()

DiskHandle 	DiskRegisterDiskSilently(
        word		driveNumber);

This routine is almost identical to DiskRegisterDisk() (described immediately above). There is only one difference: If GEOS assigns a temporary name to the disk, it will not present an alert box to the user.

See Also: DiskRegisterDisk().

Include: disk.h

DiskRestore()

DiskHandle 	DiskRestore(
        void *		buffer,			/* buffer written by DiskSave() */
        DiskRestoreError _pascal (*callback)	
			(const char 						*driveName,
			 const char 						*diskName,
			 void 						**bufferPtr,

        		 DiskRestoreError 						error);

DiskRestore() examines a buffer written by DiskSave() and returns the handle of the disk described by that buffer. If that disk is already registered, DiskRestore() will simply return its handle. If the disk is not registered and is not in the drive, DiskRestore() will call the specified callback routine. The callback routine should be declared _pascal. The callback routine is passed four arguments:

• A null-terminated string containing the name of the drive for the disk.
• A null-terminated string containing the disk's volume label.
• A pointer to a variable in the DiskRestore() routine. This variable is itself a pointer to the opaque data structure provided by DiskSave(). If the callback routine takes any action which causes that structure to move (e.g. if it causes the global or local heap containing the buffer to be shuffled), it should update the pointer in DiskRestore() .
• A member of the DiskRestoreError enumerated type. This is the error which DiskRestore() would have returned if there had not been a callback routine. This is usually DRE_REMOVABLE_DRIVE_DOESNT_HOLD_DISK.

The callback routine should prompt the user to insert a disk. If the callback routine was successful, it should return DRE_DISK_IN_DRIVE (which is guaranteed to be equal to zero). Otherwise, it should return a member of the DiskRestoreError enumerated type; usually it will return DRE_USER_CANCELLED_RESTORE. Note that the callback routine will not generally know if the user has inserted a disk; it generally just displays an alert box and returns when the user clicks "OK." After the callback routine returns, DiskRestore() registers the disk and makes sure that it's the correct one; if it is not, it calls the callback routine again.

You can pass a null function pointer to DiskRestore() instead of providing a callback routine. In this case, DiskRestore() will fail if the disk has not been registered and is not currently in the drive.

DiskRestore() returns the handle of the disk. If it fails for any reason, it returns a null handle and sets the thread's error value to a member of the DiskRestorenError enumerated type. This type has the following members:

DRE_DISK_IN_DRIVE

This is returned by the callback routine. This is guaranteed to equal zero.

DRE_DRIVE_NO_LONGER_EXISTS

The disk is associated with a drive which is no longer attached to the system.

DRE_REMOVABLE_DRIVE_DOESNT_CONTAIN_DISK

The disk is unregistered, and it is not currently in the drive associated with it. If a callback routine was provided, DiskRestore() will call it under these circumstances.

DRE_USER_CANCELLED_RESTORE

This is returned by the callback routine if the user cancels the restore.

DRE_COULDNT_CREATE_NEW_DISK_HANDLE

DiskRestore() was unable to register the disk in the appropriate drive because it couldn't create a new disk handle.

DRE_REMOVABLE_DRIVE_IS_BUSY

The appropriate drive is busy with a time-consuming operation (e.g. a disk format).

DRE_NOT_ATTACHED_TO_SERVER

The disk was from a network server to which we are not logged in.

DRE_PERMISSION_DENIED

The disk was on a network which is now denying access to it.

DRE_ALL_DRIVES_USED

The disk was on a network volume that isn't mounted, but there is no drive left to which it can be mapped.

See Also: DiskSave().

Include: disk.h