12.3.40 SP_get_stream_user_data()

Synopsis

     #include <sicstus/sicstus.h>
     
     spio_t_error_code
     SP_get_stream_user_data(
        SP_stream *stream,
        void const *user_class,
        void **puser_data);

Get the user data of a user defined stream of a particular class.

Arguments

stream

An arbitrary stream. It is legal, and often useful, to call SP_get_stream_user_data() on a stream even if it is not known whether the stream is in fact a user defined stream of a particular class.

puser_data

On success, *puser_data will be set to the user_data value used when the stream was created.

Return Value

On success, *puser_data is assigned and SPIO_S_NOERR or some other success code is returned.

On failure, e.g. if the stream was not created with this user_class, an error code is returned.

Description

This function is used in order to recognize streams of a particular type (or class). At the same time as it verifies the type of stream it also returns the user_data which gives the caller a handle to the internal state of the user defined stream.

The following sample illustrates how all streams of a particular class can be found and closed. This function mimics the behavior of the SP_FCLOSE_OPTION_USER_STREAMS option to SP_fclose, see cpg-ref-SP_fclose.

     spio_t_error_code close_streams(void const *user_class, int force)
     {
       spio_t_error_code ecode = SPIO_E_ERROR;
       SP_stream *stream;
       SP_stream *next_stream;
       void *user_data;
       spio_t_bits fclose_options = 0;
     
       if (force) fclose_options |= SP_FCLOSE_OPTION_FORCE;
     
       stream = NULL;           /* means start of list of stream */
       do
         {
           /* Note: We need to do this before closing stream */
           ecode = SP_next_stream(stream, &next_stream);
           if (SPIO_FAILED(ecode)) goto barf;
     
           if (stream != NULL)
             {
               if (SPIO_SUCCEEDED(SP_get_stream_user_data(stream, user_class, &user_data)))
                 {
                   /* This is the right class of stream, close it */
                   ecode = SP_fclose(stream, fclose_options);
                   if (SPIO_FAILED(ecode))
                     {
                       if (!force) goto barf; /* ignore error if force */
                     }
                 }
             }
           stream = next_stream;
         }
       while (stream != NULL);
     
       return SPIO_S_NOERR;
     
      barf:
       return ecode;
     }

See Also

cpg-ref-SP_create_stream. Defining a New Stream.