SpiDisableSync

The SpiDisableSync function dissolves a synchronization group. By specifying the master stream's handle, the relationship between that master and all its associated slave streams is terminated.

Syntax

#include <os2.h>

rc = SpiDisableSync(hstreamMaster);

Parameters

hstreamMaster (HSTREAM) - input

The handle of the stream currently acting as the master for the synchronization group. This handle uniquely identifies the group to be dismantled.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

• NO_ERROR: Success.
• ERROR_INVALID_FUNCTION: Invalid function requested.
• ERROR_INVALID_STREAM: The provided stream handle is not valid.
• ERROR_STREAM_NOTMASTER: The specified handle is a valid stream, but it is not currently registered as a synchronization master.
• ERROR_STREAM_PREROLLING: The group cannot be disabled because one or more streams in the group are currently in a preroll state.
• FAILURE: Stream handler-specific error.

Remarks

Calling SpiDisableSync stops the Sync/Stream Manager from passing synchronization pulses from the master to the slaves.

• **State of Streams**: Disabling synchronization does not stop the individual streams from playing or recording; it simply removes the real-time alignment constraint between them. They will continue to run independently based on their own internal clocks.
• **Master Reassignment**: If you need to change the master of a group or add/remove specific slaves, you must first call SpiDisableSync to dissolve the existing group and then use SpiEnableSync to establish the new configuration.
• **Cleanup**: It is good practice to disable synchronization before destroying the streams in a group via SpiDestroyStream.

Example Code

The following example demonstrates how to dissolve a synchronization group using the master stream handle.

#include <os2.h>
#include <os2me.h>

ULONG   ulRC;          /* Error return code      */
HSTREAM hStream1;      /* Master stream handle   */

/* ... Streams were previously created and synchronized ... */

/* 
 * Disable synchronization. 
 * hStream1 was designated as the master in a previous SpiEnableSync call.
 */
ulRC = SpiDisableSync(hStream1);

if (ulRC) {
    /* 
     * If ulRC == ERROR_STREAM_PREROLLING, wait for 
     * state change before retrying.
     */
    return (ulRC); 
}

Related Functions

• SpiEnableSync
• SpiDestroyStream

Related Messages

• SHC_DISABLE_SYNC