SpiAssociate
The SpiAssociate function connects a data object (such as a file or a memory buffer) with a specific stream handler. This determines what data will be processed by the stream handler for playback or recording.
Syntax
#include <os2.h> rc = SpiAssociate(hstream, hid, pacb);
Parameters
- hstream (HSTREAM) - input
- The handle of the stream created by SpiCreateStream.
- hid (HID) - input
- The Stream Handler ID (source or target) that will manage the data object.
- pacb (PACB) - input
- A pointer to an Associate Control Block (ACB). The structure of this block depends on the object type being associated (e.g., `ACB_MMIO` for files, `ACB_MEM_SINGLE` for memory).
Return Value
- rc (ULONG) - returns
- Return codes indicating success or the type of failure:
- NO_ERROR: Success.
- ERROR_INVALID_STREAM: Invalid stream handle.
- ERROR_INVALID_HID: Invalid handler ID.
- ERROR_INVALID_OBJTYPE: The object type in the ACB is unknown.
- ERROR_STREAM_NOT_STOP: The stream must be stopped to perform an association.
- ERROR_INVALID_BUFFER_SIZE: Invalid ACB size.
- FAILURE: Stream handler-specific error.
Remarks
After a stream is created, it is essentially an empty pipeline. SpiAssociate provides the "content" for that pipeline.
- **Timing**: This function is only valid when the stream is in a **stopped** state (initial creation, discard stop, or flush stop) or has reached the **end-of-stream**. It cannot be called while the stream is active or paused.
- **Preroll**: If a stream has been prerolled but not yet started, an association attempt will return an error.
- **Stream Time**: Associating a new object does **not** reset the stream time to zero. Furthermore, the existing stream time becomes invalid. You must call SpiSeekStream after an association to synchronize the device and set the correct starting time.
Example Code
The following code demonstrates associating a digital audio file (opened via MMIO) with a source stream handler.
#define INCL_ERRORS
#include <os2.h>
#include <os2me.h>
ULONG ulRC; /* Error return code */
HID hidSource; /* Source handler ID */
HSTREAM hStream; /* Stream handle */
HMMIO hmmioIn; /* Handle to MMIO file */
ACB_MMIO acb; /* Associate control block*/
/* 1. Open the audio file using MMIO */
hmmioIn = mmioOpen("C:\\DATA\\SOUND.WAV", NULL, MMIO_READ | MMIO_DENYNONE);
if (!hmmioIn) {
return(ERROR_FILE_NOT_FOUND);
}
/* 2. Initialize the Associate Control Block (ACB) */
acb.ulACBLen = sizeof(ACB_MMIO);
acb.ulObjType = ACBTYPE_MMIO;
acb.hmmio = hmmioIn;
/* 3. Associate the file with the source stream handler */
ulRC = SpiAssociate(hStream, hidSource, (PACB)&acb);
if (ulRC) {
return (ulRC);
}
Related Functions
Related Messages
- SHC_ASSOCIATE