acmStreamOpen function (msacm.h)
The acmStreamOpen function opens an ACM conversion stream. Conversion streams are used to convert data from one specified audio format to another.
Syntax
MMRESULT ACMAPI acmStreamOpen(
LPHACMSTREAM phas,
HACMDRIVER had,
LPWAVEFORMATEX pwfxSrc,
LPWAVEFORMATEX pwfxDst,
LPWAVEFILTER pwfltr,
DWORD_PTR dwCallback,
DWORD_PTR dwInstance,
DWORD fdwOpen
);
Parameters
phas
Pointer to a handle that will receive the new stream handle that can be used to perform conversions. This handle is used to identify the stream in calls to other ACM stream conversion functions. If the ACM_STREAMOPENF_QUERY flag is specified, this parameter should be NULL.
had
Handle to an ACM driver. If this handle is specified, it identifies a specific driver to be used for a conversion stream. If this parameter is NULL, all suitable installed ACM drivers are queried until a match is found.
pwfxSrc
Pointer to a WAVEFORMATEX structure that identifies the desired source format for the conversion.
pwfxDst
Pointer to a WAVEFORMATEX structure that identifies the desired destination format for the conversion.
pwfltr
Pointer to a WAVEFILTER structure that identifies the desired filtering operation to perform on the conversion stream. If no filtering operation is desired, this parameter can be NULL. If a filter is specified, the source (pwfxSrc) and destination (pwfxDst) formats must be the same.
dwCallback
Pointer to a callback function, a handle of a window, or a handle of an event. A callback function will be called only if the conversion stream is opened with the ACM_STREAMOPENF_ASYNC flag. A callback function is notified when the conversion stream is opened or closed and after each buffer is converted. If the conversion stream is opened without the ACM_STREAMOPENF_ASYNC flag, this parameter should be set to zero.
dwInstance
User-instance data passed to the callback function specified by the dwCallback parameter. This parameter is not used with window and event callbacks. If the conversion stream is opened without the ACM_STREAMOPENF_ASYNC flag, this parameter should be set to zero.
fdwOpen
Flags for opening the conversion stream. The following values are defined.
[ACMSTREAMHEADER](./ns-msacm-acmstreamheader.md) structure for the ACMSTREAMHEADER_STATUSF_DONE flag.| Value | Meaning |
|---|---|
| ACM_STREAMOPENF_ASYNC | |
| ACM_STREAMOPENF_NONREALTIME | ACM will not consider time constraints when converting the data. By default, the driver will attempt to convert the data in real time. For some formats, specifying this flag might improve the audio quality or other characteristics. |
| ACM_STREAMOPENF_QUERY | ACM will be queried to determine whether it supports the given conversion. A conversion stream will not be opened, and no handle will be returned in the phas parameter. |
| CALLBACK_EVENT | The dwCallback parameter is a handle of an event. |
| CALLBACK_FUNCTION | The dwCallback parameter is a callback procedure address. The function prototype must conform to the acmStreamConvertCallback prototype. |
| CALLBACK_WINDOW | The dwCallback parameter is a window handle. |
Return value
Returns zero if successful or an error otherwise. Possible error values include the following.
| Return code | Description |
|---|---|
|
The requested operation cannot be performed. |
|
At least one flag is invalid. |
|
The specified handle is invalid. |
|
At least one parameter is invalid. |
|
The system is unable to allocate resources. |
Remarks
If an ACM driver cannot perform real-time conversions and the ACM_STREAMOPENF_NONREALTIME flag is not specified for the fdwOpen parameter, the open operation will fail returning an ACMERR_NOTPOSSIBLE error code. An application can use the ACM_STREAMOPENF_QUERY flag to determine if real-time conversions are supported for input.
If an application uses a window to receive callback information, the MM_ACM_OPEN, MM_ACM_CLOSE, and MM_ACM_DONE messages are sent to the window procedure function to indicate the progress of the conversion stream. In this case, the ACMSTREAMHEADER structure for MM_ACM_DONE, but it is not used for MM_ACM_OPEN and MM_ACM_CLOSE.
If an application uses a function to receive callback information, the MM_ACM_OPEN, MM_ACM_CLOSE, and MM_ACM_DONE messages are sent to the function to indicate the progress of waveform-audio output. The callback function must reside in a dynamic-link library (DLL).
If an application uses an event for callback notification, the event is signaled to indicate the progress of the conversion stream. The event will be signaled when a stream is opened, after each buffer is converted, and when the stream is closed.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | msacm.h |
| Library | Msacm32.lib |
| DLL | Msacm32.dll |