Z Directory reference manual ("man" pages)

class ref name: baredisk
category-group: files
layer: 2
header file: z_baredisk.h

synopsis.
The baredisk object is related to the barecomputer object (in the os group). It can be used to get information about a hard disk drive attached to the computer. This object can also qualify to be in the "os" group", but since files and disks are intimately related, here it is. To use this object, follow these simple steps:

create a baredisk_o instance.
set the "drive specifier", to ID which disk it is.
call member function sync().
get the desired information by calling the appropriate "info" member function.

Example:

#include "z_baredisk.h"
#include 
int main()
{
    baredisk_o dx;
    dx.set_drive_specifier("C:");
    dx.sync();
    std::cout << "VSN is: " << dx.serial_number() << std::endl;
}

A special function, root_config(), has been created which seeks out the primary hard disk (in Microsoft-land, this is almost always but not necessarily "C:"), and automatically configures the object as such. Thus you need not specify the drive prior to the sync(). This function call also does the sync():

    baredisk_o dx;
    dx.root_config();

description.
This object was originally built only because a hard drive's VSN was needed. The object closely parallels "barecomputer" and is meant to work closely with it. The object is intended to model, or parallel an existing hard drive. The core function is sync() - after the object is synced with a hard drive, you can get various summary information about it, such as its name, ID, and type.

You can put the object into "auto-sync" mode by calling set_autosync(). Once this is done, any request for information from the object will prompt it to call sync() if it has not already been done. The error return codes from sync() are percolated thru these "getter" functions, which include: exists(), serial_number(), name(), category(), file_system(),, and max_namelen().

member functions (primary)

baredisk_o()
SIGNATURE: baredisk_o ()
SYNOPSIS: creates a a new baredisk object, completely devoid of contents.

baredisk_o(baredisk_o)
SIGNATURE: baredisk_o (const baredisk_o &that)
SYNOPSIS: creates a a new baredisk object; an exact image of the copied baredisk object 'that'.

operator = (baredisk_o)
SIGNATURE: const baredisk_o &operator = (const baredisk_o &rhs)
SYNOPSIS:
copies exactly the RHS [Right Hand Side] object 'rhs'. The resultant baredisk instance is the same as if the copy constructor was used.

destructor
SIGNATURE: ~baredisk_o ()
SYNOPSIS:
Virtual destructor. The instance is wiped out - all internal information is reset to empty. State of the object becomes "not synced".

baredisk_o(<args>)
SIGNATURE: baredisk_o (const string_o &s)
SYNOPSIS: This function creates a new baredisk object and sets the baredisk's drive specifier to that of 's'.

assignment operator()
SIGNATURE: const baredisk_o &operator = (const string_o &s)
SYNOPSIS:
set an existing instance of a baredisk object to the drive specified by "s". If 's' reflects a change in the current drive (either first-time set, or a different drive), the existing data (if any) will be reset to empty and all data will be lost. If 's' is the same as the current drive, no internal changes will occur (a no-op).
RETURNS: a reference to the current object.

exists()
SIGNATURE: boolean exists (int *pi = NULL) const
SYNOPSIS:
informs the application if the current underlying disk really exists. The disk drive specifier should have been set prior (otherwise, it will default to a degenerate "", which does not exist).
PARAMETERS
pi: [output] error indicator variable. Values:
0: the disk specified by the object exists, and is a normal, readable disk drive.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)
RETURNS:
TRUE: the disk specified in the object is real
FALSE: otherwise; or, object was not properly initialized (see value of 'pi')

is_synced()
SIGNATURE: boolean is_synced (int *pi = NULL) const
SYNOPSIS:
informs the application if the current baredisk object has been synced with the disk it is named as (ie, whether or not sync() has been called earlier).
RETURNS:
TRUE: the object has been synced with the disk
FALSE: the object has not been synced with the disk

is_nameset()
SIGNATURE: boolean is_nameset (int *pi = NULL) const
SYNOPSIS:
Informs the application if the current baredisk object has been assigned a drive specifier (ie, whether or not set_drive_specifier() has been called earlier).
RETURNS:
TRUE: the object has been 'named' - drive specifier has been set.
FALSE: the object has not been named.

name()
SIGNATURE: string_o name (int *pi = NULL) const
SYNOPSIS:
returns the name of the disk drive. This function is geared for Microsoft platforms, where you can assign a name to a disk or partition.
PARAMETERS
pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values:
0: the information from the disk has been obtained, and the name has been successfully returned.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)

category()
SIGNATURE: string_o category (int *pi = NULL) const
SYNOPSIS:
returns a string describing the type of disk it is. To avoid operating-system dependencies and arguments with disk drive manufacturers, the information is simply put into a string. The current list of possible values is:
  UNKNOWN
  [NO ROOT]
  REMOVABLE
  FIXED
  REMOTE
  CD-ROM
  RAMDISK
PARAMETERS
pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values:
0: the information from the disk has been obtained, and the category [string] has been returned.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)

file_system()
SIGNATURE: string_o file_system (int *pi = NULL) const
SYNOPSIS: returns a string describing the file system of the underlying hard disk.
PARAMETERS
pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values:
0: the information from the disk has been obtained, and the file system [string] has been returned.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)

max_namelen()
SIGNATURE: int max_namelen (int *pi = NULL) const
SYNOPSIS: returns the maximum number of characters a file name entry (in unix terminology, the inode name) can have.
PARAMETERS
pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values:
0: the information from the disk has been obtained, and the file system [string] has been returned.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)

serial_number()
SIGNATURE: string_o serial_number (int *pi = NULL) const
SYNOPSIS:
Returns the disk's serial number. In Microsoft environments, this is called the Volume Serial Number, or VSN (generated by a simple hash algorithm based on when the partition was formatted).
The baredisk object must have been synchronized with its corresponding hard drive via a previous sync() call in order for this function to successfully return the desired item. This function will automatically call sync() if in "auto-sync" mode.
PARAMETERS
pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values:
0: the information from the disk has been obtained, and the serial number has been returned.
1: the disk specified by the object does not exist
zErr_NotInitialized: drive specification not set
zErr_NotConfigured: object not synced (auto-sync is OFF)

isset_autosync()
SIGNATURE: boolean isset_autosync () const
SYNOPSIS: Tells if the application has set the object into "auto-sync" mode.
TRAITS: this is a simple, inlined "getter" function.

root_drivespec()
SIGNATURE: string_o root_drivespec (int *pi = NULL, string_o *pse = NULL)
SYNOPSIS:
returns a 1-character string (a drive designator) identifying the primary drive. In Microsoft environments, the following environment variables are inspected to determine this:
SystemDrive
HOMEDRIVE
SystemRoot
windir
ComSpec
ProgramFiles
The output of this can be fed directly into set_drive_specifier:
baredisk_o bd;
bd.set_drive_specifier(root_drivespec());
Note that the above code is equivalent to (and superceded by) a call to root_config().
TRAITS: this is a static function. Do not attach this function to an actual object-instance.

set_drive_specifier()
SIGNATURE: int set_drive_specifier (const string_o &s, int *pi = NULL)
SYNOPSIS: sets the "identifier" for the baredisk object.
PARAMETERS

s: string describing the disk drive. On Microsoft environments, this should be the drive letter. 's' should contain only a single upper-case letter (no ':' or back-slashes).
In linux environments, this must be a mount point (which can be obtained using the getmntent() libc library call). The string must match the value of struct mntent.mnt_dir field (case is irrelevant, though). Mount points can also be found in the [text] file /etc/mtab.

pi: [output] error indicator variable. Values:
0: all ok, drive set
zErr_NotInitialized: empty string provided
zErr_DataBadFormat: string not valid
zErr_DonePrior: new value same as old value (this is informational only - does not mean an error)

set_autosync()
SIGNATURE: int set_autosync (boolean onoff = TRUE)
SYNOPSIS: allows doing auto-sync. sync() will be called automatically when it is required.
TRAITS: this is a simple, inlined setter function.

root_config()
SIGNATURE: int root_config (int *pi = NULL)
SYNOPSIS:
This sets the object to the "root" drive. It is a simple and powerful function. It is equivalent to doing the following:
baredisk_o bd;
string_o sroot = root_drivespec();
bd.set_drive_specifier(sroot);
bd.sync();
PARAMETERS
pi: [output] error indicator variable. The possible values of this variable include those of root_drivespec(), set_drive_specifier(sroot), and sync().
RETURNS:
0: all ok; object set and synced
-1: error occured (see value of pi)

sync()
SIGNATURE: int sync (int *pi = NULL)
SYNOPSIS:
"syncing" a baredisk means synching the internal data members of the object instance with what's actually there. After synchronization with the actual disk, the object's internal data will be set.
RETURNS:
0: all ok; did the sync
1: the disk is not valid
-1: an error occured (see value of 'pi')

reset()
SIGNATURE: int reset (VOID)
SYNOPSIS:
sets the baredisk object instance to its at-construction state: all internal lists (subdirectories and files) are set to empty, and the auto-refresh flag is set to its default value (TRUE).
RETURNS: 0

clone()
SIGNATURE: baredisk_o *clone () const
SYNOPSIS: creates a new instance of a baredisk object, which is a clone of the current object.

note.
About the spelling of "disk" vs. "disc": from http://support.apple.com/kb/HT2300, we have:
Discs
A disc refers to optical media, such as an audio CD, CD-ROM, DVD-ROM, or DVD-Video disc.. all discs are removable, meaning when you unmount or eject the disc, it physically comes out of your computer.
Disks
A disk refers to magnetic media, such as a floppy disk, the disk in your computer's hard drive, an external hard drive. Disks are rewritable unless intentionally locked or write-protected. You can easily partition a disk into several smaller volumes, too. Disks are usually sealed inside a metal or plastic casing (often, a disk and its enclosing mechanism are collectively known as a "hard drive").

history: Tue 08/28/2012: this class started, created, and implemented (1 day)

Vettrasoft Z Directory > tech support > reference > baredisk (files group)
ref home support home samples contact
	class ref name: baredisk category-group: files layer: 2 header file: z_baredisk.h synopsis. The baredisk object is related to the barecomputer object (in the os group). It can be used to get information about a hard disk drive attached to the computer. This object can also qualify to be in the "os" group", but since files and disks are intimately related, here it is. To use this object, follow these simple steps: create a baredisk_o instance. set the "drive specifier", to ID which disk it is. call member function sync(). get the desired information by calling the appropriate "info" member function. Example: #include "z_baredisk.h" #include int main() { baredisk_o dx; dx.set_drive_specifier("C:"); dx.sync(); std::cout << "VSN is: " << dx.serial_number() << std::endl; } A special function, root_config(), has been created which seeks out the primary hard disk (in Microsoft-land, this is almost always but not necessarily "C:"), and automatically configures the object as such. Thus you need not specify the drive prior to the sync(). This function call also does the sync(): baredisk_o dx; dx.root_config(); description. This object was originally built only because a hard drive's VSN was needed. The object closely parallels "barecomputer" and is meant to work closely with it. The object is intended to model, or parallel an existing hard drive. The core function is sync() - after the object is synced with a hard drive, you can get various summary information about it, such as its name, ID, and type. You can put the object into "auto-sync" mode by calling set_autosync(). Once this is done, any request for information from the object will prompt it to call sync() if it has not already been done. The error return codes from sync() are percolated thru these "getter" functions, which include: exists(), serial_number(), name(), category(), file_system(),, and max_namelen(). member functions (primary) baredisk_o() SIGNATURE: baredisk_o () SYNOPSIS: creates a a new baredisk object, completely devoid of contents. baredisk_o(baredisk_o) SIGNATURE: baredisk_o (const baredisk_o &that) SYNOPSIS: creates a a new baredisk object; an exact image of the copied baredisk object 'that'. operator = (baredisk_o) SIGNATURE: const baredisk_o &operator = (const baredisk_o &rhs) SYNOPSIS: copies exactly the RHS [Right Hand Side] object 'rhs'. The resultant baredisk instance is the same as if the copy constructor was used. destructor SIGNATURE: ~baredisk_o () SYNOPSIS: Virtual destructor. The instance is wiped out - all internal information is reset to empty. State of the object becomes "not synced". baredisk_o(<args>) SIGNATURE: baredisk_o (const string_o &s) SYNOPSIS: This function creates a new baredisk object and sets the baredisk's drive specifier to that of 's'. assignment operator() SIGNATURE: const baredisk_o &operator = (const string_o &s) SYNOPSIS: set an existing instance of a baredisk object to the drive specified by "s". If 's' reflects a change in the current drive (either first-time set, or a different drive), the existing data (if any) will be reset to empty and all data will be lost. If 's' is the same as the current drive, no internal changes will occur (a no-op). RETURNS: a reference to the current object. exists() SIGNATURE: boolean exists (int pi = NULL) const SYNOPSIS: informs the application if the current underlying disk really exists. The disk drive specifier should have been set prior (otherwise, it will default to a degenerate "", which does not exist). PARAMETERS pi: [output] error indicator variable. Values: 0: the disk specified by the object exists, and is a normal, readable disk drive. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) RETURNS: TRUE: the disk specified in the object is real FALSE: otherwise; or, object was not properly initialized (see value of 'pi') is_synced()* SIGNATURE: boolean is_synced (int pi = NULL) const SYNOPSIS: informs the application if the current baredisk object has been synced with the disk it is named as (ie, whether or not sync()* has been called earlier). RETURNS: TRUE: the object has been synced with the disk FALSE: the object has not been synced with the disk is_nameset() SIGNATURE: boolean is_nameset (int pi = NULL) const SYNOPSIS: Informs the application if the current baredisk object has been assigned a drive specifier (ie, whether or not set_drive_specifier()* has been called earlier). RETURNS: TRUE: the object has been 'named' - drive specifier has been set. FALSE: the object has not been named. name() SIGNATURE: string_o name (int pi = NULL) const SYNOPSIS: returns the name of the disk drive. This function is geared for Microsoft platforms, where you can assign a name to a disk or partition. PARAMETERS pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync()* (if called). Additional Values: 0: the information from the disk has been obtained, and the name has been successfully returned. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) category() SIGNATURE: string_o category (int pi = NULL) const SYNOPSIS: returns a string describing the type of disk it is. To avoid operating-system dependencies and arguments with disk drive manufacturers, the information is simply put into a string. The current list of possible values is: UNKNOWN [NO ROOT] REMOVABLE FIXED REMOTE CD-ROM RAMDISK PARAMETERS pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync()* (if called). Additional Values: 0: the information from the disk has been obtained, and the category [string] has been returned. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) file_system() SIGNATURE: string_o file_system (int pi = NULL) const SYNOPSIS: returns a string describing the file system of the underlying hard disk. PARAMETERS pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync()* (if called). Additional Values: 0: the information from the disk has been obtained, and the file system [string] has been returned. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) max_namelen() SIGNATURE: int max_namelen (int pi = NULL) const SYNOPSIS: returns the maximum number of characters a file name entry (in unix terminology, the inode name) can have. PARAMETERS pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync()* (if called). Additional Values: 0: the information from the disk has been obtained, and the file system [string] has been returned. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) serial_number() SIGNATURE: string_o serial_number (int pi = NULL) const SYNOPSIS: Returns the disk's serial number. In Microsoft environments, this is called the Volume Serial Number, or VSN (generated by a simple hash algorithm based on when the partition was formatted). The baredisk object must have been synchronized with its corresponding hard drive via a previous sync()* call in order for this function to successfully return the desired item. This function will automatically call sync() if in "auto-sync" mode. PARAMETERS pi: [output] error indicator variable. If the object is in "auto-sync" mode, the possible values of this variable include those of sync() (if called). Additional Values: 0: the information from the disk has been obtained, and the serial number has been returned. 1: the disk specified by the object does not exist zErr_NotInitialized: drive specification not set zErr_NotConfigured: object not synced (auto-sync is OFF) isset_autosync() SIGNATURE: boolean isset_autosync () const SYNOPSIS: Tells if the application has set the object into "auto-sync" mode. TRAITS: this is a simple, inlined "getter" function. root_drivespec() SIGNATURE: string_o root_drivespec (int pi = NULL, string_o pse = NULL) SYNOPSIS: returns a 1-character string (a drive designator) identifying the primary drive. In Microsoft environments, the following environment variables are inspected to determine this: SystemDrive HOMEDRIVE SystemRoot windir ComSpec ProgramFiles The output of this can be fed directly into set_drive_specifier: baredisk_o bd; bd.set_drive_specifier(root_drivespec()); Note that the above code is equivalent to (and superceded by) a call to root_config(). TRAITS: this is a static function. Do not attach this function to an actual object-instance. set_drive_specifier() SIGNATURE: int set_drive_specifier (const string_o &s, int pi = NULL) SYNOPSIS: sets the "identifier" for the baredisk object. PARAMETERS s: string describing the disk drive. On Microsoft environments, this should be the drive letter. 's' should contain only a single upper-case letter (no ':' or back-slashes). In linux environments, this must be a mount point (which can be obtained using the getmntent()* libc library call). The string must match the value of struct mntent.mnt_dir field (case is irrelevant, though). Mount points can also be found in the [text] file /etc/mtab. pi: [output] error indicator variable. Values: 0: all ok, drive set zErr_NotInitialized: empty string provided zErr_DataBadFormat: string not valid zErr_DonePrior: new value same as old value (this is informational only - does not mean an error) set_autosync() SIGNATURE: int set_autosync (boolean onoff = TRUE) SYNOPSIS: allows doing auto-sync. sync() will be called automatically when it is required. TRAITS: this is a simple, inlined setter function. root_config() SIGNATURE: int root_config (int pi = NULL) SYNOPSIS: This sets the object to the "root" drive. It is a simple and powerful function. It is equivalent to doing the following: baredisk_o bd; string_o sroot = root_drivespec(); bd.set_drive_specifier(sroot); bd.sync(); PARAMETERS pi: [output] error indicator variable. The possible values of this variable include those of root_drivespec(), set_drive_specifier(sroot), and sync(). RETURNS: 0: all ok; object set and synced -1: error occured (see value of pi) sync()* SIGNATURE: int sync (int pi = NULL) SYNOPSIS: "syncing" a baredisk means synching the internal data members of the object instance with what's actually there. After synchronization with the actual disk, the object's internal data will be set. RETURNS: 0: all ok; did the sync 1: the disk is not valid -1: an error occured (see value of 'pi') reset()* SIGNATURE: int reset (VOID) SYNOPSIS: sets the baredisk object instance to its at-construction state: all internal lists (subdirectories and files) are set to empty, and the auto-refresh flag is set to its default value (TRUE). RETURNS: 0 clone() SIGNATURE: baredisk_o clone () const SYNOPSIS: creates a new instance of a baredisk object, which is a clone of the current object. note.* About the spelling of "disk" vs. "disc": from http://support.apple.com/kb/HT2300, we have: Discs A disc refers to optical media, such as an audio CD, CD-ROM, DVD-ROM, or DVD-Video disc.. all discs are removable, meaning when you unmount or eject the disc, it physically comes out of your computer. Disks A disk refers to magnetic media, such as a floppy disk, the disk in your computer's hard drive, an external hard drive. Disks are rewritable unless intentionally locked or write-protected. You can easily partition a disk into several smaller volumes, too. Disks are usually sealed inside a metal or plastic casing (often, a disk and its enclosing mechanism are collectively known as a "hard drive"). history: Tue 08/28/2012: this class started, created, and implemented (1 day)
home \|\| support \|\| FAQ \|\| get Z Dir \|\| contact us Copyright 2010 Vettrasoft Corporation - All Rights Reserved