==============================
JF Software VB Modules
By Joshua Foster - JF Software
http://www.jfsoftware.net
jfsoftware@jfsoftware.net
July 29, 2001
==============================
CDDrive class module
====================
Description: Controls any CD-ROM drive.


Procedures:
===========
---------
OpenDrive
---------
Syntax:       OpenDrive(strCDDrive As String, strAliasName As String) As Boolean
Description:  Opens a CD drive for use by the program.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strCDDrive   - The drive letter of the CD drive (E, E:, or E:\)
              strAliasName - The alias to give to the CD drive (you will use this alias to refer to the CD drive in the other
                             functions)

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.OpenDrive("E","mydrive")  'MsgBox whether or not the E: drive was opened as "mydrive"
End Sub


---------
CloseDoor
---------
Syntax:       CloseDoor(strAliasName As String) As Boolean
Description:  Closes the CD drive's door.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.CloseDoor("mydrive")  'Closes the door on the "mydrive" drive
End Sub


-------------
GetArtistName
-------------
Syntax:       GetArtistName(strCDDrive As String) As String
Description:  Reads the CD's artist (from the CD Player file).
Return Value: Returns the artist if successful, the CD's serial number if the CD wasn't found, or a blank string if an error
              occured.
Parameters:   strCDDrive - The drive letter of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetArtistName("E")  'MsgBox the CD's artist
End Sub


-----------------------
GetCurrentMinuteInTrack
-----------------------
Syntax:       GetCurrentMinuteInTrack(strAliasName As String) As Long
Description:  Reads the current track's minute counter.
Return Value: Returns the current minute in-track if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetCurrentMinuteInTrack("mydrive")  'MsgBox the CD's current minute in-track
End Sub


-----------------------
GetCurrentSecondInTrack
-----------------------
Syntax:       GetCurrentSecondInTrack(strAliasName As String) As Long
Description:  Reads the current track's second counter.
Return Value: Returns the current second in-track if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetCurrentSecondInTrack("mydrive")  'MsgBox the CD's current second in-track
End Sub


---------------------
GetCurrentMinuteTotal
---------------------
Syntax:       GetCurrentMinuteTotal(strAliasName As String) As Long
Description:  Reads the entire CD's minute counter.
Return Value: Returns the current minute if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetCurrentMinuteTotal("mydrive")  'MsgBox the CD's current minute
End Sub


---------------------
GetCurrentSecondTotal
---------------------
Syntax:       GetCurrentSecondTotal(strAliasName As String) As Long
Description:  Reads the entire CD's second counter.
Return Value: Returns the current second if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetCurrentSecondTotal("mydrive")  'MsgBox the CD's current second
End Sub


---------------
GetCurrentTrack
---------------
Syntax:       GetCurrentTrack(strAliasName As String) As Long
Description:  Reads the CD's current track.
Return Value: Returns the current track if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetCurrentTrack("mydrive")  'MsgBox the CD's current track
End Sub


---------------
GetNumberTracks
---------------
Syntax:       GetNumberTracks(strAliasName As String) As Long
Description:  Reads the total number of tracks on the CD.
Return Value: Returns the number of tracks if successful, -1 if an error occured
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetNumberTracks("mydrive")  'MsgBox the CD's track count
End Sub


----------------------
GetStartOfTrackMinutes
----------------------
Syntax:       GetStartOfTrackMinutes(strAliasName As String, lngTrackNum As Long) As Long
Description:  Reads the starting minute position of a track.
Return Value: Returns the starting minute position of the track if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              lngTrackNum  - The number of the track.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetStartOfTrackMinutes("mydrive",1)  'MsgBox the starting minute of track #1
End Sub


----------------------
GetStartOfTrackSeconds
----------------------
Syntax:       GetStartOfTrackSeconds(strAliasName As String, lngTrackNum As Long) As Long
Description:  Reads the starting second position of a track.
Return Value: Returns the starting second position of the track if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              lngTrackNum  - The number of the track.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetStartOfTrackMinutes("mydrive",1)  'MsgBox the starting second of track #1
End Sub


------------
GetTitleName
------------
Syntax:       GetTitleName(strCDDrive As String) As String
Description:  Reads the CD's title (from the CD Player file).
Return Value: Returns the title if successful, the CD's serial number if the CD wasn't found, or a blank string if an error
              occured.
Parameters:   strCDDrive - The drive letter of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetTitleName("E")  'MsgBox the CD's title
End Sub


--------------
GetTotalLength
--------------
Syntax:       GetTotalLength(strAliasName As String) As Long
Description:  Reads the length of the entire CD.
Return Value: Returns the CD's length if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetTotalLength("mydrive")  'MsgBox the length of the CD
End Sub


--------------
GetTrackLength
--------------
Syntax:       GetTrackLength(strAliasName As String, lngTrackNum As Long) As Long
Description:  Reads the length of a track.
Return Value: Returns the track's length if successful, -1 if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              lngTrackNum  - The number of the track.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetTrackLength("mydrive",1)  'MsgBox the length of track #1
End Sub


------------
GetTrackName
------------
Syntax:       GetTrackName(strCDDrive As String, lngTrackNum As Long) As String
Description:  Reads a track's title (from the CD Player file).
Return Value: Returns the track name if successful, the CD's serial number if the CD wasn't found, or a blank string if an
              error occured.
Parameters:   strCDDrive - The drive letter of the CD drive.
              lngTrackNum  - The number of the track.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.GetTrackName("E",1)  'MsgBox the title of track #1
End Sub


--------------
IsMediaInDrive
--------------
Syntax:       IsMediaInDrive(strAliasName As String) As Boolean
Description:  Determines if a readable CD is in the CD drive.
Return Value: Returns true if a CD is found, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.IsMediaInDrive("mydrive")  'MsgBox if a CD's in "mydrive"
End Sub


--------
IsPaused
--------
Syntax:       IsPaused(strAliasName As String) As Boolean
Description:  Determines if the CD is paused.
Return Value: Returns true if the CD is paused, false if the CD is not paused or an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.IsPaused("mydrive")  'MsgBox if the CD is paused
End Sub


---------
IsPlaying
---------
Syntax:       IsPlaying(strAliasName As String) As Boolean
Description:  Determines if the CD is playing.
Return Value: Returns true if the CD is playing, false if the CD is not playing or an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.IsPlaying("mydrive")  'MsgBox if the CD is playing
End Sub


---------
IsStopped
---------
Syntax:       IsStopped(strAliasName As String) As Boolean
Description:  Determines if the CD is stopped.
Return Value: Returns true if the CD is stopped, false if the CD is not stopped or an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.IsStopped("mydrive")  'MsgBox if the CD is stopped
End Sub


-----------
LeftChannel
-----------
Syntax:       LeftChannel(strAliasName As String, blnStatus As Boolean) As Boolean
Description:  Turns the left audio channel on or off.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              blnStatus    - The status of the left channel (true=on, false=off)

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.LeftChannel("mydrive",False)  'Turns the left channel off
End Sub


----
Mute
----
Syntax:       Mute(strAliasName As String, blnStatus As Boolean) As Boolean
Description:  Turns the mute on or off.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              blnStatus    - The status of the mute (true=on/no sound, false=off/sound)

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.Mute("mydrive",True)  'Turns the mute on
End Sub


--------
OpenDoor
--------
Syntax:       OpenDoor(strAliasName As String) As Boolean
Description:  Opens the CD drive's door.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.OpenDoor("mydrive")  'Opens the door on the "mydrive" drive
End Sub


-------
PauseCD
-------
Syntax:       PauseCD(strAliasName As String) As Boolean
Description:  Pauses the CD playback.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.PauseCD("mydrive")  'Pauses the CD playback
End Sub


------
PlayCD
------
Syntax:       PlayCD(strAliasName As String) As Boolean
Description:  Starts the CD playback.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.PlayCD("mydrive")  'Starts the CD playback
End Sub


------------
RightChannel
------------
Syntax:       RightChannel(strAliasName As String, blnStatus As Boolean) As Boolean
Description:  Turns the right audio channel on or off.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              blnStatus    - The status of the right channel (true=on, false=off)

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.RightChannel("mydrive",False)  'Turns the right channel off
End Sub


-------------
SetArtistName
-------------
Syntax:       SetArtistName(strCDDrive As String, strNewArtistName As String) As Boolean
Description:  Sets the CD's artist (in the CD Player file).
Return Value: Returns true if successful, false if an error occured.
Parameters:   strCDDrive       - The drive letter of the CD drive.
              strNewArtistName - The new artist for the CD.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.SetArtistName("E","Unknown Artist")  'Set the CD's artist to Unknown Artist
End Sub


------------------
SetCurrentPosition
------------------
Syntax:       SetCurrentPosition(strAliasName As String, [lngTrackNum As Long], [lngMinutes As Long], [lngSeconds As Long]) _
              As Boolean
Description:  Sets the current position on the CD.
Return Value: Returns the true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.
              lngTrackNum  - The track number to play (optional; if not specified, 1).
              lngMinutes   - The minutes position in-track to play (optional; if not specified, 0).
              lngSeconds   - The seconds position in-track to play (optional; if not specified, 0).

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.SetPosition("E")  'Set the CD to play at the beginning of the first track
End Sub


------------
SetTitleName
------------
Syntax:       SetTitleName(strCDDrive As String, strNewTitleName As String) As Boolean
Description:  Sets the CD's title (in the CD Player file).
Return Value: Returns true if successful, false if an error occured.
Parameters:   strCDDrive      - The drive letter of the CD drive.
              strNewTitleName - The new title for the CD.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.SetTitleName("E","Unknown Title")  'Set the CD's title to Unknown Title
End Sub


------------
SetTrackName
------------
Syntax:       SetTrackName(strCDDrive As String, lngTrackNum As Long, strNewTrackName As String) As String
Description:  Sets a track's title (in the CD Player file).
Return Value: Returns true if successful, false if an error occured.
Parameters:   strCDDrive      - The drive letter of the CD drive.
              lngTrackNum     - The number of the track.
              strNewTrackName - The new title for the track.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.SetTrackName("E",1,"Unknown Track")  'Set the title of track #1 to Unknown Track
End Sub


------
StopCD
------
Syntax:       StopCD(strAliasName As String) As Boolean
Description:  Stops the CD playback.
Return Value: Returns true if successful, false if an error occured.
Parameters:   strAliasName - The alias of the CD drive.

Example:
--------
Private cCDDrive As CDDrive  'Define a CDDrive object

Private Sub Form_Load()
Set cCDDrive = New CDDrive  'Load the cCDDrive object
MsgBox cCDDrive.StopCD("mydrive")  'Stops the CD playback
End Sub


----------
CloseDrive
----------
Syntax:       CloseDrive() As Boolean
Description:  Closes the CD drive.
Return Value: Returns true if successful, false if an error occured.

Example:
--------
'MsgBox whether or not the drive closed
MsgBox cCDDrive.CloseDrive
