acmStreamOpen

The acmStreamOpen function opens an ACM conversion stream. Conversion streams are used to convert data from one specified audio format to another.

MMRESULT acmStreamOpen(
  LPHACMSTREAM phas,    
  HACMDRIVER had,       
  LPWAVEFORMATEX pwfxSrc,  
  LPWAVEFORMATEX pwfxDst,  
  LPWAVEFILTER pwfltr,  
  DWORD dwCallback,     
  DWORD dwInstance,     
  DWORD fdwOpen         
);
 

Parameters

phas

Address of 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 of 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

Address of a WAVEFORMATEX structure that identifies the desired source format for the conversion.

pwfxDst

Address of a WAVEFORMATEX structure that identifies the desired destination format for the conversion.

pwfltr

Address of 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

Address of 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:

ACM_STREAMOPENF_ASYNC

Stream conversion should be performed asynchronously. If this flag is specified, the application can use a callback function to be notified when the conversion stream is opened and closed and after each buffer is converted. In addition to using a callback function, an application can examine the fdwStatus member of the ACMSTREAMHEADER structure for the ACMSTREAMHEADER_STATUSF_DONE flag.

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 Values

Returns zero if successful or an error otherwise. Possible error values include the following:

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 wParam parameter identifies the HACMSTREAM handle. The lParam parameter identifies 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.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in msacm.h.
  Import Library: Use msacm32.lib.

See Also

Audio Compression Manager Overview, Audio Compression Functions, WAVEFORMATEX, WAVEFILTER, ACMSTREAMHEADER, acmStreamConvertCallback