.refpage auxGetDevCaps WORD %auxGetDevCaps%(, , ) This function queries a specified auxiliary output device to determine its capabilities. .parameters WORD Identifies the auxiliary output device to be queried. LPAUXCAPS Specifies a far pointer to an AUXCAPS structure. This structure is filled with information about the capabilities of the device. WORD 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 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%(, ) This function returns the current volume setting of an auxiliary output device. .parameters WORD Identifies the auxiliary output device to be queried. LPDWORD 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%(, ) This function sets the volume in an auxiliary output device. .parameters WORD 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 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 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%() 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 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%(, , ) This function returns a textual description of the specified MCI error. .parameters DWORD Specifies the error code returned by %mciSendCommand% or %mciSendString%. LPSTR Specifies a pointer to a buffer that is filled with a textual description of the specified error. WORD Specifies the length of the buffer pointed to by . .returns Returns TRUE if successful. Otherwise, the given error code was not known. .refpage mciSendCommand DWORD %mciSendCommand%(, , , ) This function sends a command message to the specified MCI device. .parameters WORD Specifies the device ID of the MCI device to receive the command. This parameter is not used with the %MCI_OPEN% command. WORD Specifies the command message. DWORD Specifies flags for the command. DWORD 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 . .seealso %mciGetErrorString%, %mciSendString% .refpage mciSendString DWORD %mciSendString%(, , , ) 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 Specifies an MCI command string. LPSTR Specifies a buffer for return information. If no return information is needed, you can specify NUL for this parameter. WORD Specifies the size of the return buffer specified by . HANDLE 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%(, , ) 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 Specifies the device ID of the MCI device to which the yield procedure is to be assigned. YIELDPROC Specifies the callback procedure to be called when the given device is yielding. Specify a NULL value to disable any existing yield procedure. DWORD 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%(, ) %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 Specifies the device ID of the MCI device. DWORD Specifies the application-supplied yield data originally supplied in the 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%() 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 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%(, , ) 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 Specifies a handle to the MIDI input device. LPMIDIHDR Specifies a far pointer to a %MIDIHDR% structure that identifies the buffer. WORD 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 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%() This function closes the specified MIDI input device. .parameters 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%(, , ) This function queries a specified MIDI input device to determine its capabilities. .parameters WORD Identifies the MIDI input device. LPMIDIINCAPS Specifies a far pointer to a %MIDIINCAPS% data structure. This structure is filled with information about the capabilities of the device. WORD 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 varies from zero to one less than the number of devices present. Only bytes (or less) of information is copied to the location pointed to by . If is zero, nothing is copied, and the function returns zero. .seealso %midiInGetNumDevs% .refpage midiInGetErrorText WORD %midiInGetErrorText%(, , ) This function retrieves a textual description of the error identified by the specified error number. .parameters WORD Specifies the error number. LPSTR Specifies a far pointer to the buffer to be filled with the textual error description. WORD Specifies the length of buffer pointed to by . .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 is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long. .refpage midiInGetID WORD %midiInGetID%(, ) This function gets the device ID for a MIDI input device. .parameters HMIDIIN Specifies the handle to the MIDI input device. LPWORD 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 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%(, , , , ) This function opens a specified MIDI input device. .parameters 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 Identifies the MIDI input device to be opened. DWORD Specifies the address of a fixed callback function or a handle to a window called with information about incoming MIDI messages. DWORD Specifies user instance data passed to the callback function. This parameter is not used with window callbacks. DWORD Specifies a callback flag for opening the device. CALLBACK_WINDOW If this flag is specified, is assumed to be a window handle. CALLBACK_FUNCTION If this flag is specified, 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 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%(, , , , ) %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 Specifies a handle to the MIDI input device. WORD Specifies a MIDI input message. DWORD Specifies the instance data supplied with %midiInOpen%. DWORD Specifies a parameter for the message. DWORD 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%(, , ) This function prepares a buffer for MIDI input. .parameters HMIDIIN Specifies a handle to the MIDI input device. LPMIDIHDR Specifies a pointer to a %MIDIHDR% structure that identifies the buffer to be prepared. WORD 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%() This function stops input on a given MIDI input device and marks all pending input buffers as done. .parameters 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%() This function starts MIDI input on the specified MIDI input device. .parameters 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%() This function terminates MIDI input on the specified MIDI input device. .parameters 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%(, , ) 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 Specifies a handle to the MIDI input device. LPMIDIHDR Specifies a pointer to a %MIDIHDR% structure identifying the data buffer to be cleaned up. WORD 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 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%(, , , ) 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 Specifies a handle to the opened MIDI output device. This device should be an internal MIDI synthesizer. WORD Specifies which drum patch number should be used. Currently, this parameter must be set to zero. LPKEYARRAY Specifies a pointer to a %KEYARRAY% array indicating the key numbers of the specified percussion patches to be cached or uncached. WORD 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%(, , , ) 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 Specifies a handle to the opened MIDI output device. This device must be an internal MIDI synthesizer. WORD Specifies which bank of patches should be used. Currently, this parameter must be set to zero. LPPATCHARRAY Specifies a pointer to a %PATCHARRAY% array indicating the patches to be cached or uncached. WORD 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%() This function closes the specified MIDI output device. .parameters 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%(, , ) This function queries a specified MIDI output device to determine its capabilities. .parameters WORD Identifies the MIDI output device. LPMIDIOUTCAPS Specifies a far pointer to a %MIDIOUTCAPS% structure. This structure is filled with information about the capabilities of the device. WORD 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 varies from zero to one less than the number of devices present. Only bytes (or less) of information is copied to the location pointed to by . If is zero, nothing is copied, and the function returns zero. .seealso %midiOutGetNumDevs% .refpage midiOutGetErrorText WORD %midiOutGetErrorText%(, , ) This function retrieves a textual description of the error identified by the specified error number. .parameters WORD Specifies the error number. LPSTR Specifies a far pointer to a buffer to be filled with the textual error description. WORD Specifies the length of the buffer pointed to by . .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 is zero, nothing is copied, and the function returns MMSYSERR_NOERROR. All error descriptions are less than MAXERRORLENGTH characters long. .refpage midiOutGetID WORD %midiOutGetID%(, ) This function gets the device ID for a MIDI output device. .parameters HMIDIOUT Specifies the handle to the MIDI output device. LPWORD 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 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%(, ) This function returns the current volume setting of a MIDI output device. .parameters WORD Identifies the MIDI output device. LPDWORD 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%(, , ) 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 Specifies a handle to the MIDI output device. LPMIDIHDR Specifies a far pointer to a %MIDIHDR% structure that identifies the MIDI data buffer. WORD 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 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%(, , , , ) This function opens a specified MIDI output device for playback. .parameters 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 Identifies the MIDI output device that is to be opened. DWORD 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 Specifies user instance data passed to the callback. This parameter is not used with window callbacks. DWORD Specifies a callback flag for opening the device. CALLBACK_WINDOW If this flag is specified, is assumed to be a window handle. CALLBACK_FUNCTION If this flag is specified, 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 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%(, , , , ) %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 Specifies a handle to the MIDI device associated with the callback. WORD Specifies a MIDI output message. DWORD Specifies the instance data supplied with %midiOutOpen%. DWORD Specifies a parameter for the message. DWORD 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%(, , ) This function prepares a MIDI system exclusive data block for output. .parameters HMIDIOUT Specifies a handle to the MIDI output device. LPMIDIHDR Specifies a far pointer to a %MIDIHDR% structure that identifies the data block to be prepared. WORD 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%() This function turns off all notes on all MIDI channels for the specified MIDI output device. .parameters 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%(, ) This function sets the volume of a MIDI output device. .parameters WORD Identifies the MIDI output device. DWORD 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 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%(, ) 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 Specifies a handle to the MIDI output device. DWORD 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%(, , ) 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 Specifies a handle to the MIDI output device. LPMIDIHDR Specifies a pointer to a %MIDIHDR% structure identifying the buffer to be cleaned up. WORD 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 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%(, , ) 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 Specifies the file handle for a file opened with %mmioOpen%. LPMMIOINFO Specifies a pointer to the %MMIOINFO% structure obtained with %mmioGetInfo%. UINT 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%(, , ) This function ascends out of a chunk in a RIFF file descended into with %mmioDescend% or created with %mmioCreateChunk%. .parameters HMMIO Specifies the file handle of an open RIFF file. LPMMCKINFO Specifies a pointer to a caller-supplied %MMCKINFO% structure previously filled by %mmioDescend% or %mmioCreateChunk%. UINT 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 , 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%(, ) This function closes a file opened with %mmioOpen%. .parameters HMMIO Specifies the file handle of the file to close. UINT 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%(, , ) 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 Specifies the file handle of an open RIFF file. LPMMCKINFO 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 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 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%(, , , ) This function descends into a chunk of a RIFF file opened with %mmioOpen%. It can also search for a given chunk. .parameters HMMIO Specifies the file handle of an open RIFF file. LPMMCKINFO 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 , 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 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 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 to NULL if no parent chunk is being specified. UINT 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%(, ) This function writes the I/O buffer of a file to disk, if the I/O buffer has been written to. .parameters HMMIO Specifies the file handle of a file opened with %mmioOpen%. UINT 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%(, , , ) This macro converts four characters to to a DWORD code. .parameters CHAR The first character of the four-character code. CHAR The second character of the four-character code. CHAR The third character of the four-character code. CHAR 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%(, , ) 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 Specifies the file handle of the file. 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 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%(, , ) 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 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 Specifies the address of the I/O procedure to install. To remove or locate an I/O procedure, set this parameter to NULL. DWORD 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 . You don't need to get a procedure-instance address if the I/O procedure resides in a DLL. .head "Callback" LONG %IOProc%(, , , ) %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 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 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 Specifies a parameter for the message. LONG Specifies a parameter for the message. %Return Value% The return value depends on the message specified by . 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%(, , ) 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 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 to NULL. 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 is not NULL, all unused fields of the %MMIOINFO% structure it references must be set to zero, including the reserved fields. DWORD 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, 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 is not NULL, then its %wError% field will contain extended error information returned by the I/O procedure. .comments If 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 , 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 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 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%(, , ) This function reads a specified number of bytes from a file opened with %mmioOpen%. .parameters HMMIO Specifies the file handle of the file to be read. LPSTR Specifies a pointer to a buffer to contain the data read from the file. LONG 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%(, , ) 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 Specifies the file handle of the file to seek in. LONG Specifies an offset to change the file position. int Specifies how the offset specified by is interpreted. Contains one of the following flags: SEEK_SET Seeks to bytes from the beginning of the file. SEEK_CUR Seeks to bytes from the current file position. SEEK_END Seeks to 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 set to zero and set to SEEK_END. .refpage mmioSendMessage LRESULT %mmioSendMessage%(, , , ) This function sends a message to the I/O procedure associated with the specified file. .parameters HMMIO Specifies the file handle for a file opened with %mmioOpen%. UINT Specifies the message to send to the I/O procedure. LONG Specifies a parameter for the message. LONG 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%(, , , ) This function enables or disables buffered I/O, or changes the buffer or buffer size for a file opened with %mmioOpen%. .parameters HMMIO Specifies the file handle of the file. LPSTR 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 Specifies the size of the caller-supplied buffer, or the size of the buffer for %mmioSetBuffer% to allocate. UINT 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 to NULL and to the desired buffer size. To supply your own buffer, set to point to the buffer, and set to the size of the buffer. To disable buffered I/O, set to NULL and to zero. If buffered I/O is already enabled using an internal buffer, you can reallocate the buffer to a different size by setting to NULL and to the new buffer size. The contents of the buffer may be changed after resizing. .refpage mmioSetInfo MMRESULT %mmioSetInfo%(, , ) 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 Specifies the file handle of the file. LPMMIOINFO Specifies a pointer to an %MMIOINFO% structure filled with information with %mmioGetInfo%. UINT 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%(, ) This function converts a null-terminated string to a four-character code. .parameters LPSTR Specifies a pointer to a null-terminated string to a four-character code. UINT 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 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%(, , ) This function writes a specified number of bytes to a file opened with %mmioOpen%. .parameters HMMIO Specifies the file handle of the file. LPSTR Specifies a pointer to the buffer to be written to the file. LONG 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%(, ) 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 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 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 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 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 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, 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%() 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 Specifies the minimum timer-event resolution that the application or driver will use. .returns Returns zero if successful. Returns TIMERR_NOCANDO if the specified resolution value is out of range. .comments For each call to %timeBeginPeriod%, you must call %timeEndPeriod% with a matching 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%() 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 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 resolution value is out of range. .comments For each call to %timeBeginPeriod%, you must call %timeEndPeriod% with a matching 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%(, ) This function queries the timer device to determine its capabilities. .parameters LPTIMECAPS Specifies a far pointer to a %TIMECAPS% structure. This structure is filled with information about the capabilities of the timer device. WORD 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%(, ) This function retrieves the system time in milliseconds. The system time is the time elapsed since Windows was started. .parameters LPMMTIME Specifies a far pointer to an %MMTIME% data structure. WORD 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%() This functions destroys a specified timer callback event. .parameters WORD 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 must be an ID returned by %timeSetEvent%. .seealso %timeSetEvent% .refpage timeSetEvent WORD %timeSetEvent%(, , , , ) 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 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 Specifies the accuracy of the delay in milliseconds. The resolution of the timer event increases with smaller values. To reduce system overhead, use the maximum value appropriate for your application. LPTIMECALLBACK 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 Contains user-supplied callback data. WORD Specifies the type of timer event, using one of the following flags: TIME_ONESHOT Event occurs once, after milliseconds. TIME_PERIODIC Event occurs every 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%(, , , , ) %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 The ID of the timer event. This is the ID returned by %timeSetEvent%. WORD Not used. DWORD User instance data supplied to the parameter of %timeSetEvent%. DWORD Not used. DWORD 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%(, , ) 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 Specifies a handle to the waveform input device. LPWAVEHDR Specifies a far pointer to a %WAVEHDR% structure that identifies the buffer. WORD 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 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%() This function closes the specified waveform input device. .parameters 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%(, , ) This function queries a specified waveform input device to determine its capabilities. .parameters WORD Identifies the waveform input device. LPWAVEINCAPS Specifies a far pointer to a %WAVEINCAPS% structure. This structure is filled with information about the capabilities of the device. WORD 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 varies from zero to one less than the number of devices present. Only bytes (or less) of information is copied to the location pointed to by . If is zero, nothing is copied, and the function returns zero. .seealso %waveInGetNumDevs% .refpage waveInGetErrorText WORD %waveInGetErrorText%(, , ) This function retrieves a textual description of the error identified by the specified error number. .parameters WORD Specifies the error number. LPSTR Specifies a far pointer to the buffer to be filled with the textual error description. WORD Specifies the size of the buffer pointed to by . .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 is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long. .refpage waveInGetID WORD %waveInGetID%(, ) This function gets the device ID for a waveform input device. .parameters HWAVEIN Specifies the handle to the waveform input device. LPWORD 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 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%(, , ) This function retrieves the current input position of the specified waveform input device. .parameters HWAVEIN Specifies a handle to the waveform input device. LPMMTIME Specifies a far pointer to an %MMTIME% structure. WORD 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%(, , , , , ) This function opens a specified waveform input device for recording. .parameters 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 . WORD 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 Specifies a pointer to a %WAVEFORMAT% data structure that identifies the desired format for recording waveform data. DWORD 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 Specifies user instance data passed to the callback. This parameter is not used with window callbacks. DWORD 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, is assumed to be a window handle. CALLBACK_FUNCTION If this flag is specified, 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 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%(, , , , ) %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 Specifies a handle to the waveform device associated with the callback. WORD Specifies a waveform input device. DWORD Specifies the user instance data specified with %waveInOpen%. DWORD Specifies a parameter for the message. DWORD 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%(, , ) This function prepares a buffer for waveform input. .parameters HWAVEIN Specifies a handle to the waveform input device. LPWAVEHDR Specifies a pointer to a %WAVEHDR% structure that identifies the buffer to be prepared. WORD 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%() 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 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%() This function starts input on the specified waveform input device. .parameters 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%() This function stops waveform input. .parameters 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%(, , ) 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 Specifies a handle to the waveform input device. LPWAVEHDR Specifies a pointer to a %WAVEHDR% structure identifying the data buffer to be cleaned up. WORD 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 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%() 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 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%() This function closes the specified waveform output device. .parameters 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%(, , ) This function queries a specified waveform device to determine its capabilities. .parameters WORD Identifies the waveform output device. LPWAVEOUTCAPS Specifies a far pointer to a %WAVEOUTCAPS% structure. This structure is filled with information about the capabilities of the device. WORD 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 varies from zero to one less than the number of devices present. Only bytes (or less) of information is copied to the location pointed to by . If is zero, nothing is copied, and the function returns zero. .seealso %waveOutGetNumDevs% .refpage waveOutGetErrorText WORD %waveOutGetErrorText%(, , ) This function retrieves a textual description of the error identified by the specified error number. .parameters WORD Specifies the error number. LPSTR Specifies a far pointer to a buffer to be filled with the textual error description. WORD Specifies the length of the buffer pointed to by . .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 is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long. .refpage waveOutGetID WORD %waveOutGetID%(, ) This function gets the device ID for a waveform output device. .parameters HWAVEOUT Specifies the handle to the waveform output device. LPWORD 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 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%(, ) This function queries the the current pitch setting of a waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. LPDWORD 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%(, ) This function queries the current playback rate setting of a waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. LPDWORD 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%(, , ) This function retrieves the current playback position of the specified waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. LPMMTIME Specifies a far pointer to an %MMTIME% structure. WORD 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%(, ) This function queries the current volume setting of a waveform output device. .parameters WORD Identifies the waveform output device. LPDWORD 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%(, , , , , ) This function opens a specified waveform output device for playback. .parameters 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 . WORD 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 Specifies a pointer to a %WAVEFORMAT% structure that identifies the format of the waveform data to be sent to the waveform output device. DWORD 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 Specifies user instance data passed to the callback. This parameter is not used with window callbacks. DWORD 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, is assumed to be a window handle. CALLBACK_FUNCTION If this flag is specified, 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 varies from zero to one less than the number of devices present. The %WAVEFORMAT% structure pointed to by 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%(, , , , ) %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 Specifies a handle to the waveform device associated with the callback. WORD Specifies a waveform output message. DWORD Specifies the user instance data specified with %waveOutOpen%. DWORD Specifies a parameter for the message. DWORD 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%() 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 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%(, , ) This function prepares a waveform data block for playback. .parameters HWAVEOUT Specifies a handle to the waveform output device. LPWAVEHDR Specifies a pointer to a %WAVEHDR% structure that identifies the data block to be prepared. WORD 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%() 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 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%() This function restarts a paused waveform output device. .parameters 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%(, ) This function sets the pitch of a waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. DWORD 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%(, ) This function sets the playback rate of a waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. DWORD 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%(, ) This function sets the volume of a waveform output device. .parameters WORD Identifies the waveform output device. DWORD 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 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%(, , ) 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 Specifies a handle to the waveform output device. LPWAVEHDR Specifies a pointer to a %WAVEHDR% structure identifying the data block to be cleaned up. WORD 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 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%(, , ) This function sends a data block to the specified waveform output device. .parameters HWAVEOUT Specifies a handle to the waveform output device. LPWAVEHDR Specifies a far pointer to a %WAVEHDR% structure containing information about the data block. WORD 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 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%