SpiDestroyStream

The SpiDestroyStream function removes a stream instance from the system. It closes the connection between the source and target stream handlers and deallocates all system resources associated with the stream.

Syntax

SpiDestroyStream(hstream)

Parameters

hstream (HSTREAM) - input

The handle of the stream to be removed from the system. This handle was previously returned by SpiCreateStream.

Return Value

rc (ULONG) - returns

Return code indicating success or the type of failure:

• NO_ERROR: Success.
• ERROR_DESTROY_STREAM: Attempted to destroy a split stream that owns buffers while other streams are still using those buffers.
• ERROR_INVALID_FUNCTION: Invalid function requested.
• ERROR_INVALID_STREAM: Invalid stream handle.
• FAILURE: Stream handler-specific error return code.

Remarks

Once this function is successfully called, the provided stream handle becomes invalid and cannot be used for any further SPI calls.

• **Resource Management**: All memory, buffers, and control blocks allocated for the stream are returned to the system heap.
• **Synchronization Groups**:
  • If the stream being destroyed is the **master stream** of a synchronization group, the entire group is disabled.
  • If it is a **slave stream**, only that specific stream is removed from the group; the remaining master and slave streams continue to function normally.
• **Split Streams**: In configurations where multiple streams share buffers, the "owner" stream (the one that originally allocated the buffers) must be the **last** stream destroyed. Attempting to destroy the buffer-owning stream while dependent streams still exist will result in an `ERROR_DESTROY_STREAM` error.

Example Code

The following code snippet demonstrates the standard procedure for cleaning up a stream after data processing is complete.

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

ULONG   ulRC;    /* Error return code */
HSTREAM hStream; /* Stream handle      */

/* ... Stream is created and data is processed ... */

/*------------------------------------------------*/
/* Finished with stream - Now destroy the stream  */
/*------------------------------------------------*/
ulRC = SpiDestroyStream(hStream);

if (ulRC) {
  /* Handle the error - the handle might be invalid or 
     resource dependencies might exist */
  return (ulRC);
}

Related Functions

• SpiCreateStream
• SpiStopStream

Related Messages

• SHC_DESTROY
• SHC_DISABLE_SYNC