In Lesson 5 we learned how to pass a string variable "by reference" so that the API function can modify the contents. This is done by passing a memory pointer to the variable. Liberty BASIc has no type that allows us to pass a numeric variable "by reference."
Passing a Number by Reference
We can pass a numeric variable "by reference" by including it in a STRUCT and passing the STRUCT into the API call. A STRUCT, like a PTR is a pointer to a memory address.
Important Note
This article and the demonstration program are meant to explain passing numeric variables "by reference." The MCI API is used in the demonstration. MCI stands for Media Control Interface, a high-level API for controlling multimedia devices, such as CD-ROM players and audio controllers. This area of programming is complex and is not addressed in this simple tutorial. To learn more, visit the Microsoft Developers Network topic on MCI, here: http://msdn2.microsoft.com/en-us/library/ms704979.aspx
STRUCT with Numeric Member
We learned about STRUCTS in Lesson 6. We'll create a STRUCT with one numeric member. Since this member will contain a handle, it is type "ulong." See Lesson 3 for more information on handle types in API calls.
struct LPHMIDIOUT, handle asulong
Passing a STRUCT Argument
We don't need to assign a value to the handle member of the struct. It will be filled in the API call to midiOutOpen as shown below. The comments give a brief explanation of the API call.
struct LPHMIDIOUT, handle asulong
CallDLL #winmm, "midiOutOpen",_
LPHMIDIOUT As struct,_ 'Pointer to HMIDIOUT handle-1Asulong,_ 'device ID of MIDI_MAPPER0Asulong,_ 'callback address - not used0Asulong,_ 'callback instance - not used0Asulong,_ 'callback flags - not used
ret Aslong'returns 0 if successful
Retrieving a Number from a STRUCT
When the midiOutOpen function returns, the handle member of the LPHMIDIOUT STRUCT contains the handle of the MIDI device. We retrieve it like this:
hMidiOut = LPHMIDIOUT.handle.struct'handle to MIDI device
We've now assigned the value of the handle to the variable called hMidiOut. We'll use that variable any time we need to pass the MIDI device handle into an API call.
Demonstration Program
The following program retrieves the handle of the MIDI device from a STRUCT. It and uses this handle to play a note. Be sure the sound is not muted on your computer, so that you can hear the note.
struct LPHMIDIOUT, handle asulong
CallDLL #winmm, "midiOutOpen",_
LPHMIDIOUT As struct,_ 'Pointer to HMIDIOUT handle-1Asulong,_ 'device ID of MIDI_MAPPER0Asulong,_ 'callback address - not used0Asulong,_ 'callback instance - not used0Asulong,_ 'callback flags - not used
ret Aslong'returns 0 if successful
hMidiOut = LPHMIDIOUT.handle.struct'handle to MIDI device
PRINT "Handle of MIDI device is ";hMidiOut
'default instrument (voice) is Grand Piano'set up to play a MIDI note
note =60'for C. C# = 61, etc.event=144'event 144 = play on channel 1
loWord =(note*256)+event
velocity =127
hiWord = velocity*256*256
dwMsg = loWord + hiWord
'send message to the opened MIDI device
CallDLL #winmm, "midiOutShortMsg",_
hMidiOut Asulong,_ 'handle to MIDI device
dwMsg Asulong,_ 'message to play a note
ret Asulong'a three second timer'allows note to play for 3 seconds
TIMER 3000, [stopPlay]
wait
[stopPlay]'close MIDI device
CallDLL #winmm, "midiOutClose",_ 'close opened device
hMidiOut Asulong,_ 'handle of opened device
ret Asulong
print "Done"end
More?
The piano6.bas program that comes with Liberty BASIC has a simple interface for playing MIDI notes. You can use it as a starting point to learn more about using the MIDI mapper. The Microsoft Developers Network (MSDN) has all of the information you'll need. Start with midiOutOpen, here: http://msdn2.microsoft.com/en-us/library/ms711632.aspx
What's Next?
Lesson 8 will discuss the native Windows API features of Liberty BASIC.
Passing Numbers by Reference
Table of Contents
Passing a Number by Reference
We can pass a numeric variable "by reference" by including it in a STRUCT and passing the STRUCT into the API call. A STRUCT, like a PTR is a pointer to a memory address.Important Note
This article and the demonstration program are meant to explain passing numeric variables "by reference." The MCI API is used in the demonstration. MCI stands for Media Control Interface, a high-level API for controlling multimedia devices, such as CD-ROM players and audio controllers. This area of programming is complex and is not addressed in this simple tutorial. To learn more, visit the Microsoft Developers Network topic on MCI, here:http://msdn2.microsoft.com/en-us/library/ms704979.aspx
STRUCT with Numeric Member
We learned about STRUCTS in Lesson 6. We'll create a STRUCT with one numeric member. Since this member will contain a handle, it is type "ulong." See Lesson 3 for more information on handle types in API calls.Passing a STRUCT Argument
We don't need to assign a value to the handle member of the struct. It will be filled in the API call to midiOutOpen as shown below. The comments give a brief explanation of the API call.Retrieving a Number from a STRUCT
When the midiOutOpen function returns, the handle member of the LPHMIDIOUT STRUCT contains the handle of the MIDI device. We retrieve it like this:We've now assigned the value of the handle to the variable called hMidiOut. We'll use that variable any time we need to pass the MIDI device handle into an API call.
Demonstration Program
The following program retrieves the handle of the MIDI device from a STRUCT. It and uses this handle to play a note. Be sure the sound is not muted on your computer, so that you can hear the note.More?
The piano6.bas program that comes with Liberty BASIC has a simple interface for playing MIDI notes. You can use it as a starting point to learn more about using the MIDI mapper. The Microsoft Developers Network (MSDN) has all of the information you'll need. Start with midiOutOpen, here:http://msdn2.microsoft.com/en-us/library/ms711632.aspx
What's Next?
Lesson 8 will discuss the native Windows API features of Liberty BASIC.Written by Alyce Watson. For more on APIs, see:
APIs for Liberty BASIC