archive
/
windows-xp
mirror of https://github.com/tongzx/nt5src
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Source code of Windows XP (NT5)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
9 Commits
1 Branch
0 Tags
2.0 GiB
 
 
 
 
 
 
Tree: 75c48ba87f
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '75c48ba87f'
${ noResults }
windows-xp/Source/XPSP1/NT/multimedia/media/doc/mmapi32.ref

5324 lines
132 KiB
Raw Blame History

.refpage auxGetDevCaps
WORD %auxGetDevCaps%(<wDeviceID>, <lpCaps>, <wSize>)
This function queries a specified auxiliary output device to determine its
capabilities.
.parameters
WORD <wDeviceID>
Identifies the auxiliary output device to be queried.
LPAUXCAPS <lpCaps>
Specifies a far pointer to an AUXCAPS structure. This structure is
filled with information about the capabilities of the device.
WORD <wSize>
Specifies the size of the AUXCAPS structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver failed to install.
.endlist
.comments
Use %auxGetNumDevs% to determine the number of auxiliary output devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present.
.seealso
%auxGetNumDevs%
.refpage auxGetNumDevs
WORD %auxGetNumDevs%()
This function retrieves the number of auxiliary output devices present in
the system.
.parameters
None
.returns
Returns the number of auxiliary output devices present in the system.
.seealso
%auxGetDevCaps%
.refpage auxGetVolume
WORD %auxGetVolume%(<wDeviceID>, <lpdwVolume>)
This function returns the current volume setting of an auxiliary output
device.
.parameters
WORD <wDeviceID>
Identifies the auxiliary output device to be queried.
LPDWORD <lpdwVolume>
Specifies a far pointer to a location to be filled with the current
volume setting. The low-order word of this location contains the left
channel volume setting, and the high-order word contains the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of the specified location contains the volume level.
The full 16-bit setting(s) set with %auxSetVolume% are returned,
regardless of whether the device supports the full 16 bits of volume
level control.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver failed to install.
.endlist
.comments
Not all devices support volume control. To determine whether the device
supports volume control, use the AUXCAPS_VOLUME flag to test the %dwSupport%
field of the %AUXCAPS% structure (filled by %auxGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the AUXCAPS_LRVOLUME flag to test the %dwSupport% field
of the %AUXCAPS% structure (filled by %auxGetDevCaps%).
.seealso
%auxSetVolume%
.refpage auxSetVolume
WORD %auxSetVolume%(<wDeviceID>, <dwVolume>)
This function sets the volume in an auxiliary output device.
.parameters
WORD <wDeviceID>
Identifies the auxiliary output device to be queried. Device IDs are
determined implicitly from the number of devices present in the system.
Device ID values range from zero to one less than the number of devices
present. Use %auxGetNumDevs% to determine the number of auxiliary
devices in the system.
DWORD <dwVolume>
Specifies the new volume setting. The low-order word specifies the left
channel volume setting, and the high-order word specifies the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of <dwVolume> specifies the volume level, and the
high-order word is ignored.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver failed to install.
.endlist
.comments
Not all devices support volume control. To determine whether the device
supports volume control, use the AUXCAPS_VOLUME flag to test the %dwSupport%
field of the %AUXCAPS% structure (filled by %auxGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the AUXCAPS_LRVOLUME flag to test the %dwSupport% field
of the %AUXCAPS% structure (filled by %auxGetDevCaps%).
Most devices do not support the full 16 bits of volume level control and
will use only the high-order bits of the requested volume setting. For
example, for a device that supports 4 bits of volume control, requested
volume level values of 0x4000, 0x4fff, and 0x43be will all produce the same
physical volume setting, 0x4000. The %auxGetVolume% function will return the
full 16-bit setting set with %auxSetVolume%.
Volume settings are interpreted logarithmically. This means the perceived
volume increase is the same when increasing the volume level from 0x5000 to
0x6000 as it is from 0x4000 to 0x5000.
.seealso
%auxGetVolume%
.refpage mciExecute
BOOL %mciExecute%(<lpstrCommand>)
This function is a simplified version of the %mciSendString% function. It
does not take a buffer for return information, and it displays a message box
when errors occur.
.parameters
LPSTR <lpstrCommand>
Specifies an MCI command string.
.returns
TRUE if successful, FALSE if unsuccessful.
.comments
This function provides a simple interface to MCI from scripting languages.
.seealso
%mciSendString%
.refpage mciGetErrorString
WORD %mciGetErrorString%(<dwError>, <lpstrBuffer>, <wLength>)
This function returns a textual description of the specified MCI error.
.parameters
DWORD <dwError>
Specifies the error code returned by %mciSendCommand% or
%mciSendString%.
LPSTR <lpstrBuffer>
Specifies a pointer to a buffer that is filled with a textual
description of the specified error.
WORD <wLength>
Specifies the length of the buffer pointed to by <lpstrBuffer>.
.returns
Returns TRUE if successful. Otherwise, the given error code was not known.
.refpage mciSendCommand
DWORD %mciSendCommand%(<wDeviceID>, <wMessage>, <dwParam1>, <dwParam2>)
This function sends a command message to the specified MCI device.
.parameters
WORD <wDeviceID>
Specifies the device ID of the MCI device to receive the command. This
parameter is not used with the %MCI_OPEN% command.
WORD <wMessage>
Specifies the command message.
DWORD <dwParam1>
Specifies flags for the command.
DWORD <dwParam2>
Specifies a pointer to a parameter block for the command.
.returns
Returns zero if the function was successful. Otherwise, it returns error
information. The low-order word of the returned DWORD is the error return
value. If the error is device-specific, the high-order word contains the
driver ID; otherwise the high-order word is zero.
To get a textual description of %mciSendCommand% return values, pass the
return value to %mciGetErrorString%.
Error values that are returned when a device is being opened are listed with
the MCI_OPEN message. In addition to the MCI_OPEN error returns, this
function can return the following values:
MCIERR_BAD_TIME_FORMAT
Illegal value for time format.
MCIERR_CANNOT_USE_ALL
The device name "all" is not allowed for this command.
MCIERR_CREATEWINDOW
Could not create or use window.
MCIERR_DEVICE_LOCKED
The device is locked until it is closed automatically.
MCIERR_DEVICE_NOT_READY
Device not ready.
MCIERR_DEVICE_TYPE_REQUIRED
The device name must be a valid device type.
MCIERR_DRIVER
Unspecified device error.
MCIERR_DRIVER_INTERNAL
Internal driver error.
MCIERR_FILE_NOT_FOUND
Requested file not found.
MCIERR_FILE_NOT_SAVED
The file was not saved.
MCIERR_FILE_READ
A read from the file failed.
MCIERR_FILE_WRITE
A write to the file failed.
MCIERR_FLAGS_NOT_COMPATIBLE
Incompatible parameters were specified.
MCIERR_HARDWARE
Hardware error on media device.
MCIERR_INTERNAL
Internal error.
MCIERR_INVALID_DEVICE_ID
Invalid device ID.
MCIERR_INVALID_DEVICE_NAME
The device is not open or is not known.
MCIERR_INVALID_FILE
Invalid file format.
MCIERR_MULTIPLE
Errors occurred in more than one device.
MCIERR_NO_WINDOW
There is no display window.
MCIERR_NULL_PARAMETER_BLOCK
Parameter block pointer was NULL.
MCIERR_OUT_OF_MEMORY
Not enough memory for requested operation.
MCIERR_OUTOFRANGE
Parameter value out of range.
MCIERR_UNNAMED_RESOURCE
Attempt to save unnamed file.
MCIERR_UNRECOGNIZED_COMMAND
Unknown command.
MCIERR_UNSUPPORTED_FUNCTION
Action not available for this device.
The following additional return values are defined for MCI sequencers:
MCIERR_SEQ_DIV_INCOMPATIBLE
Set Song Pointer incompatible with SMPTE files.
MCIERR_SEQ_PORT_INUSE
Specified port is in use.
MCIERR_SEQ_PORT_MAPNODEVICE
Current map uses non-existent device.
MCIERR_SEQ_PORT_MISCERROR
Miscellaneous error with specified port.
MCIERR_SEQ_PORT_NONEXISTENT
Specified port does not exist.
MCIERR_SEQ_PORTUNSPECIFIED
No current MIDI port.
MCIERR_SEQ_TIMER
Timer error.
The following additional return values are defined for MCI waveform
audio devices:
MCIERR_WAVE_INPUTSINUSE
No compatible waveform recording device is free.
MCIERR_WAVE_INPUTSUNSUITABLE
No compatible waveform recording devices.
MCIERR_WAVE_INPUTUNSPECIFIED
Any compatible waveform recording device may be used.
MCIERR_WAVE_OUTPUTSINUSE
No compatible waveform playback device is free.
MCIERR_WAVE_OUTPUTSUNSUITABLE
No compatible waveform playback devices.
MCIERR_WAVE_OUTPUTUNSPECIFIED
Any compatible waveform playback device may be used.
MCIERR_WAVE_SETINPUTINUSE
Set waveform recording device is in use.
MCIERR_WAVE_SETINPUTUNSUITABLE
Set waveform recording device is incompatible with set format.
MCIERR_WAVE_SETOUTPUTINUSE
Set waveform playback device is in use.
MCIERR_WAVE_SETOUTPUTUNSUITABLE
Set waveform playback device is incompatible with set format.
.comments
Use the %MCI_OPEN% command to obtain the device ID specified by
<wDeviceID>.
.seealso
%mciGetErrorString%, %mciSendString%
.refpage mciSendString
DWORD %mciSendString%(<lpstrCommand>, <lpstrReturnString>, <wReturnLength>,
<hCallback>)
This function sends a command string to an MCI device. The device that the
command is sent to is specified in the command string.
.parameters
LPSTR <lpstrCommand>
Specifies an MCI command string.
LPSTR <lpstrReturnString>
Specifies a buffer for return information. If no return information is
needed, you can specify NUL for this parameter.
WORD <wReturnLength>
Specifies the size of the return buffer specified by
<lpstrReturnString>.
HANDLE <hCallback>
Specifies a handle to a window to call back if "notify" was specified in
the command string.
.returns
Returns zero if the function was successful. Otherwise, it returns error
information. The low-order word of the returned DWORD contains the error
return value.
To get a textual description of %mciSendString% return values, pass the
return value to %mciGetErrorString%.
The error returns listed for %mciSendCommand% also apply to %mciSendString%.
The following error returns are unique to %mciSendString%:
MCIERR_BAD_CONSTANT
Unknown value for parameter.
MCIERR_BAD_INTEGER
Invalid or missing integer in command.
MCIERR_DUPLICATE_FLAGS
A flag or value was specified twice.
MCIERR_MISSING_COMMAND_STRING
No command was specified.
MCIERR_MISSING_DEVICE_NAME
No device name was specified.
MCIERR_MISSING_STRING_ARGUMENT
A string value was missing from the command.
MCIERR_NEW_REQUIRES_ALIAS
An alias must be used with the "new" device name.
MCIERR_NO_CLOSING_QUOTE
A closing quotation mark is missing.
MCIERR_NOTIFY_ON_AUTO_OPEN
The "notify" flag is illegal with auto-open.
MCIERR_PARAM_OVERFLOW
The output string was not long enough.
MCIERR_PARSER_INTERNAL
Internal parser error.
MCIERR_UNRECOGNIZED_KEYWORD
Unknown command parameter.
.seealso
%mciExecute%, %mciGetErrorString%, %mciSendCommand%
.refpage mciSetYieldProc
WORD FAR %mciSetYieldProc%(<wDeviceID>, <fpYieldProc>, <dwYieldData>)
This function sets the address of a callback procedure to be called
periodically when an MCI device is completing a command specified with the
WAIT flag.
.parameters
WORD <wDeviceID>
Specifies the device ID of the MCI device to which the yield procedure
is to be assigned.
YIELDPROC <fpYieldProc>
Specifies the callback procedure to be called when the given device is
yielding. Specify a NULL value to disable any existing yield procedure.
DWORD <dwYieldData>
Specifies the data sent to the yield procedure when it is called for the
given device.
.returns
Returns TRUE if successful. Returns FALSE for an invalid device ID.
.head "Callback"
int FAR PASCAL %YieldProc%(<wDeviceID>, <dwData>)
%YieldProc% is a placeholder for the application-supplied function name.
Export the actual name by including it in the EXPORTS statement in your
module-definition file.
%Parameters%
WORD <wDeviceID>
Specifies the device ID of the MCI device.
DWORD <dwData>
Specifies the application-supplied yield data originally supplied in the
<dwYieldData> parameter.
%Return Value%
Return zero to continue the operation. To cancel the operation, return a
nonzero value.
%Comments%
This call overides any previous yield procedure for this device.
.refpage MessageBeep
void %MessageBeep%(<wAlert>)
This function plays a waveform sound corresponding to a given system alert
level. The sound for each alert level is identified by an entry in the
[sounds] section of WIN.INI.
.parameters
WORD <wAlert>
Specifies the alert level. Use one of the following values:
MB_OK
Plays the sound identified by the "SystemDefault" entry in the [sounds]
section of WIN.INI.
MB_ICONASTERISK
Plays the sound identified by the "SystemAsterisk" entry in the [sounds]
section of WIN.INI.
MB_ICONEXCLAMATION
Plays the sound identified by the "SystemExclamation" entry in the
[sounds] section of WIN.INI.
MB_ICONHAND
Plays the sound identified by the "SystemHand" entry in the [sounds]
section of WIN.INI.
MB_ICONQUESTION
Plays the sound identified by the "SystemQuestion" entry in the [sounds]
section of WIN.INI.
0
Plays the sound identified by the "SystemDefault" entry in the [sounds]
section of WIN.INI.
-1
Produces a standard beep sound using the computer speaker.
.returns
None
.comments
%MessageBeep% returns control to the caller after queuing the sound and
plays the sound asynchronously.
If the specified alert sound can't be played, %MessageBeep% tries to play
the system default sound. If the system default sound can't be played, it
produces a standard beep sound using the computer speaker.
The user can disable the warning beep using the Sounds control-panel
applet.
.seealso
%sndPlaySound%
.refpage midiInAddBuffer
WORD %midiInAddBuffer%(<hMidiIn>, <lpMidiInHdr>, <wSize>)
This function sends an input buffer to a specified opened MIDI input device.
When the buffer is filled, it is sent back to the application. Input buffers
are used only for system exclusive messages.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
LPMIDIHDR <lpMidiInHdr>
Specifies a far pointer to a %MIDIHDR% structure that identifies the
buffer.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_UNPREPARED
<lpMidiInHdr> hasn't been prepared.
.endlist
.comments
The data buffer must be prepared with %midiInPrepareHeader% before it is
passed to %midiInAddBuffer%. The %MIDIHDR% data structure and the data
buffer pointed to by its %lpData% field must be allocated with %GlobalAlloc%
using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with %GlobalLock%.
.seealso
%midiInPrepareHeader%
.refpage midiInClose
WORD %midiInClose%(<hMidiIn>)
This function closes the specified MIDI input device.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device. If the function is
successful, the handle is no longer valid after this call.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_STILLPLAYING
There are still buffers in the queue.
.endlist
.comments
If there are input buffers that have been sent with %midiInAddBuffer% and
haven't been returned to the application, the close operation will fail.
Call %midiInReset% to mark all pending buffers as being done.
.seealso
%midiInOpen%, %midiInReset%
.refpage midiInGetDevCaps
WORD %midiInGetDevCaps%(<wDeviceID>, <lpCaps>, <wSize>)
This function queries a specified MIDI input device to determine its
capabilities.
.parameters
WORD <wDeviceID>
Identifies the MIDI input device.
LPMIDIINCAPS <lpCaps>
Specifies a far pointer to a %MIDIINCAPS% data structure. This structure
is filled with information about the capabilities of the device.
WORD <wSize>
Specifies the size of the %MIDIINCAPS% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Use %midiInGetNumDevs% to determine the number of MIDI input devices present
in the system. The device ID specified by <wDeviceID> varies from zero to
one less than the number of devices present. Only <wSize> bytes (or less) of
information is copied to the location pointed to by <lpCaps>. If <wSize> is
zero, nothing is copied, and the function returns zero.
.seealso
%midiInGetNumDevs%
.refpage midiInGetErrorText
WORD %midiInGetErrorText%(<wError>, <lpText>, <wSize>)
This function retrieves a textual description of the error identified by the
specified error number.
.parameters
WORD <wError>
Specifies the error number.
LPSTR <lpText>
Specifies a far pointer to the buffer to be filled with the textual
error description.
WORD <wSize>
Specifies the length of buffer pointed to by <lpText>.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADERRNUM
Specified error number is out of range.
.endlist
.comments
If the textual error description is longer than the specified buffer, the
description is truncated. The returned error string is always
null-terminated. If <wSize> is zero, nothing is copied, and the function
returns zero. All error descriptions are less than MAXERRORLENGTH characters
long.
.refpage midiInGetID
WORD %midiInGetID%(<hMidiIn>, <lpwDeviceID>)
This function gets the device ID for a MIDI input device.
.parameters
HMIDIIN <hMidiIn>
Specifies the handle to the MIDI input device.
LPWORD <lpwDeviceID>
Specifies a pointer to the WORD-sized memory location to be filled with
the device ID.
.returns
Returns zero if successful. Otherwise, returns an error number. Possible
error returns are:
MMSYSERR_INVALHANDLE
The <hMidiIn> parameter specifies an invalid handle.
.refpage midiInGetNumDevs
WORD %midiInGetNumDevs%()
This function retrieves the number of MIDI input devices in the system.
.parameters
None
.returns
Returns the number of MIDI input devices present in the system.
.seealso
%midiInGetDevCaps%
.refpage midiInOpen
WORD %midiInOpen%(<lphMidiIn>, <wDeviceID>, <dwCallback>,
<dwCallbackInstance>, <dwFlags>)
This function opens a specified MIDI input device.
.parameters
LPHMIDIIN <lphMidiIn>
Specifies a far pointer to an HMIDIIN handle. This location is filled
with a handle identifying the opened MIDI input device. Use the handle
to identify the device when calling other MIDI input functions.
WORD <wDeviceID>
Identifies the MIDI input device to be opened.
DWORD <dwCallback>
Specifies the address of a fixed callback function or a handle to a
window called with information about incoming MIDI messages.
DWORD <dwCallbackInstance>
Specifies user instance data passed to the callback function. This
parameter is not used with window callbacks.
DWORD <dwFlags>
Specifies a callback flag for opening the device.
CALLBACK_WINDOW
If this flag is specified, <dwCallback> is assumed to be a window
handle.
CALLBACK_FUNCTION
If this flag is specified, <dwCallback> is assumed to be a callback
procedure address.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_ALLOCATED
Specified resource is already allocated.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
.endlist
.comments
Use %midiInGetNumDevs% to determine the number of MIDI input devices present
in the system. The device ID specified by <wDeviceID> varies from zero to
one less than the number of devices present.
If a window is chosen to receive callback information, the following
messages are sent to the window procedure function to indicate the progress
of MIDI input:
.blist
o %MM_MIM_OPEN%
o %MM_MIM_CLOSE%
o %MM_MIM_DATA%
o %MM_MIM_LONGDATA%
o %MM_MIM_ERROR%
o %MM_MIM_LONGERROR%
.endblist
If a function is chosen to receive callback information, the following
messages are sent to the function to indicate the progress of MIDI input:
.blist
o %MIM_OPEN%, %MIM_CLOSE%
o %MIM_DATA%
o %MIM_LONGDATA%
o %MIM_ERROR%
o %MIM_LONGERROR%
.endblist
The callback function must reside in a DLL. You do not have to use
%MakeProcInstance% to get a procedure-instance address for the callback
function.
.head "Callback"
void FAR PASCAL %MidiInFunc%(<hMidiIn>, <wMsg>, <dwInstance>, <dwParam1>,
<dwParam2>)
%MidiInFunc% is a placeholder for the application-supplied function name.
The actual name must be exported by including it in an EXPORTS statement in
the DLL's module definition file.
%Parameters%
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
WORD <wMsg>
Specifies a MIDI input message.
DWORD <dwInstance>
Specifies the instance data supplied with %midiInOpen%.
DWORD <dwParam1>
Specifies a parameter for the message.
DWORD <dwParam2>
Specifies a parameter for the message.
%Comments%
Because the callback is accessed at interrupt time, it must reside in a DLL,
and its code segment must be specified as FIXED in the module-definition
file for the DLL. Any data that the callback accesses must be in a FIXED
data segment as well. The callback may not make any system calls except for
%PostMessage%, %timeGetSystemTime%, %timeGetTime%, %timeSetEvent%,
%timeKillEvent%, %midiOutShortMsg%, %midiOutLongMsg%, and %OutputDebugStr%.
.seealso
%midiInClose%
.refpage midiInPrepareHeader
WORD %midiInPrepareHeader%(<hMidiIn>, <lpMidiInHdr>, <wSize>)
This function prepares a buffer for MIDI input.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
LPMIDIHDR <lpMidiInHdr>
Specifies a pointer to a %MIDIHDR% structure that identifies the buffer
to be prepared.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
.endlist
.comments
The %MIDIHDR% data structure and the data block pointed to by its %lpData%
field must be allocated with %GlobalAlloc% using the GMEM_MOVEABLE and
GMEM_SHARE flags, and locked with %GlobalLock%. Preparing a header that has
already been prepared has no effect, and the function returns zero.
.seealso
%midiInUnprepareHeader%
.refpage midiInReset
WORD %midiInReset%(<hMidiIn>)
This function stops input on a given MIDI input device and marks all pending
input buffers as done.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.seealso
%midiInStart%, %midiInStop%, %midiInAddBuffer%, %midiInClose%
.refpage midiInStart
WORD %midiInStart%(<hMidiIn>)
This function starts MIDI input on the specified MIDI input device.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
This function resets the timestamps to zero; timestamp values for
subsequently received messages are relative to the time this function was
called.
All messages other than system exclusive messages are sent directly to the
client when received. System exclusive messages are placed in the buffers
supplied by %midiInAddBuffer%; if there are no buffers in the queue, the
data is thrown away without notification to the client, and input
continues.
Buffers are returned to the client when full, when a complete system
exclusive message has been received, or when %midiInReset% is called. The
%dwBytesRecorded% field in the header will contain the actual length of data
received.
Calling this function when input is already started has no effect, and the
function returns zero.
.seealso
%midiInStop%, %midiInReset%
.refpage midiInStop
WORD %midiInStop%(<hMidiIn>)
This function terminates MIDI input on the specified MIDI input device.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Current status (running status, parsing state, etc.) is maintained across
calls to %midiInStop% and %midiInStart%. If there are any system exclusive
message buffers in the queue, the current buffer is marked as done (the
%dwBytesRecorded% field in the header will contain the actual length of
data), but any empty buffers in the queue remain there. Calling this
function when input is not started has no no effect, and the function
returns zero.
.seealso
%midiInStart%, %midiInReset%
.refpage midiInUnprepareHeader
WORD %midiInUnprepareHeader%(<hMidiIn>, <lpMidiInHdr>, <wSize>)
This function cleans up the preparation performed by %midiInPrepareHeader%.
The %midiInUnprepareHeader% function must be called after the device driver
fills a data buffer and returns it to the application. You must call this
function before freeing the data buffer.
.parameters
HMIDIIN <hMidiIn>
Specifies a handle to the MIDI input device.
LPMIDIHDR <lpMidiInHdr>
Specifies a pointer to a %MIDIHDR% structure identifying the data buffer
to be cleaned up.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_STILLPLAYING
<lpMidiInHdr> is still in the queue.
.endlist
.comments
This function is the complementary function to %midiInPrepareHeader%. You
must call this function before freeing the data buffer with %GlobalFree%.
After passing a buffer to the device driver with %midiInAddBuffer%, you must
wait until the driver is finished with the buffer before calling
%midiInUnprepareHeader%. Unpreparing a buffer that has not been prepared has
no effect, and the function returns zero.
.seealso
%midiInPrepareHeader%
.refpage midiOutCacheDrumPatches
WORD %midiOutCacheDrumPatches%(<hMidiOut>, <wPatch>, <lpKeyArray>, <wFlags>)
This function requests that an internal MIDI synthesizer device preload a
specified set of key-based percussion patches. Some synthesizers are not
capable of keeping all percussion patches loaded simultaneously. Caching
patches ensures specified patches are available.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the opened MIDI output device. This device should
be an internal MIDI synthesizer.
WORD <wPatch>
Specifies which drum patch number should be used. Currently, this
parameter must be set to zero.
LPKEYARRAY <lpKeyArray>
Specifies a pointer to a %KEYARRAY% array indicating the key numbers of
the specified percussion patches to be cached or uncached.
WORD <wFlags>
Specifies options for the cache operation. Only one of the following
flags can be specified:
MIDI_CACHE_ALL
Cache all of the specified patches. If they can't all be cached, cache
none, clear the %KEYARRAY% array, and return MMSYSERR_NOMEM.
MIDI_CACHE_BESTFIT
Cache all of the specified patches. If all patches can't be cached,
cache as many patches as possible, change the %KEYARRAY% array to
reflect which patches were cached, and return MMSYSERR_NOMEM.
MIDI_CACHE_QUERY
Change the %KEYARRAY% array to indicate which patches are currently
cached.
MIDI_UNCACHE
Uncache the specified patches and clear the %KEYARRAY% array.
.returns
Returns zero if the function was successful. Otherwise, it returns one of
the following error codes:
MMSYSERR_INVALHANDLE
The specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
The specified device does not support patch caching.
MMSYSERR_NOMEM
The device does not have enough memory to cache all of the requested
patches.
.comments
The %KEYARRAY% data type is defined as:
typedef WORD KEYARRAY[128];
Each element of the array represents one of the 128 key-based percussion
patches and has bits set for each of the 16 MIDI channels that use that
particular patch. The least-significant bit represents physical channel 0;
the most-significant bit represents physical channel 15. For example, if the
patch on key number 60 is used by physical channels 9 and 15, element 60
would be set to 0x8200.
This function applies only to internal MIDI synthesizer devices. Not all
internal synthesizers support patch caching. Use the MIDICAPS_CACHE flag to
test the %dwSupport% field of the %MIDIOUTCAPS% structure filled by
%midiOutGetDevCaps% to see if the device supports patch caching.
.seealso
%midiOutCachePatches%
.refpage midiOutCachePatches
WORD %midiOutCachePatches%(<hMidiOut>, <wBank>, <lpPatchArray>, <wFlags>)
This function requests that an internal MIDI synthesizer device preload a
specified set of patches. Some synthesizers are not capable of keeping all
patches loaded simultaneously and must load data from disk when they receive
MIDI program change messages. Caching patches ensures specified patches are
immediately available.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the opened MIDI output device. This device must be
an internal MIDI synthesizer.
WORD <wBank>
Specifies which bank of patches should be used. Currently, this
parameter must be set to zero.
LPPATCHARRAY <lpPatchArray>
Specifies a pointer to a %PATCHARRAY% array indicating the patches to be
cached or uncached.
WORD <wFlags>
Specifies options for the cache operation. Only one of the following
flags can be specified:
MIDI_CACHE_ALL
Cache all of the specified patches. If they can't all be cached, cache
none, clear the %PATCHARRAY% array, and return MMSYSERR_NOMEM.
MIDI_CACHE_BESTFIT
Cache all of the specified patches. If all patches can't be cached,
cache as many patches as possible, change the %PATCHARRAY% array to
reflect which patches were cached, and return MMSYSERR_NOMEM.
MIDI_CACHE_QUERY
Change the %PATCHARRAY% array to indicate which patches are currently
cached.
MIDI_UNCACHE
Uncache the specified patches and clear the %PATCHARRAY% array.
.returns
Returns zero if the function was successful. Otherwise, it returns one of
the following error codes:
MMSYSERR_INVALHANDLE
The specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
The specified device does not support patch caching.
MMSYSERR_NOMEM
The device does not have enough memory to cache all of the requested
patches.
.comments
The %PATCHARRAY% data type is defined as:
typedef WORD PATCHARRAY[128];
Each element of the array represents one of the 128 patches and has bits set
for each of the 16 MIDI channels that use that particular patch. The
least-significant bit represents physical channel 0; the most-significant
bit represents physical channel 15 (0x0F). For example, if patch 0 is used
by physical channels 0 and 8, element 0 would be set to 0x0101.
This function only applies to internal MIDI synthesizer devices. Not all
internal synthesizers support patch caching. Use the MIDICAPS_CACHE flag to
test the %dwSupport% field of the %MIDIOUTCAPS% structure filled by
%midiOutGetDevCaps% to see if the device supports patch caching.
.seealso
%midiOutCacheDrumPatches%
.refpage midiOutClose
WORD %midiOutClose%(<hMidiOut>)
This function closes the specified MIDI output device.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device. If the function is
successful, the handle is no longer valid after this call.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_STILLPLAYING
There are still buffers in the queue.
.endlist
.comments
If there are output buffers that have been sent with %midiOutLongMsg% and
haven't been returned to the application, the close operation will fail.
Call %midiOutReset% to mark all pending buffers as being done.
.seealso
%midiOutOpen%, %midiOutReset%
.refpage midiOutGetDevCaps
WORD %midiOutGetDevCaps%(<wDeviceID>, <lpCaps>, <wSize>)
This function queries a specified MIDI output device to determine its
capabilities.
.parameters
WORD <wDeviceID>
Identifies the MIDI output device.
LPMIDIOUTCAPS <lpCaps>
Specifies a far pointer to a %MIDIOUTCAPS% structure. This structure is
filled with information about the capabilities of the device.
WORD <wSize>
Specifies the size of the %MIDIOUTCAPS% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Use %midiOutGetNumDevs% to determine the number of MIDI output devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present. Only <wSize> bytes (or
less) of information is copied to the location pointed to by <lpCaps>. If
<wSize> is zero, nothing is copied, and the function returns zero.
.seealso
%midiOutGetNumDevs%
.refpage midiOutGetErrorText
WORD %midiOutGetErrorText%(<wError>, <lpText>, <wSize>)
This function retrieves a textual description of the error identified by the
specified error number.
.parameters
WORD <wError>
Specifies the error number.
LPSTR <lpText>
Specifies a far pointer to a buffer to be filled with the textual error
description.
WORD <wSize>
Specifies the length of the buffer pointed to by <lpText>.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADERRNUM
Specified error number is out of range.
.endlist
.comments
If the textual error description is longer than the specified buffer, the
description is truncated. The returned error string is always
null-terminated. If <wSize> is zero, nothing is copied, and the function
returns MMSYSERR_NOERROR. All error descriptions are less than
MAXERRORLENGTH characters long.
.refpage midiOutGetID
WORD %midiOutGetID%(<hMidiOut>, <lpwDeviceID>)
This function gets the device ID for a MIDI output device.
.parameters
HMIDIOUT <hMidiOut>
Specifies the handle to the MIDI output device.
LPWORD <lpwDeviceID>
Specifies a pointer to the WORD-sized memory location to be filled with
the device ID.
.returns
Returns MMSYSERR_NOERROR if successful. Otherwise, returns an error number.
Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
The <hMidiOut> parameter specifies an invalid handle.
.endlist
.refpage midiOutGetNumDevs
WORD %midiOutGetNumDevs%()
This function retrieves the number of MIDI output devices present in the
system.
.parameters
None
.returns
Returns the number of MIDI output devices present in the system.
.seealso
%midiOutGetDevCaps%
.refpage midiOutGetVolume
WORD %midiOutGetVolume%(<wDeviceID>, <lpdwVolume>)
This function returns the current volume setting of a MIDI output device.
.parameters
WORD <wDeviceID>
Identifies the MIDI output device.
LPDWORD <lpdwVolume>
Specifies a far pointer to a location to be filled with the current
volume setting. The low-order word of this location contains the left
channel volume setting, and the high-order word contains the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of the specified location contains the mono volume
level.
The full 16-bit setting(s) set with %midiOutSetVolume% is returned,
regardless of whether the device supports the full 16 bits of volume
level control.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Not all devices support volume control. To determine whether the device
supports volume control, use the MIDICAPS_VOLUME flag to test the
%dwSupport% field of the %MIDIOUTCAPS% structure (filled by
%midiOutGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the MIDICAPS_LRVOLUME flag to test the %dwSupport% field
of the %MIDIOUTCAPS% structure (filled by %midiOutGetDevCaps%).
.seealso
%midiOutSetVolume%
.refpage midiOutLongMsg
WORD %midiOutLongMsg%(<hMidiOut>, <lpMidiOutHdr>, <wSize>)
This function sends a long MIDI message to the specified MIDI output device.
Use this function to send system exclusive messages or to send a buffer
filled with short messages.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device.
LPMIDIHDR <lpMidiOutHdr>
Specifies a far pointer to a %MIDIHDR% structure that identifies the
MIDI data buffer.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_UNPREPARED
<lpMidiOutHdr> hasn't been prepared.
MIDIERR_NOTREADY
The hardware is busy with other data.
.endlist
.comments
The data buffer must be prepared with %midiOutPrepareHeader% before it is
passed to %midiOutLongMsg%. The %MIDIHDR% data structure and the data buffer
pointed to by its %lpData% field must be allocated with %GlobalAlloc% using
the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with %GlobalLock%. This
function may or may not return until the data block has been sent to the
output device.
.seealso
%midiOutShortMsg%, %midiOutPrepareHeader%
.refpage midiOutOpen
WORD %midiOutOpen%(<lphMidiOut>, <wDeviceID>, <dwCallback>,
<dwCallbackInstance>, <dwFlags>)
This function opens a specified MIDI output device for playback.
.parameters
LPHMIDIOUT <lphMidiOut>
Specifies a far pointer to an HMIDIOUT handle. This location is filled
with a handle identifying the opened MIDI output device. Use the handle
to identify the device when calling other MIDI output functions.
WORD <wDeviceID>
Identifies the MIDI output device that is to be opened.
DWORD <dwCallback>
Specifies the address of a fixed callback function or a handle to a
window called during MIDI playback to process messages related to the
progress of the playback. Specify NULL for this parameter if no callback
is desired.
DWORD <dwCallbackInstance>
Specifies user instance data passed to the callback. This parameter is
not used with window callbacks.
DWORD <dwFlags>
Specifies a callback flag for opening the device.
CALLBACK_WINDOW
If this flag is specified, <dwCallback> is assumed to be a window
handle.
CALLBACK_FUNCTION
If this flag is specified, <dwCallback> is assumed to be a callback
procedure address.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are as follows:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_ALLOCATED
Specified resource is already allocated.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
MIDIERR_NOMAP
There is no current MIDI map. This occurs only when opening the mapper.
MIDIERR_NODEVICE
A port in the current MIDI map doesn't exist. This occurs only when
opening the mapper.
.endlist
.comments
Use %midiOutGetNumDevs% to determine the number of MIDI output devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present. You may also specify
MIDIMAPPER as the device ID to open the MIDI mapper.
If a window is chosen to receive callback information, the following
messages are sent to the window procedure function to indicate the progress
of MIDI output: %MM_MOM_OPEN%, %MM_MOM_CLOSE%, %MM_MOM_DONE%.
If a function is chosen to receive callback information, the following
messages are sent to the function to indicate the progress of MIDI output:
%MOM_OPEN%, %MOM_CLOSE%, %MOM_DONE%. The callback function must reside in a
DLL. You do not have to use %MakeProcInstance% to get a procedure-instance
address for the callback function.
.head "Callback"
void FAR PASCAL %MidiOutFunc%(<hMidiOut>, <wMsg>, <dwInstance>, <dwParam1>,
<dwParam2>)
%MidiOutFunc% is a placeholder for the application-supplied function name.
The actual name must be exported by including it in an EXPORTS statement in
the DLL's module-definition file.
%Parameters%
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI device associated with the callback.
WORD <wMsg>
Specifies a MIDI output message.
DWORD <dwInstance>
Specifies the instance data supplied with %midiOutOpen%.
DWORD <dwParam1>
Specifies a parameter for the message.
DWORD <dwParam2>
Specifies a parameter for the message.
%Comments%
Because the callback is accessed at interrupt time, it must reside in a DLL
and its code segment must be specified as FIXED in the module-definition
file for the DLL. Any data that the callback accesses must be in a FIXED
data segment as well. The callback may not make any system calls except for
%PostMessage%, %timeGetSystemTime%, %timeGetTime%, %timeSetEvent%,
%timeKillEvent%, %midiOutShortMsg%, %midiOutLongMsg%, and %OutputDebugStr%.
.seealso
%midiOutClose%
.refpage midiOutPrepareHeader
WORD %midiOutPrepareHeader%(<hMidiOut>, <lpMidiOutHdr>, <wSize>)
This function prepares a MIDI system exclusive data block for output.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device.
LPMIDIHDR <lpMidiOutHdr>
Specifies a far pointer to a %MIDIHDR% structure that identifies the
data block to be prepared.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
.endlist
.comments
The %MIDIHDR% data structure and the data block pointed to by its %lpData%
field must be allocated with %GlobalAlloc% using the GMEM_MOVEABLE and
GMEM_SHARE flags and locked with %GlobalLock%. Preparing a header that has
already been prepared has no effect, and the function returns zero.
.seealso
%midiOutUnprepareHeader%
.refpage midiOutReset
WORD %midiOutReset%(<hMidiOut>)
This function turns off all notes on all MIDI channels for the specified
MIDI output device.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
If the specified MIDI output device is an output port, a note off message
for each note of each channel is sent. In addition, a sustain (damper pedal)
off controller message is sent for each channel.
.seealso
%midiOutLongMsg%, %midiOutClose%
.refpage midiOutSetVolume
WORD %midiOutSetVolume%(<wDeviceID>, <dwVolume>)
This function sets the volume of a MIDI output device.
.parameters
WORD <wDeviceID>
Identifies the MIDI output device.
DWORD <dwVolume>
Specifies the new volume setting. The low-order word contains the left
channel volume setting, and the high-order word contains the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of <dwVolume> specifies the volume level, and the
high-order word is ignored.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Not all devices support volume changes. To determine whether the device
supports volume control, use the MIDICAPS_VOLUME flag to test the
%dwSupport% field of the %MIDIOUTCAPS% structure (filled by
%midiOutGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the MIDICAPS_LRVOLUME flag to test the %dwSupport% field
of the %MIDIOUTCAPS% structure (filled by %midiOutGetDevCaps%).
Most devices do not support the full 16 bits of volume level control and
will use only the high-order bits of the requested volume setting. For
example, for a device that supports 4 bits of volume control, requested
volume level values of 0x4000, 0x4fff, and 0x43be will all produce the same
physical volume setting, 0x4000. The %midiOutGetVolume% function will return
the full 16-bit setting set with %midiOutSetVolume%.
Volume settings are interpreted logarithmically. This means the perceived
increase in volume is the same when increasing the volume level from 0x5000
to 0x6000 as it is from 0x4000 to 0x5000.
.seealso
%midiOutGetVolume%
.refpage midiOutShortMsg
WORD %midiOutShortMsg%(<hMidiOut>, <dwMsg>)
This function sends a short MIDI message to the specified MIDI output
device. Use this function to send any MIDI message except for system
exclusive messages.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device.
DWORD <dwMsg>
Specifies the MIDI message. The message is packed into a DWORD with the
first byte of the message in the low order byte.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_NOTREADY
The hardware is busy with other data.
.endlist
.comments
This function may not return until the message has been sent to the output
device.
.seealso
%midiOutLongMsg%
.refpage midiOutUnprepareHeader
WORD %midiOutUnprepareHeader%(<hMidiOut>, <lpMidiOutHdr>, <wSize>)
This function cleans up the preparation performed by %midiOutPrepareHeader%.
The %midiOutUnprepareHeader% function must be called after the device driver
fills a data buffer and returns it to the application. You must call this
function before freeing the data buffer.
.parameters
HMIDIOUT <hMidiOut>
Specifies a handle to the MIDI output device.
LPMIDIHDR <lpMidiOutHdr>
Specifies a pointer to a %MIDIHDR% structure identifying the buffer to
be cleaned up.
WORD <wSize>
Specifies the size of the %MIDIHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MIDIERR_STILLPLAYING
<lpMidiOutHdr> is still in the queue.
.endlist
.comments
This function is the complementary function to %midiOutPrepareHeader%. You
must call this function before freeing the data buffer with %GlobalFree%.
After passing a buffer to the device driver with %midiOutLongMsg%, you must
wait until the driver is finished with the buffer before calling
%midiOutUnprepareHeader%.
Unpreparing a buffer that has not been prepared has no effect, and the
function returns zero.
.seealso
%midiOutPrepareHeader%
.refpage mmioAdvance
MMRESULT %mmioAdvance%(<hmmio>, <lpmmioinfo>, <uFlags>)
This function advances the I/O buffer of a file set up for direct I/O buffer
access with %mmioGetInfo%. If the file is opened for reading, the I/O buffer
is filled from the disk. If the file is opened for writing and the
MMIO_DIRTY flag is set in the %dwFlags% field of the %MMIOINFO% structure,
the buffer is written to disk. The %pchNext%, %pchEndRead%, and
%pchEndWrite% fields of the %MMIOINFO% structure are updated to reflect the
new state of the I/O buffer.
.parameters
HMMIO <hmmio>
Specifies the file handle for a file opened with %mmioOpen%.
LPMMIOINFO <lpmmioinfo>
Specifies a pointer to the %MMIOINFO% structure obtained with
%mmioGetInfo%.
UINT <uFlags>
Specifies options for the operation. Contains exactly one of the
following two flags:
MMIO_READ
The buffer is filled from the file.
MMIO_WRITE
The buffer is written to the file.
.returns
The return value is zero if the operation is successful. Otherwise, the
return value specifies an error code. The error code can be one of the
following codes:
MMIOERR_CANNOTWRITE
The contents of the buffer could not be written to disk.
MMIOERR_CANNOTREAD
An error occurred while re-filling the buffer.
MMIOERR_UNBUFFERED
The specified file is not opened for buffered I/O.
MMIOERR_CANNOTEXPAND
The specified memory file cannot be expanded, probably because the
%adwInfo[0]% field was set to zero in the initial call to %mmioOpen%.
MMIOERR_OUTOFMEMORY
There was not enough memory to expand a memory file for further
writing.
.comments
If the specified file is opened for writing or for both reading and writing,
the I/O buffer will be flushed to disk before the next buffer is read. If
the I/O buffer cannot be written to disk because the disk is full, then
%mmioAdvance% will return MMIOERR_CANNOTWRITE.
If the specified file is only open for writing, the MMIO_WRITE flag must be
specified.
If you have written to the I/O buffer, you must set the MMIO_DIRTY flag in
the %dwFlags% field of the %MMIOINFO% structure before calling
%mmioAdvance%. Otherwise, the buffer will not be written to disk.
If the end of file is reached, %mmioAdvance% will still return success, even
though no more data can be read. Thus, to check for the end of the file, it
is necessary to see if the %pchNext% and %pchEndRead% fields of the
%MMIOINFO% structure are equal after calling %mmioAdvance%.
.seealso
%mmioGetInfo%, %MMIOINFO%
.refpage mmioAscend
MMRESULT %mmioAscend%(<hmmio>, <lpck>, <uFlags>)
This function ascends out of a chunk in a RIFF file descended into with
%mmioDescend% or created with %mmioCreateChunk%.
.parameters
HMMIO <hmmio>
Specifies the file handle of an open RIFF file.
LPMMCKINFO <lpck>
Specifies a pointer to a caller-supplied %MMCKINFO% structure
previously filled by %mmioDescend% or %mmioCreateChunk%.
UINT <uFlags>
Is not used and should be set to zero.
.returns
The return value is zero if the function is successful. Otherwise, the
return value specifies an error code. The error code can be one of the
following codes:
MMIOERR_CANNOTWRITE
The contents of the buffer could not be written to disk.
MMIOERR_CANNOTSEEK
There was an error while seeking to the end of the chunk.
.comments
If the chunk was descended into using %mmioDescend%, then %mmioAscend% seeks
to the location following the end of the chunk (past the extra pad byte, if
any).
If the chunk was created and descended into using %mmioCreateChunk%, or if
the MMIO_DIRTY flag is set in the %dwFlags% field of the %MMCKINFO%
structure referenced by <lpck>, then the current file position is assumed to
be the end of the data portion of the chunk. If the chunk size is not the
same as the value stored in the %cksize% field when %mmioCreateChunk% was
called, then %mmioAscend% corrects the chunk size in the file before
ascending from the chunk. If the chunk size is odd, %mmioAscend% writes a
null pad byte at the end of the chunk. After ascending from the chunk, the
current file position is the location following the end of the chunk (past
the extra pad byte, if any).
.seealso
%mmioDescend%, %mmioCreateChunk%, %MMCKINFO%
.refpage mmioClose
MMRESULT %mmioClose%(<hmmio>, <uFlags>)
This function closes a file opened with %mmioOpen%.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file to close.
UINT <uFlags>
Specifies options for the close operation.
MMIO_FHOPEN
If the file was opened by passing the DOS file handle of an
already-opened file to %mmioOpen%, then using this flag tells
%mmioClose% to close the MMIO file handle, but not the DOS file handle.
(This is performed by the installed or default IOProc).
.returns
The return value is zero if the function is successful. Otherwise, the
return value is an error code, either from %mmioFlush% or from the I/O
procedure. The error code can be one of the following codes:
MMIOERR_CANNOTWRITE
The contents of the buffer could not be written to disk.
MMIOERR_CANNOTCLOSE
The DOS file system failed to close the file.
Other error codes are possible depending on the IOProcedure installed
.seealso
%mmioOpen%, %mmioFlush%
.refpage mmioCreateChunk
MMRESULT %mmioCreateChunk%(<hmmio>, <lpck>, <uFlags>)
This function creates a chunk in a RIFF file opened with %mmioOpen%. The new
chunk is created at the current file position. After the new chunk is
created, the current file position is the beginning of the data portion of
the new chunk.
.parameters
HMMIO <hmmio>
Specifies the file handle of an open RIFF file.
LPMMCKINFO <lpck>
Specifies a pointer to a caller-supplied %MMCKINFO% structure containing
information about the chunk to be created. Set up the %MMCKINFO%
structure as follows:
.blist
o The %ckid% field specifies the chunk ID of the chunk. If <wFlags>
includes MMIO_CREATERIFF or MMIO_CREATELIST, this field will be filled
by %mmioCreateChunk%.
o The %cksize% field specifies the size of the data portion of the chunk,
including the form type or list type (if any). If this value is not
correct when %mmioAscend% is called to mark the end of the chunk, them
%mmioAscend% will correct the chunk size.
o The %fccType% field specifies the form type or list type if the chunk is
a "RIFF" or "LIST" chunk. If the chunk is not a "RIFF" or "LIST" chunk,
this field need not be filled in.
o The %dwDataOffset% field need not be filled in. The %mmioCreateChunk%
function will fill this field with the file offset of the data portion
of the chunk.
o The %dwFlags% field need not be filled in. The %mmioCreateChunk%
function will set the MMIO_DIRTY flag in %dwFlags%.
.endblist
UINT <uFlags>
Specifies flags to optionally create either a "RIFF" chunk or a "LIST"
chunk. Can contain one of the following flags:
MMIO_CREATERIFF
Creates a "RIFF" chunk.
MMIO_CREATELIST
Creates a "LIST" chunk.
.returns
The return value is zero if the function is successful. Otherwise, the
return value specifies an error code. The error code can be one of the
following codes:
MMIOERR_CANNOTWRITE
Unable to write the chunk header.
MMIOERR_CANNOTSEEK
Uanble to determine offset of data portion of the chunk.
.comments
This function cannot insert a chunk into the middle of a file. If a chunk is
created anywhere but the end of a file, %mmioCreateChunk% will overwrite
existing information in the file.
.refpage mmioDescend
MMRESULT %mmioDescend%(<hmmio>, <lpck>, <lpckParent>, <uFlags>)
This function descends into a chunk of a RIFF file opened with %mmioOpen%.
It can also search for a given chunk.
.parameters
HMMIO <hmmio>
Specifies the file handle of an open RIFF file.
LPMMCKINFO <lpck>
Specifies a pointer to a caller-supplied %MMCKINFO% structure that
%mmioDescend% fills with the following information:
.blist
o The %ckid% field is the chunk ID of the chunk.
o The %cksize% field is the size of the data portion of the chunk. The
data size includes the form type or list type (if any), but does not
include the 8-byte chunk header or the pad byte at the end of the data
(if any).
o The %fccType% field is the form type if %ckid% is "RIFF", or the list
type if %ckid% is "LIST". Otherwise, it is NULL.
o The %dwDataOffset% field is the file offset of the beginning of the data
portion of the chunk. If the chunk is a "RIFF" chunk or a "LIST" chunk,
then %dwDataOffset% is the offset of the form type or list type.
o The %dwFlags% contains other information about the chunk. Currently,
this information is not used and is set to zero.
.endblist
If the MMIO_FINDCHUNK, MMIO_FINDRIFF, or MMIO_FINDLIST flag is specified
for <uFlags>, then the %MMCKINFO% structure is also used to pass
parameters to %mmioDescend%:
.blist
o The %ckid% field specifies the four-character code of the chunk ID, form
type, or list type to search for.
.endblist
LPMMCKINFO <lpckParent>
Specifies a pointer to an optional caller-supplied %MMCKINFO%
structure identifying the parent of the chunk being searched for. A
parent of a chunk is the enclosing chunk--only "RIFF" and "LIST" chunks
can be parents. If <lpckParent> is not NULL, then %mmioDescend% assumes
the %MMCKINFO% structure it refers to was filled when %mmioDescend% was
called to descend into the parent chunk, and %mmioDescend% will only
search for a chunk within the parent chunk. Set <lpckParent> to NULL if
no parent chunk is being specified.
UINT <uFlags>
Specifies search options. Contains up to one of the following flags. If
no flags are specified, %mmioDescend% descends into the chunk beginning
at the current file position.
MMIO_FINDCHUNK
Searches for a chunk with the specified chunk ID.
MMIO_FINDRIFF
Searches for a chunk with chunk ID "RIFF" and with the specified form
type.
MMIO_FINDLIST
Searches for a chunk with chunk ID "LIST" and with the specified form
type.
.returns
The return value is zero if the function is successful. Otherwise, the
return value specifies an error code. If the end of the file (or the end of
the parent chunk, if given) is reached before the desired chunk is found,
the return value is MMIOERR_CHUNKNOTFOUND. Other non-zero error returns
may be possible.
.comments
A RIFF chunk consists of a four-byte chunk ID (type FOURCC), followed by a
four-byte chunk size (type DWORD), followed by the data portion of the
chunk, followed by a null pad byte if the size of the data portion is odd.
If the chunk ID is "RIFF" or "LIST", the first four bytes of the data
portion of the chunk are a form type or list type (type FOURCC).
If %mmioDescend% is used to search for a chunk, the file position should be
at the beginning of a chunk before calling %mmioDescend%. The search begins
at the current file position and continues to the end of the file. If a
parent chunk is specified, the file position should be somewhere within the
parent chunk before calling %mmioDescend%. In this case, the search begins
at the current file position and continues to the end of the parent chunk.
If %mmioDescend% is unsuccessful in searching for a chunk, the current file
position is undefined. If %mmioDescend% is successful, the current file
position is changed. If the chunk is a "RIFF" or "LIST" chunk, the new file
position will be just after the form type or list type (12 bytes from the
beginning of the chunk). For other chunks, the new file position will be the
start of the data portion of the chunk (8 bytes from the beginning of the
chunk).
For efficient RIFF file I/O, use buffered I/O.
.seealso
%mmioAscend%, %MMCKINFO%
.refpage mmioFlush
MMRESULT %mmioFlush%(<hmmio>, <uFlags>)
This function writes the I/O buffer of a file to disk, if the I/O buffer has
been written to.
.parameters
HMMIO <hmmio>
Specifies the file handle of a file opened with %mmioOpen%.
UINT <uFlags>
Is not used and should be set to zero.
.returns
The return value is zero if the function is successful. Otherwise, the
return value specifies an error code. The error code can be one of the
following codes:
MMIOERR_CANNOTWRITE
The contents of the buffer could not be written to disk.
.comments
Closing a file with %mmioClose% will automatically flush its buffer.
If there is insufficient disk space to write the buffer, %mmioFlush% will
fail, even if the preceding %mmioWrite% calls were successful.
.refpage mmioFOURCC
FOURCC %mmioFOURCC%(<ch0>, <ch1>, <ch2>, <ch3>)
This macro converts four characters to to a DWORD code.
.parameters
CHAR <ch0>
The first character of the four-character code.
CHAR <ch1>
The second character of the four-character code.
CHAR <ch2>
The third character of the four-character code.
CHAR <ch3>
The fourth character of the four-character code.
.returns
The return value is the DWORD representing the four character code
created from the given characters.
.comments
This macro does not check to see if the four character code follows any
conventions regarding which characters to include in a four-character code.
.seealso
%mmioStringToFOURCC%
.refpage mmioGetInfo
MMRESULT %mmioGetInfo%(<hmmio>, <lpmmioinfo>, <uFlags>)
This function retrieves information about a file opened with %mmioOpen%.
This information allows the caller to directly access the I/O buffer, if the
file is opened for buffered I/O.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file.
LPMMIOINFO <lpmmioinfo>
Specifies a pointer to a caller-allocated %MMIOINFO% structure that
%mmioGetInfo% fills with information about the file. See the %MMIOINFO%
structure and the %mmioOpen% function for information about the fields
in this structure.
UINT <uFlags>
Is not used and should be set to zero.
.returns
The return value is zero if the function is successful.
.comments
To directly access the I/O buffer of a file opened for buffered I/O, use the
following fields of the %MMIOINFO% structure filled by %mmioGetInfo%:
.blist
o The %pchNext% field points to the next byte in the buffer that can be
read or written. When you read or write, increment %pchNext% by the
number of bytes read or written.
o The %pchEndRead% field points to one byte past the last valid byte in
the buffer that can be read.
o The %pchEndWrite% field points to one byte past the last location in the
buffer that can be written.
.endblist
Once you read or write to the buffer and modify %pchNext%, do not call any
MMIO function except %mmioAdvance% until you call %mmioSetInfo%. Call
%mmioSetInfo% when you are finished directly accessing the buffer.
When you reach the end of the buffer specified by %pchEndRead% or
%pchEndWrite%, call %mmioAdvance% to fill the buffer from the disk, or write
the buffer to the disk. The %mmioAdvance% function will update the
%pchNext%, %pchEndRead%, and %pchEndWrite% fields in the %MMIOINFO%
structure for the file.
Before calling %mmioAdvance% or %mmioSetInfo% to flush a buffer to disk, set
the MMIO_DIRTY flag in the %dwFlags% field of the %MMIOINFO% structure for
the file. Otherwise, the buffer will not get written to disk.
Do not decrement %pchNext% or modify any fields in the %MMIOINFO% structure
other than %pchNext% and %dwFlags%. Do not set any flags in %dwFlags% except
MMIO_DIRTY.
.seealso
%mmioSetInfo%, %MMIOINFO%
.refpage mmioInstallIOProc
LPMMIOPROC %mmioInstallIOProc%(<fccIOProc>, <pIOProc>, <dwFlags>)
This function installs or removes a custom I/O procedure. It will also
locate an installed I/O procedure, given its corresponding four-character
code.
.parameters
FOURCC <fccIOProc>
Specifies a four-character code identifying the I/O procedure to
install, remove, or locate. All characters in this four-character code
should be uppercase characters.
LPMMIOPROC <pIOProc>
Specifies the address of the I/O procedure to install. To remove or
locate an I/O procedure, set this parameter to NULL.
DWORD <dwFlags>
Specifies one of the following flags indicating whether the I/O
procedure is being installed, removed, or located:
MMIO_INSTALLPROC
Installs the specified I/O procedure.
MMIO_REMOVEPROC
Removes the specified I/O procedure.
MMIO_FINDPROC
Searches for the specified I/O procedure.
.returns
The return value is the address of the I/O procedure installed, removed, or
located. If there is an error, the return value is NULL.
.comments
If the I/O procedure resides in the application, for compatibility with the
16 bit windows API use %MakeProcInstance% to
get a procedure-instance address and specify this address for <pIOProc>. You
don't need to get a procedure-instance address if the I/O procedure resides
in a DLL.
.head "Callback"
LONG %IOProc%(<lpmmioinfo>, <wMsg>, <lParam1>, <lParam2>)
%IOProc% is a placeholder for the application-supplied function name. The
actual name must be exported by including it in a EXPORTS statement in the
application's module-definitions file.
%Parameters%
LPSTR <lpmmioinfo>
Specifies a pointer to an %MMIOINFO% structure containing
information about the open file. The I/O procedure must maintain the
%lDiskOffset% field in this structure to indicate the file offset to the
next read or write location. The I/O procedure can use the %adwInfo[]%
field to store state information. The I/O procedure should not modify
any other fields of the %MMIOINFO% structure.
UINT <uMsg>
Specifies a message indicating the requested I/O operation. Messages
that can be received include %MMIOM_OPEN%, %MMIOM_CLOSE%, %MMIOM_READ%,
%MMIOM_WRITE%, and %MMIOM_SEEK%.
LONG <lParam1>
Specifies a parameter for the message.
LONG <lParam2>
Specifies a parameter for the message.
%Return Value%
The return value depends on the message specified by <wMsg>. If the I/O
procedure does not recognize a message, it should return zero.
%Comments%
The four-character code specified by the %fccIOProc% field in the %MMIOINFO%
structure associated with a file identifies a filename extension for a
custom storage system. When an application calls %mmioOpen% with a filename
like "foo.xyz!bar", the I/O procedure associated with the four-character
code "XYZ " is called to open the "bar" element of the file "foo.xyz".
The %mmioInstallIOProc% function maintains a separate list of installed I/O
procedures for each Windows application. Therefore, different applications
can use the same I/O procedure identifier for different I/O procedures
without conflict.
To share an I/O procedure among applications, the I/O procedure must reside
in a DLL called by each application using it. Each application using the
shared I/O procedure must call %mmioInstallIOProc% to install the procedure
(or call the DLL to install the procedure on behalf of the application).
Each application must call %mmioInstallIOProc% to remove the I/O procedure
before terminating.
If an application calls %mmioInstallIOProc% more than once to register the
same I/O procedure, then it must call %mmioInstallIOProc% to remove the
procedure once for each time it installed the procedure.
%mmioInstallIOProc% will not prevent an application from installing two
different I/O procedures with the same identifier, or installing an I/O
procedure with one of the predefined identifiers ("DOS ", "MEM ", or "BND
"). The most recently installed procedure takes precedence, and the most
recently installed procedure is the first one to get removed.
.seealso
%mmioOpen%
.refpage mmioOpen
HMMIO %mmioOpen%(<szFilename>, <lpmmioinfo>, <dwOpenFlags>)
This function opens a file for unbuffered or buffered I/O. The file can be a
DOS file, a memory file, or an element of a custom storage system.
.parameters
LPSTR <szFilename>
Specifies a pointer to a string containing the filename of the file
to open. If no I/O procedure is specified to open the file, then the
filename determines how the file is opened, as follows:
.blist
o If the filename does not contain "+", then it is assumed to be the name
of a DOS file.
o If the filename is of the form "foo.ext+bar", then the extension "EXT "
is assumed to identify an installed I/O procedure which is called to
perform I/O on the file (see %mmioInstallIOProc%).
o If the filename is NULL and no I/O procedure is given, then %adwInfo[0]%
is assumed to be the DOS file handle of a currently open file.
.endblist
The filename should not be longer than 128 bytes, including the
terminating NULL.
When opening a memory file, set <szFilename> to NULL.
LPMMIOINFO <lpmmioinfo>
Specifies a pointer to an %MMIOINFO% structure containing extra
parameters used by %mmioOpen%. Unless you are opening a memory file,
specifying the size of a buffer for buffered I/O, or specifying an
uninstalled I/O procedure to open a file, this parameter should be
NULL.
If <lpmmioinfo> is not NULL, all unused fields of the %MMIOINFO%
structure it references must be set to zero, including the reserved
fields.
DWORD <dwOpenFlags>
Specifies option flags for the open operation. The MMIO_READ,
MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive--only one
should be specified. The MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE,
MMIO_DENYREAD, and MMIO_DENYNONE flags are DOS file-sharing flags, and
can only be used after the DOS command SHARE has been executed.
MMIO_READ
Opens the file for reading only. This is the default, if MMIO_WRITE and
MMIO_READWRITE are not specified.
MMIO_WRITE
Opens the file for writing. You should not read from a file opened in
this mode.
MMIO_READWRITE
Opens the file for both reading and writing.
MMIO_CREATE
Creates a new file. If the file already exists, it is truncated to zero
length. For memory files, MMIO_CREATE indicates the end of the file is
initially at the start of the buffer.
MMIO_DELETE
Deletes a file. If this flag is specified, <szFilename> should not be
NULL. The return value will be TRUE (cast to HMMIO) if the file was
deleted successfully, FALSE otherwise. Do not call %mmioClose% for a
file that has been deleted. If this flag is specified, all other flags
are ignored.
MMIO_ALLOCBUF
Opens a file for buffered I/O. To allocate a buffer larger or smaller
than the default buffer size (8K), set the %cchBuffer% field of the
%MMIOINFO% structure to the desired buffer size. If %cchBuffer% is zero,
then the default buffer size is used. If you are providing your own I/O
buffer, then the MMIO_ALLOCBUF flag should not be used.
MMIO_COMPAT
Opens the file with compatibility mode, allowing any process on a given
machine to open the file any number of times. %mmioOpen% fails if the
file has been opened with any of the other sharing modes.
MMIO_EXCLUSIVE
Opens the file with exclusive mode, denying other processes both read
and write access to the file. %mmioOpen% fails if the file has been
opened in any other mode for read or write access, even by the current
process.
MMIO_DENYWRITE
Opens the file and denies other processes write access to the file.
%mmioOpen% fails if the file has been opened in compatibility or for
write access by any other process.
MMIO_DENYREAD
Opens the file and denies other processes read access to the file.
%mmioOpen% fails if the file has been opened in compatibility mode or
for read access by any other process.
MMIO_DENYNONE
Opens the file without denying other processes read or write access to
the file. %mmioOpen% fails if the file has been opened in compatibility
mode by any other process.
.returns
The return value is a handle to the opened file. This handle is not a DOS
file handle--do not use it with any file I/O functions other than MMIO
functions.
If the file cannot be opened, the return value is NULL. If <lpmmioinfo> is
not NULL, then its %wError% field will contain extended error information
returned by the I/O procedure.
.comments
If <lpmmioinfo> references an %MMIOINFO% structure, set up the fields as
described below. All unused fields must be set to zero, including reserved
fields.
.blist
o To request that a file be opened with an installed I/O procedure, set
the %fccIOProc% field to the four-character code of the I/O procedure,
and set the %pIOProc% field to NULL.
o To request that a file be opened with an uninstalled I/O procedure, set
the %pIOProc% field to point to the I/O procedure, and set %fccIOProc%
to NULL.
o To request that %mmioOpen% determine which I/O procedure to use to open
the file based on the filename contained in <szFilename>, set both
%fccIOProc% and %pIOProc% to NULL. This is the default behavior if no
%MMIOINFO% structure is specified.
o To open a memory file using an internally allocated and managed buffer,
set the %pchBuffer% field to NULL, %fccIOProc% to FOURCC_MEM,
%cchBuffer% to the initial size of the buffer, and %adwInfo[0]% to the
incremental expansion size of the buffer. This memory file will
automatically be expanded in increments of %adwInfo[0]% bytes when
necessary. Specify the MMIO_CREATE flag for the <dwOpenFlags> parameter
to initially set the end of the file to be the beginning of the buffer.
o To open a memory file using a caller-supplied buffer, set the
%pchBuffer% field to point to the memory buffer, %fccIOProc% to
FOURCC_MEM, %cchBuffer% to the size of the buffer, and %adwInfo[0]% to
the incremental expansion size of the buffer. The expansion size in
%adwInfo[0]% should only be non-zero if %pchBuffer% is a pointer
obtained by calling %GlobalAlloc% and %GlobalLock%, since
%GlobalReAlloc% will be called to expand the buffer. In particular, if
%pchBuffer% points to a local or global array, a block of memory in the
local heap, or a block of memory allocated by %GlobalDosAlloc%,
%adwInfo[0]% must be zero.
Specify the MMIO_CREATE flag for the <dwOpenFlags> parameter to
initially set the end of the file to be the beginning of the buffer;
otherwise, the entire block of memory will be considered readable.
o To use a currently open DOS file handle with MMIO, set the %fccIOProc%
field to FOURCC_DOS, %pchBuffer% to NULL, and %adwInfo[0]% to the DOS
file handle. Note that offsets within the file will be relative to the
beginning of the file, and will not depend on the DOS file position at
the time %mmioOpen% is called; the initial MMIO offset will be the same
as the DOS offset when %mmioOpen% is called. Later, to close the MMIO
file handle without closing the DOS file handle, pass the MMIO_FHOPEN
flag to %mmioClose%.
.endblist
You must call %mmioClose% to close a file opened with %mmioOpen%. Open files
are not automatically closed when an application exits.
.seealso
%mmioClose%
.refpage mmioRead
LRESULT %mmioRead%(<hmmio>, <pch>, <cch>)
This function reads a specified number of bytes from a file opened with
%mmioOpen%.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file to be read.
LPSTR <pch>
Specifies a pointer to a buffer to contain the data read from the
file.
LONG <cch>
Specifies the number of bytes to read from the file.
.returns
The return value is the number of bytes actually read. If the end of the
file has been reached and no more bytes can be read, the return value is
zero. If there is an error reading from the file, the return value is -1.
.comments
On 16 bit windows pch is a huge pointer. On 32 bit windows there is no
distinction between huge poointers and long pointers.
.seealso
%mmioWrite%
.refpage mmioSeek
LRESULT %mmioSeek%(<hmmio>, <lOffset>, <iOrigin>)
This function changes the current file position in a file opened with
%mmioOpen%. The current file position is the location in the file where data
is read or written.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file to seek in.
LONG <lOffset>
Specifies an offset to change the file position.
int <iOrigin>
Specifies how the offset specified by <lOffset> is interpreted. Contains
one of the following flags:
SEEK_SET
Seeks to <lOffset> bytes from the beginning of the file.
SEEK_CUR
Seeks to <lOffset> bytes from the current file position.
SEEK_END
Seeks to <lOffset> bytes from the end of the file.
.returns
The return value is the new file position in bytes, relative to the
beginning of the file. If there is an error, the return value is -1.
.comments
Seeking to an invalid location in the file, such as past the end of the
file, may fail to cause %mmioSeek% to return an error, but may cause subsequent
I/O operations on the file to fail.
To locate the end of a file, call %mmioSeek% with <lOffset> set to zero and
<iOrigin> set to SEEK_END.
.refpage mmioSendMessage
LRESULT %mmioSendMessage%(<hmmio>, <uMsg>, <lParam1>, <lParam2>)
This function sends a message to the I/O procedure associated with the
specified file.
.parameters
HMMIO <hmmio>
Specifies the file handle for a file opened with %mmioOpen%.
UINT <uMsg>
Specifies the message to send to the I/O procedure.
LONG <lParam1>
Specifies a parameter for the message.
LONG <lParam2>
Specifies a parameter for the message.
.returns
The return value depends on the message. If the I/O procedure does not
recognize the message, the return value is zero.
.comments
Use this function to send custom user-defined messages. Do not use it to
send the %MMIOM_OPEN%, %MMIOM_CLOSE%, %MMIOM_READ%, %MMIOM_WRITE%,
%MMIOM_WRITEFLUSH%, or %MMIOM_SEEK% messages. Define custom messages to be
greater than or equal to the MMIOM_USER constant.
.seealso
%mmioInstallIOProc%
.refpage mmioSetBuffer
MMRESULT %mmioSetBuffer%(<hmmio>, <pchBuffer>, <cchBuffer>, <uFlags>)
This function enables or disables buffered I/O, or changes the buffer or
buffer size for a file opened with %mmioOpen%.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file.
LPSTR <pchBuffer>
Specifies a pointer to a caller-supplied buffer to use for buffered
I/O. If NULL, %mmioSetBuffer% allocates an internal buffer for buffered
I/O.
LONG <cchBuffer>
Specifies the size of the caller-supplied buffer, or the size of the
buffer for %mmioSetBuffer% to allocate.
UINT <uFlags>
Is not used and should be set to zero.
.returns
The return value is zero if the function is successful. Otherwise, the
return value specifies an error code. If an error occurs, the file handle
remains valid. The error code can be one of the following codes:
MMIOERR_CANNOTWRITE
The contents of the old buffer could not be written to disk, so the
operation was aborted.
MMIOERR_OUTOFMEMORY
The new buffer could not be allocated, probably due to a lack of
available memory.
.comments
To enable buffering using an internal buffer, set <pchBuffer> to NULL and
<cchBuffer> to the desired buffer size.
To supply your own buffer, set <pchBuffer> to point to the buffer, and set
<cchBuffer> to the size of the buffer.
To disable buffered I/O, set <pchBuffer> to NULL and <cchBuffer> to zero.
If buffered I/O is already enabled using an internal buffer, you can
reallocate the buffer to a different size by setting <pchBuffer> to NULL and
<cchBuffer> to the new buffer size. The contents of the buffer may be
changed after resizing.
.refpage mmioSetInfo
MMRESULT %mmioSetInfo%(<hmmio>, <lpmmioinfo>, <uFlags>)
This function updates the information retrieved by %mmioGetInfo% about a
file opened with %mmioOpen%. Use this function to terminate direct buffer
access of a file opened for buffered I/O.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file.
LPMMIOINFO <lpmmioinfo>
Specifies a pointer to an %MMIOINFO% structure filled with
information with %mmioGetInfo%.
UINT <uFlags>
Is not used and should be set to zero.
.returns
The return value is zero if the function is successful.
.comments
If you have written to the file I/O buffer, set the MMIO_DIRTY flag in the
%dwFlags% field of the %MMIOINFO% structure before calling %mmioSetInfo% to
terminate direct buffer access. Otherwise, the buffer will not get flushed
to disk.
.seealso
%mmioGetInfo%, %MMIOINFO%
.refpage mmioStringToFOURCC
FOURCC %mmioStringToFOURCC%(<sz>, <uFlags>)
This function converts a null-terminated string to a four-character code.
.parameters
LPSTR <sz>
Specifies a pointer to a null-terminated string to a four-character
code.
UINT <uFlags>
Specifies options for the conversion:
MMIO_TOUPPER
Converts all characters to uppercase.
.returns
The return value is the four character code created from the given string.
.comments
This function does not check to see if the string <sz> follows conventions
regarding legal characters to use in a four-character code. The string is
simply copied to a four-character code and padded to the right with blanks
or truncated to four characters as required.
.seealso
%mmioFOURCC%
.refpage mmioWrite
LRESULT %mmioWrite%(<hmmio>, <pch>, <cch>)
This function writes a specified number of bytes to a file opened with
%mmioOpen%.
.parameters
HMMIO <hmmio>
Specifies the file handle of the file.
LPSTR <pch>
Specifies a pointer to the buffer to be written to the file.
LONG <cch>
Specifies the number of bytes to write to the file.
.returns
The return value is the number of bytes actually written. If there is an
error writing to the file, the return value is -1.
.comments
The current file position is incremented by the number of bytes written.
On 16 bit windows pch is a huge pointer. On 32 bit windows there is no
distinction between huge poointers and long pointers.
.seealso
%mmioRead%
.refpage sndPlaySound
BOOL %sndPlaySound%(<lpszSoundName>, <wFlags>)
This function plays a waveform sound specified by a filename or by an entry
in the [sounds] section of WIN.INI. If the sound can't be found, it plays
the default sound specified by the SystemDefault entry in the [sounds]
section of WIN.INI. If there is no SystemDefault entry or if the default
sound can't be found, the function makes no sound and returns FALSE.
.parameters
LPSTR <lpszSoundName>
Specifies the name of the sound to play. The function searches the
[sounds] section of WIN.INI for an entry with this name and plays the
associated waveform file. If no entry by this name exists, then it
assumes the name is the name of a waveform file. If this parameter is
NULL, any currently playing sound is stopped.
WORD <wFlags>
Specifies options for playing the sound using one or more of the
following flags:
SND_SYNC
The sound is played synchronously and the function does not return until
the sound ends.
SND_ASYNC
The sound is played asynchronously and the function returns immediately
after beginning the sound. To terminate an asynchronously-played sound,
call %sndPlaySound% with <lpszSoundName> set to NULL.
SND_NODEFAULT
If the sound can't be found, the function returns silently without
playing the default sound.
SND_MEMORY
The parameter specified by <lpszSoundName> points to an in-memory image
of a waveform sound.
SND_LOOP
The sound will continue to play repeatedly until %sndPlaySound% is
called again with the <lpszSoundName> parameter set to NULL. You must
also specify the SND_ASYNC flag to loop sounds.
SND_NOSTOP
If a sound is currently playing, the function will immediately return
FALSE without playing the requested sound.
.returns
Returns TRUE if the sound is played, otherwise returns FALSE.
.comments
The sound must fit in available physical memory and be playable by an
installed waveform audio device driver. The directories searched for sound
files are, in order: the current directory; the Windows directory; the
Windows system directory; the directories listed in the PATH environment
variable; the list of directories mapped in a network. See the Windows
%OpenFile% function for more information about the directory search order.
If you specify the SND_MEMORY flag, <lpszSoundName> must point to an
in-memory image of a waveform sound. If the sound is stored as a resource,
use %LoadResource% and %LockResource% to load and lock the resource and get
a pointer to it. If the sound is not a resource, you must use %GlobalAlloc%
with the GMEM_MOVEABLE and GMEM_SHARE flags set and then %GlobalLock% to
allocate and lock memory for the sound.
.seealso
%MessageBeep%
.refpage timeBeginPeriod
WORD %timeBeginPeriod%(<wPeriod>)
This function sets the minimum (lowest number of milliseconds) timer
resolution that an application or driver is going to use. Call this function
immediately before starting to use timer-event services, and call
%timeEndPeriod% immediately after finishing with the timer-event services.
.parameters
WORD <wPeriod>
Specifies the minimum timer-event resolution that the application or
driver will use.
.returns
Returns zero if successful. Returns TIMERR_NOCANDO if the specified
<wPeriod> resolution value is out of range.
.comments
For each call to %timeBeginPeriod%, you must call %timeEndPeriod% with a
matching <wPeriod> value. An application or driver can make multiple calls
to %timeBeginPeriod%, as long as each %timeBeginPeriod% call is matched with
a %timeEndPeriod% call.
.seealso
%timeEndPeriod%, %timeSetEvent%
.refpage timeEndPeriod
WORD %timeEndPeriod%(<wPeriod>)
This function clears a previously set minimum (lowest number of
milliseconds) timer resolution that an application or driver is going to
use. Call this function immediately after using timer event services.
.parameters
WORD <wPeriod>
Specifies the minimum timer-event resolution value specified in the
previous call to %timeBeginPeriod%.
.returns
Returns zero if successful. Returns TIMERR_NOCANDO if the specified
<wPeriod> resolution value is out of range.
.comments
For each call to %timeBeginPeriod%, you must call %timeEndPeriod% with a
matching <wPeriod> value. An application or driver can make multiple calls
to %timeBeginPeriod%, as long as each %timeBeginPeriod% call is matched with
a %timeEndPeriod% call.
.seealso
%timeBeginPeriod%, %timeSetEvent%
.refpage timeGetDevCaps
WORD %timeGetDevCaps%(<lpTimeCaps>, <wSize>)
This function queries the timer device to determine its capabilities.
.parameters
LPTIMECAPS <lpTimeCaps>
Specifies a far pointer to a %TIMECAPS% structure. This structure is
filled with information about the capabilities of the timer device.
WORD <wSize>
Specifies the size of the %TIMECAPS% structure.
.returns
Returns zero if successful. Returns TIMERR_NOCANDO if it fails to return the
timer device capabilities.
.refpage timeGetSystemTime
WORD %timeGetSystemTime%(<lpTime>, <wSize>)
This function retrieves the system time in milliseconds. The system time is
the time elapsed since Windows was started.
.parameters
LPMMTIME <lpTime>
Specifies a far pointer to an %MMTIME% data structure.
WORD <wSize>
Specifies the size of the %MMTIME% structure.
.returns
Returns zero. The system time is returned in the %ms% field of the %MMTIME%
structure.
.comments
The time is always returned in milliseconds.
.seealso
%timeGetTime%
.refpage timeGetTime
DWORD %timeGetTime%()
This function retrieves the system time in milliseconds. The system time is
the time elapsed since Windows was started.
.parameters
None
.returns
The return value is the system time in milliseconds.
.comments
The only difference between this function and the %timeGetSystemTime%
function is %timeGetSystemTime% uses the standard multimedia time structure
%MMTIME% to return the system time. The %timeGetTime% function has less
overhead than %timeGetSystemTime%.
.seealso
%timeGetSystemTime%
.refpage timeKillEvent
WORD %timeKillEvent%(<wID>)
This functions destroys a specified timer callback event.
.parameters
WORD <wID>
Identifies the event to be destroyed.
.returns
Returns zero if successful. Returns TIMERR_NOCANDO if the specified timer
event does not exist.
.comments
The timer event ID specified by <wID> must be an ID returned by
%timeSetEvent%.
.seealso
%timeSetEvent%
.refpage timeSetEvent
WORD %timeSetEvent%(<wDelay>, <wResolution>, <lpFunction>, <dwUser>,
<wFlags>)
This function sets up a timed callback event. The event can be a one-time
event or a periodic event. Once activated, the event calls the specified
callback function.
.parameters
WORD <wDelay>
Specifies the event period in milliseconds. If the delay is less than
the minimum period supported by the timer, or greater than the maximum
period supported by the timer, the function returns an error.
WORD <wResolution>
Specifies the accuracy of the delay in milliseconds. The resolution of
the timer event increases with smaller <wResolution> values. To reduce
system overhead, use the maximum <wResolution> value appropriate for
your application.
LPTIMECALLBACK <lpFunction>
Specifies the procedure address of a callback function that is called
once upon expiration of a one-shot event or periodically upon expiration
of periodic events.
DWORD <dwUser>
Contains user-supplied callback data.
WORD <wFlags>
Specifies the type of timer event, using one of the following flags:
TIME_ONESHOT
Event occurs once, after <wPeriod> milliseconds.
TIME_PERIODIC
Event occurs every <wPeriod> milliseconds.
.returns
Returns an ID code that identifies the timer event. Returns NULL if the
timer event was not created. The ID code is also passed to the callback
function.
.comments
Using this function to generate a high-frequency periodic-delay event (with
a period less than 10 milliseconds) can consume a significant portion of the
system CPU bandwidth. Any call to %timeSetEvent% for a periodic-delay timer
must be paired with a call to %timeKillEvent%.
The callback function must reside in a DLL. You don't have to use
%MakeProcInstance% to get a procedure-instance address for the callback
function.
.head "Callback"
void FAR PASCAL %TimeFunc%(<wID>, <wMsg>, <dwUser>, <dw1>, <dw2>)
%TimeFunc% is a placeholder for the application-supplied function name. The
actual name must be exported by including it in the EXPORTS statement of the
module-definition file for the DLL.
%Parameters%
WORD <wID>
The ID of the timer event. This is the ID returned by %timeSetEvent%.
WORD <wMsg>
Not used.
DWORD <dwUser>
User instance data supplied to the <dwUser> parameter of
%timeSetEvent%.
DWORD <dw1>
Not used.
DWORD <dw2>
Not used.
%Comments%
Because the callback is accessed at interrupt time, it must reside in a DLL,
and its code segment must be specified as FIXED in the module-definition
file for the DLL. Any data that the callback accesses must be in a FIXED
data segment as well. The callback may not make any system calls except for
%PostMessage%, %timeGetSystemTime%, %timeGetTime%, %timeSetEvent%,
%timeKillEvent%, %midiOutShortMsg%, %midiOutLongMsg%, and %OutputDebugStr%.
.seealso
%timeKillEvent%, %timeBeginPeriod%, %timeEndPeriod%
.refpage waveInAddBuffer
WORD %waveInAddBuffer%(<hWaveIn>, <lpWaveInHdr>, <wSize>)
This function sends an input buffer to a waveform input device. When the
buffer is filled, it is sent back to the application.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
LPWAVEHDR <lpWaveInHdr>
Specifies a far pointer to a %WAVEHDR% structure that identifies the
buffer.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_UNPREPARED
<lpWaveInHdr> hasn't been prepared.
.endlist
.comments
The data buffer must be prepared with %waveInPrepareHeader% before it is
passed to %waveInAddBuffer%. The %WAVEHDR% data structure and the data
buffer pointed to by its %lpData% field must be allocated with %GlobalAlloc%
using the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with %GlobalLock%.
.seealso
%waveInPrepareHeader%
.refpage waveInClose
WORD %waveInClose%(<hWaveIn>)
This function closes the specified waveform input device.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device. If the function is
successful, the handle is no longer valid after this call.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_STILLPLAYING
There are still buffers in the queue.
.endlist
.comments
If there are input buffers that have been sent with %waveInAddBuffer%, and
haven't been returned to the application, the close operation will fail.
Call %waveInReset% to mark all pending buffers as done.
.seealso
%waveInOpen%, %waveInReset%
.refpage waveInGetDevCaps
WORD %waveInGetDevCaps%(<wDeviceID>, <lpCaps>, <wSize>)
This function queries a specified waveform input device to determine its
capabilities.
.parameters
WORD <wDeviceID>
Identifies the waveform input device.
LPWAVEINCAPS <lpCaps>
Specifies a far pointer to a %WAVEINCAPS% structure. This structure is
filled with information about the capabilities of the device.
WORD <wSize>
Specifies the size of the %WAVEINCAPS% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Use %waveInGetNumDevs% to determine the number of waveform input devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present. Only <wSize> bytes (or
less) of information is copied to the location pointed to by <lpCaps>. If
<wSize> is zero, nothing is copied, and the function returns zero.
.seealso
%waveInGetNumDevs%
.refpage waveInGetErrorText
WORD %waveInGetErrorText%(<wError>, <lpText>, <wSize>)
This function retrieves a textual description of the error identified by the
specified error number.
.parameters
WORD <wError>
Specifies the error number.
LPSTR <lpText>
Specifies a far pointer to the buffer to be filled with the textual
error description.
WORD <wSize>
Specifies the size of the buffer pointed to by <lpText>.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADERRNUM
Specified error number is out of range.
.endlist
.comments
If the textual error description is longer than the buffer, the description
is truncated. The returned string is always null-terminated. If <wSize> is
zero, nothing is copied, and the function returns zero. All error
descriptions are less than MAXERRORLENGTH characters long.
.refpage waveInGetID
WORD %waveInGetID%(<hWaveIn>, <lpwDeviceID>)
This function gets the device ID for a waveform input device.
.parameters
HWAVEIN <hWaveIn>
Specifies the handle to the waveform input device.
LPWORD <lpwDeviceID>
Specifies a pointer to the WORD-sized memory location to fill with the
device ID.
.returns
Returns zero if successful. Otherwise, it returns an error number. Possible
error returns are:
MMSYSERR_INVALHANDLE
The <hWaveIn> parameter specifies an invalid handle.
.refpage waveInGetNumDevs
WORD %waveInGetNumDevs%()
This function returns the number of waveform input devices.
.parameters
None
.returns
Returns the number of waveform input devices present in the system.
.seealso
%waveInGetDevCaps%
.refpage waveInGetPosition
WORD %waveInGetPosition%(<hWaveIn>, <lpInfo>, <wSize>)
This function retrieves the current input position of the specified waveform
input device.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
LPMMTIME <lpInfo>
Specifies a far pointer to an %MMTIME% structure.
WORD <wSize>
Specifies the size of the %MMTIME% structure.
.returns
Returns zero if the function was successful. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Before calling %waveInGetPosition%, set the %wType% field of the %MMTIME%
structure to indicate the time format that you desire. After calling
%waveInGetPosition%, be sure to check the %wType% field to determine if the
desired time format is supported. If the desired format is not supported,
%wType% will specify an alternative format.
The position is set to zero when the device is opened or reset.
.refpage waveInOpen
WORD %waveInOpen%(<lphWaveIn>, <wDeviceID>, <lpFormat>, <dwCallback>,
<dwCallbackInstance>, <dwFlags>)
This function opens a specified waveform input device for recording.
.parameters
LPHWAVEIN <lphWaveIn>
Specifies a far pointer to a HWAVEIN handle. This location is filled
with a handle identifying the opened waveform input device. Use this
handle to identify the device when calling other waveform input
functions. This parameter may be NULL if the WAVE_FORMAT_QUERY flag is
specified for <dwFlags>.
WORD <wDeviceID>
Identifies the waveform input device to open. Use a valid device ID or
the following flag:
WAVE_MAPPER
If this flag is specified, the function selects a waveform input device
capable of recording in the given format.
LPWAVEFORMAT <lpFormat>
Specifies a pointer to a %WAVEFORMAT% data structure that identifies the
desired format for recording waveform data.
DWORD <dwCallback>
Specifies the address of a callback function or a handle to a window
called during waveform recording to process messages related to the
progress of recording.
DWORD <dwCallbackInstance>
Specifies user instance data passed to the callback. This parameter is
not used with window callbacks.
DWORD <dwFlags>
Specifies flags for opening the device.
WAVE_FORMAT_QUERY
If this flag is specified, the device will be queried to determine if it
supports the given format but will not actually be opened.
CALLBACK_WINDOW
If this flag is specified, <dwCallback> is assumed to be a window
handle.
CALLBACK_FUNCTION
If this flag is specified, <dwCallback> is assumed to be a callback
procedure address.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_NODRIVER
The driver was not installed.
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_ALLOCATED
Specified resource is already allocated.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
WAVERR_BADFORMAT
Attempted to open with an unsupported wave format.
.endlist
.comments
Use %waveInGetNumDevs% to determine the number of waveform input devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present.
If a window is chosen to receive callback information, the following
messages are sent to the window procedure function to indicate the progress
of waveform input: %MM_WIM_OPEN%, %MM_WIM_CLOSE%, %MM_WIM_DATA%
If a function is chosen to receive callback information, the following
messages are sent to the function to indicate the progress of waveform
input: %WIM_OPEN%, %WIM_CLOSE%, %WIM_DATA%. The callback function must
reside in a DLL. You do not have to use %MakeProcInstance% to get a
procedure-instance address for the callback function.
.head "Callback"
void FAR PASCAL %WaveInFunc%(<hWaveIn>, <wMsg>, <dwInstance>, <dwParam1>,
<dwParam2>)
%WaveInFunc% is a placeholder for the application-supplied function name.
The actual name must be exported by including it in an EXPORTS statement in
the DLL's module-definition file.
%Parameters%
HWAVEIN <hWaveIn>
Specifies a handle to the waveform device associated with the callback.
WORD <wMsg>
Specifies a waveform input device.
DWORD <dwInstance>
Specifies the user instance data specified with %waveInOpen%.
DWORD <dwParam1>
Specifies a parameter for the message.
DWORD <dwParam2>
Specifies a parameter for the message.
%Comments%
Because the callback is accessed at interrupt time, it must reside in a DLL
and its code segment must be specified as FIXED in the module-definition
file for the DLL. Any data that the callback accesses must be in a FIXED
data segment as well. The callback may not make any system calls except for
%PostMessage%, %timeGetSystemTime%, %timeGetTime%, %timeSetEvent%,
%timeKillEvent%, %midiOutShortMsg%, %midiOutLongMsg%, and %OutputDebugStr%.
.seealso
%waveInClose%
.refpage waveInPrepareHeader
WORD %waveInPrepareHeader%(<hWaveIn>, <lpWaveInHdr>, <wSize>)
This function prepares a buffer for waveform input.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
LPWAVEHDR <lpWaveInHdr>
Specifies a pointer to a %WAVEHDR% structure that identifies the buffer
to be prepared.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
.endlist
.comments
The %WAVEHDR% data structure and the data block pointed to by its %lpData%
field must be allocated with %GlobalAlloc% using the GMEM_MOVEABLE and
GMEM_SHARE flags, and locked with %GlobalLock%. Preparing a header that has
already been prepared will have no effect, and the function will return
zero.
.seealso
%waveInUnprepareHeader%
.refpage waveInReset
WORD %waveInReset%(<hWaveIn>)
This function stops input on a given waveform input device and resets the
current position to 0. All pending buffers are marked as done and returned
to the application.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.seealso
%waveInStart%, %waveInStop%, %waveInAddBuffer%, %waveInClose%
.refpage waveInStart
WORD %waveInStart%(<hWaveIn>)
This function starts input on the specified waveform input device.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Buffers are returned to the client when full or when %waveInReset% is called
(the %dwBytesRecorded% field in the header will contain the actual length of
data). If there are no buffers in the queue, the data is thrown away without
notification to the client, and input continues.
Calling this function when input is already started has no effect, and the
function returns zero.
.seealso
%waveInStop%, %waveInReset%
.refpage waveInStop
WORD %waveInStop%(<hWaveIn>)
This function stops waveform input.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
If there are any buffers in the queue, the current buffer will be marked as
done (the %dwBytesRecorded% field in the header will contain the actual
length of data), but any empty buffers in the queue will remain there.
Calling this function when input is not started has no effect, and the
function returns zero.
.seealso
%waveInStart%, %waveInReset%
.refpage waveInUnprepareHeader
WORD %waveInUnprepareHeader%(<hWaveIn>, <lpWaveInHdr>, <wSize>)
This function cleans up the preparation performed by %waveInPrepareHeader%.
The function must be called after the device driver fills a data buffer and
returns it to the application. You must call this function before freeing
the data buffer.
.parameters
HWAVEIN <hWaveIn>
Specifies a handle to the waveform input device.
LPWAVEHDR <lpWaveInHdr>
Specifies a pointer to a %WAVEHDR% structure identifying the data buffer
to be cleaned up.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_STILLPLAYING
<lpWaveInHdr> is still in the queue.
.endlist
.comments
This function is the complementary function to %waveInPrepareHeader%. You
must call this function before freeing the data buffer with %GlobalFree%.
After passing a buffer to the device driver with %waveInAddBuffer%, you must
wait until the driver is finished with the buffer before calling
%waveInUnprepareHeader%. Unpreparing a buffer that has not been prepared has
no effect, and the function returns zero.
.seealso
%waveInPrepareHeader%
.refpage waveOutBreakLoop
WORD %waveOutBreakLoop%(<hWaveOut>)
This function breaks a loop on a given waveform output device and allows
playback to continue with the next block in the driver list.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Waveform looping is controlled by the %dwLoops% and %dwFlags% fields in the
%WAVEHDR% structures passed to the device with %waveOutWrite%. Use the
WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the %dwFlags% field to specify the
beginning and ending data blocks for looping.
To loop on a single block, specify both flags for the same block. To specify
the number of loops, use the %dwLoops% field in the %WAVEHDR% structure for
the first block in the loop.
The blocks making up the loop are played to the end before the loop is
terminated.
Calling this function when the nothing is playing or looping has no effect,
and the function returns zero.
.seealso
%waveOutWrite%, %waveOutPause%, %waveOutRestart%
.refpage waveOutClose
WORD %waveOutClose%(<hWaveOut>)
This function closes the specified waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device. If the function is
successful, the handle is no longer valid after this call.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_STILLPLAYING
There are still buffers in the queue.
.endlist
.comments
If the device is still playing a waveform, the close operation will fail.
Use %waveOutReset% to terminate waveform playback before calling
%waveOutClose%.
.seealso
%waveOutOpen%, %waveOutReset%
.refpage waveOutGetDevCaps
WORD %waveOutGetDevCaps%(<wDeviceID>, <lpCaps>, <wSize>)
This function queries a specified waveform device to determine its
capabilities.
.parameters
WORD <wDeviceID>
Identifies the waveform output device.
LPWAVEOUTCAPS <lpCaps>
Specifies a far pointer to a %WAVEOUTCAPS% structure. This structure is
filled with information about the capabilities of the device.
WORD <wSize>
Specifies the size of the %WAVEOUTCAPS% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Use %waveOutGetNumDevs% to determine the number of waveform output devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present. Only <wSize> bytes (or
less) of information is copied to the location pointed to by <lpCaps>. If
<wSize> is zero, nothing is copied, and the function returns zero.
.seealso
%waveOutGetNumDevs%
.refpage waveOutGetErrorText
WORD %waveOutGetErrorText%(<wError>, <lpText>, <wSize>)
This function retrieves a textual description of the error identified by the
specified error number.
.parameters
WORD <wError>
Specifies the error number.
LPSTR <lpText>
Specifies a far pointer to a buffer to be filled with the textual error
description.
WORD <wSize>
Specifies the length of the buffer pointed to by <lpText>.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADERRNUM
Specified error number is out of range.
.endlist
.comments
If the textual error description is longer than the specified buffer, the
description is truncated. The returned error string is always
null-terminated. If <wSize> is zero, nothing is copied, and the function
returns zero. All error descriptions are less than MAXERRORLENGTH characters
long.
.refpage waveOutGetID
WORD %waveOutGetID%(<hWaveOut>, <lpwDeviceID>)
This function gets the device ID for a waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies the handle to the waveform output device.
LPWORD <lpwDeviceID>
Specifies a pointer to the WORD-sized memory location to be filled with
the device ID.
.returns
Returns zero if successful. Otherwise, it returns an error number. Possible
error returns are:
MMSYSERR_INVALHANDLE
The <hWaveOut> parameter specifies an invalid handle.
.refpage waveOutGetNumDevs
WORD %waveOutGetNumDevs%()
This function retrieves the number of waveform output devices present in the
system.
.parameters
None
.returns
Returns the number of waveform output devices present in the system.
.seealso
%waveOutGetDevCaps%
.refpage waveOutGetPitch
WORD %waveOutGetPitch%(<hWaveOut>, <lpdwPitch>)
This function queries the the current pitch setting of a waveform output
device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPDWORD <lpdwPitch>
Specifies a far pointer to a location to be filled with the current
pitch multiplier setting. The pitch multiplier indicates the current
change in pitch from the original authored setting. The pitch multiplier
must be a positive value.
The pitch multiplier is specified as a fixed-point value. The high-order
word of the DWORD location contains the signed integer part of the
number, and the low-order word contains the fractional part. The
fraction is expressed as a WORD in which a value of 0x8000 represents
one half, and 0x4000 represents one quarter. For example, the value
0x00010000 specifies a multiplier of 1.0 (no pitch change), and a value
of 0x000F8000 specifies a multiplier of 15.5.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
.endlist
.comments
Changing the pitch does not change the playback rate, sample rate, or
playback time. Not all devices support pitch changes. To determine whether
the device supports pitch control, use the WAVECAPS_PITCH flag to test the
%dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
.seealso
%waveOutSetPitch%, %waveOutGetPlaybackRate%, %waveOutSetPlaybackRate%
.refpage waveOutGetPlaybackRate
WORD %waveOutGetPlaybackRate%(<hWaveOut>, <lpdwRate>)
This function queries the current playback rate setting of a waveform output
device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPDWORD <lpdwRate>
Specifies a far pointer to a location to be filled with the current
playback rate. The playback rate setting is a multiplier indicating the
current change in playback rate from the original authored setting. The
playback rate multiplier must be a positive value.
The rate is specified as a fixed-point value. The high-order word of the
DWORD location contains the signed integer part of the number, and the
low-order word contains the fractional part. The fraction is expressed
as a WORD in which a value of 0x8000 represents one half, and 0x4000
represents one quarter. For example, the value 0x00010000 specifies a
multiplier of 1.0 (no playback rate change), and a value of 0x000F8000
specifies a multiplier of 15.5.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
.endlist
.comments
Changing the playback rate does not change the sample rate but does change
the playback time.
Not all devices support playback rate changes. To determine whether a device
supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test
the %dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
.seealso
%waveOutSetPlaybackRate%, %waveOutSetPitch%, %waveOutGetPitch%
.refpage waveOutGetPosition
WORD %waveOutGetPosition%(<hWaveOut>, <lpInfo>, <wSize>)
This function retrieves the current playback position of the specified
waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPMMTIME <lpInfo>
Specifies a far pointer to an %MMTIME% structure.
WORD <wSize>
Specifies the size of the %MMTIME% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Before calling %waveOutGetPosition%, set the %wType% field of the MMTIME
structure to indicate the time format that you desire. After calling
%waveOutGetPosition%, check the %wType% field to determine if the desired
time format is supported. If the desired format is not supported, %wType%
will specify an alternative format.
The position is set to zero when the device is opened or reset.
.refpage waveOutGetVolume
WORD %waveOutGetVolume%(<wDeviceID>, <lpdwVolume>)
This function queries the current volume setting of a waveform output
device.
.parameters
WORD <wDeviceID>
Identifies the waveform output device.
LPDWORD <lpdwVolume>
Specifies a far pointer to a location to be filled with the current
volume setting. The low-order word of this location contains the left
channel volume setting, and the high-order word contains the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of the specified location contains the mono volume
level.
The full 16-bit setting(s) set with %waveOutSetVolume% is returned,
regardless of whether the device supports the full 16 bits of
volume-level control.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Not all devices support volume changes. To determine whether the device
supports volume control, use the WAVECAPS_VOLUME flag to test the
%dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the WAVECAPS_VOLUME flag to test the %dwSupport% field
of the %WAVEOUTCAPS% structure (filled by %waveOutGetDevCaps%).
.seealso
%waveOutSetVolume%
.refpage waveOutOpen
WORD %waveOutOpen%(<lphWaveOut>, <wDeviceID>, <lpFormat>, <dwCallback>,
<dwCallbackInstance>, <dwFlags>)
This function opens a specified waveform output device for playback.
.parameters
LPHWAVEOUT <lphWaveOut>
Specifies a far pointer to an HWAVEOUT handle. This location is filled
with a handle identifying the opened waveform output device. Use the
handle to identify the device when calling other waveform output
functions. This parameter may be NULL if the WAVE_FORMAT_QUERY flag is
specified for <dwFlags>.
WORD <wDeviceID>
Identifies the waveform output device to open. Use a valid device ID or
the following flag:
WAVE_MAPPER
If this flag is specified, the function selects a waveform output device
capable of playing the given format.
LPWAVEFORMAT <lpFormat>
Specifies a pointer to a %WAVEFORMAT% structure that identifies the
format of the waveform data to be sent to the waveform output device.
DWORD <dwCallback>
Specifies the address of a callback function or a handle to a window
called during waveform playback to process messages related to the
progress of the playback. Specify NULL for this parameter if no callback
is desired.
DWORD <dwCallbackInstance>
Specifies user instance data passed to the callback. This parameter is
not used with window callbacks.
DWORD <dwFlags>
Specifies flags for opening the device.
WAVE_FORMAT_QUERY
If this flag is specified, the device is be queried to determine if it
supports the given format but is not actually opened.
CALLBACK_WINDOW
If this flag is specified, <dwCallback> is assumed to be a window
handle.
CALLBACK_FUNCTION
If this flag is specified, <dwCallback> is assumed to be a callback
procedure address.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_BADDEVICEID
Specified device ID is out of range.
MMSYSERR_ALLOCATED
Specified resource is already allocated.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
WAVERR_BADFORMAT
Attempted to open with an unsupported wave format.
.endlist
.comments
Use %waveOutGetNumDevs% to determine the number of waveform output devices
present in the system. The device ID specified by <wDeviceID> varies from
zero to one less than the number of devices present.
The %WAVEFORMAT% structure pointed to by <lpFormat> may be extended to
include type-specific information for certain data formats. For example, for
PCM data, an extra WORD is added to specify the number of bits per sample.
Use the %PCMWAVEFORMAT% structure in this case.
If a window is chosen to receive callback information, the following
messages are sent to the window procedure function to indicate the progress
of waveform output: %MM_WOM_OPEN%, %MM_WOM_CLOSE%, %MM_WOM_DONE%
If a function is chosen to receive callback information, the following
messages are sent to the function to indicate the progress of waveform
output: %WOM_OPEN%, %WOM_CLOSE%, %WOM_DONE%. The callback function must
reside in a DLL. You do not have to use %MakeProcInstance% to get a
procedure-instance address for the callback function.
.head "Callback"
void FAR PASCAL %WaveOutFunc%(<hWaveOut>, <wMsg>, <dwInstance>, <dwParam1>,
<dwParam2>)
%WaveOutFunc% is a placeholder for the application-supplied function name.
The actual name must be exported by including it in an EXPORTS statement in
the DLL's module- definition file.
%Parameters%
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform device associated with the callback.
WORD <wMsg>
Specifies a waveform output message.
DWORD <dwInstance>
Specifies the user instance data specified with %waveOutOpen%.
DWORD <dwParam1>
Specifies a parameter for the message.
DWORD <dwParam2>
Specifies a parameter for the message.
%Comments%
Because the callback is accessed at interrupt time, it must reside in a DLL
and its code segment must be specified as FIXED in the module-definition
file for the DLL. Any data that the callback accesses must be in a FIXED
data segment as well. The callback may not make any system calls except for
%PostMessage%, %timeGetSystemTime%, %timeGetTime%, %timeSetEvent%,
%timeKillEvent%, %midiOutShortMsg%, %midiOutLongMsg%, and %OutputDebugStr%.
.seealso
%waveOutClose%
.refpage waveOutPause
WORD %waveOutPause%(<hWaveOut>)
This function pauses playback on a specified waveform output device. The
current playback position is saved. Use %waveOutRestart% to resume playback
from the current playback position.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Calling this function when the output is already paused has no effect, and
the function returns zero.
.seealso
%waveOutRestart%, %waveOutBreakLoop%
.refpage waveOutPrepareHeader
WORD %waveOutPrepareHeader%(<hWaveOut>, <lpWaveOutHdr>, <wSize>)
This function prepares a waveform data block for playback.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPWAVEHDR <lpWaveOutHdr>
Specifies a pointer to a %WAVEHDR% structure that identifies the data
block to be prepared.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOMEM
Unable to allocate or lock memory.
.endlist
.comments
The %WAVEHDR% data structure and the data block pointed to by its %lpData%
field must be allocated with %GlobalAlloc% using the GMEM_MOVEABLE and
GMEM_SHARE flags, and locked with %GlobalLock%. Preparing a header that has
already been prepared has no effect, and the function returns zero.
.seealso
%waveOutUnprepareHeader%
.refpage waveOutReset
WORD %waveOutReset%(<hWaveOut>)
This function stops playback on a given waveform output device and resets
the current position to 0. All pending playback buffers are marked as done
and returned to the application.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.seealso
%waveOutWrite%, %waveOutClose%
.refpage waveOutRestart
WORD %waveOutRestart%(<hWaveOut>)
This function restarts a paused waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
.endlist
.comments
Calling this function when the output is not paused has no effect, and the
function returns zero.
.seealso
%waveOutPause%, %waveOutBreakLoop%
.refpage waveOutSetPitch
WORD %waveOutSetPitch%(<hWaveOut>, <dwPitch>)
This function sets the pitch of a waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
DWORD <dwPitch>
Specifies the new pitch multiplier setting. The pitch multiplier setting
indicates the current change in pitch from the original authored
setting. The pitch multiplier must be a positive value.
The pitch multiplier is specified as a fixed-point value. The high-order
word location contains the signed integer part of the number, and the
low-order word contains the fractional part. The fraction is expressed
as a WORD in which a value of 0x8000 represents one half, and 0x4000
represents one quarter. For example, the value 0x00010000 specifies a
multiplier of 1.0 (no pitch change), and a value of 0x000F8000 specifies
a multiplier of 15.5.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
.endlist
.comments
Changing the pitch does not change the playback rate or the sample rate. The
playback time is also unchanged. Not all devices support pitch changes. To
determine whether the device supports pitch control, use the WAVECAPS_PITCH
flag to test the %dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
.seealso
%waveOutGetPitch%, %waveOutSetPlaybackRate%, %waveOutGetPlaybackRate%
.refpage waveOutSetPlaybackRate
WORD %waveOutSetPlaybackRate%(<hWaveOut>, <dwRate>)
This function sets the playback rate of a waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
DWORD <dwRate>
Specifies the new playback rate setting. The playback rate setting is a
multiplier indicating the current change in playback rate from the
original authored setting. The playback rate multiplier must be a
positive value.
The rate is specified as a fixed-point value. The high-order word
contains the signed integer part of the number, and the low-order word
contains the fractional part. The fraction is expressed as a WORD in
which a value of 0x8000 represents one half, and 0x4000 represents one
quarter. For example, the value 0x00010000 specifies a multiplier of 1.0
(no playback rate change), and a value of 0x000F8000 specifies a
multiplier of 15.5.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
.endlist
.comments
Changing the playback rate does not change the sample rate but does change
the playback time.
Not all devices support playback rate changes. To determine whether a device
supports playback rate changes, use the WAVECAPS_PLAYBACKRATE flag to test
the %dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
.seealso
%waveOutGetPlaybackRate%, %waveOutSetPitch%, %waveOutGetPitch%
.refpage waveOutSetVolume
WORD %waveOutSetVolume%(<wDeviceID>, <dwVolume>)
This function sets the volume of a waveform output device.
.parameters
WORD <wDeviceID>
Identifies the waveform output device.
DWORD <dwVolume>
Specifies the new volume setting. The low-order word contains the left
channel volume setting, and the high-order word contains the right
channel setting. A value of 0xFFFF represents full volume, and a value
of 0x0000 is silence.
If a device does not support both left and right volume control, the
low-order word of <dwVolume> specifies the volume level, and the
high-order word is ignored.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
MMSYSERR_NOTSUPPORTED
Function isn't supported.
MMSYSERR_NODRIVER
The driver was not installed.
.endlist
.comments
Not all devices support volume changes. To determine whether the device
supports volume control, use the WAVECAPS_VOLUME flag to test the
%dwSupport% field of the %WAVEOUTCAPS% structure (filled by
%waveOutGetDevCaps%).
To determine whether the device supports volume control on both the left and
right channels, use the WAVECAPS_LRVOLUME flag flag to test the %dwSupport%
field of the %WAVEOUTCAPS% structure (filled by %waveOutGetDevCaps%).
Most devices don't support the full 16 bits of volume level control and will
not use the high-order bits of the requested volume setting. For example,
for a device that supports 4 bits of volume control, requested volume level
values of 0x4000, 0x4fff, and 0x43be all produce the same physical volume
setting, 0x4000. The %waveOutGetVolume% function returns the full 16-bit
setting set with %waveOutSetVolume%.
Volume settings are interpreted logarithmically. This means the perceived
increase in volume is the same when increasing the volume level from 0x5000
to 0x6000 as it is from 0x4000 to 0x5000.
.seealso
%waveOutGetVolume%
.refpage waveOutUnprepareHeader
WORD %waveOutUnprepareHeader%(<hWaveOut>, <lpWaveOutHdr>, <wSize>)
This function cleans up the preparation performed by %waveOutPrepareHeader%.
The function must be called after the device driver is finished with a data
block. You must call this function before freeing the data buffer.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPWAVEHDR <lpWaveOutHdr>
Specifies a pointer to a %WAVEHDR% structure identifying the data block
to be cleaned up.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_STILLPLAYING
<lpWaveOutHdr> is still in the queue.
.endlist
.comments
This function is the complementary function to %waveOutPrepareHeader%. You
must call this function before freeing the data buffer with %GlobalFree%.
After passing a buffer to the device driver with %waveOutWrite%, you must
wait until the driver is finished with the buffer before calling
%waveOutUnprepareHeader%.
Unpreparing a buffer that has not been prepared has no effect, and the
function returns zero.
.seealso
%waveOutPrepareHeader%
.refpage waveOutWrite
WORD %waveOutWrite%(<hWaveOut>, <lpWaveOutHdr>, <wSize>)
This function sends a data block to the specified waveform output device.
.parameters
HWAVEOUT <hWaveOut>
Specifies a handle to the waveform output device.
LPWAVEHDR <lpWaveOutHdr>
Specifies a far pointer to a %WAVEHDR% structure containing information
about the data block.
WORD <wSize>
Specifies the size of the %WAVEHDR% structure.
.returns
Returns zero if the function was successful. Otherwise, it returns an error
number. Possible error returns are:
.list Value Meaning
MMSYSERR_INVALHANDLE
Specified device handle is invalid.
WAVERR_UNPREPARED
<lpWaveOutHdr> hasn't been prepared.
.endlist
.comments
The data buffer must be prepared with %waveOutPrepareHeader% before it is
passed to %waveOutWrite%. The %WAVEHDR% data structure and the data buffer
pointed to by its %lpData% field must be allocated with %GlobalAlloc% using
the GMEM_MOVEABLE and GMEM_SHARE flags, and locked with %GlobalLock%. Unless
the device is paused by calling %waveOutPause%, playback begins when the
first data block is sent to the device.
.seealso
%waveOutPrepareHeader%, %waveOutPause%, %waveOutReset%, %waveOutRestart%