Next: cpg-ref-user_write, Previous: cpg-ref-user_flush_output, Up: cpg-bif [Contents][Index]
user_read()spio_t_error_code user_read( void *user_data, void *buf, size_t *pbuf_size, spio_t_bits read_options );
This is the prototype for one of the methods of user defined streams. It is used when SICStus need to obtain more data from the user defined stream.
The same value as was passed to SP_create_stream().
Points to a buffer allocated by the caller.
Points to the size of the buffer. The buffer is always large enough to
hold at least one byte (for binary streams) or one character (for text
streams). When this function
returns successfully, *pbuf_size should be set to the number of
bytes stored in the buffer, which should always be positive for
successful return.
Note that buffer size is measured in bytes also for text streams.
The following bits can be set:
SPIO_DEVICE_READ_OPTION_BINARYThis is always specified if the device was created as a binary
device. The buffer should be filled with up to *pbuf_size bytes.
SPIO_DEVICE_READ_OPTION_TEXTThis is always specified if the device was created as a text
device. The buffer should be filled with wide characters, i.e.
spio_t_wchar. Note that *buf_size is size in
bytes, not in characters.
SPIO_DEVICE_READ_OPTION_NONBLOCKINGIf this is set then the function should return
quickly, either with some data read or with a
SPIO_E_WOULD_BLOCK code.
If your user_read will never block, you can ignore this value.
You should return SPIO_E_NOT_SUPPORTED if user_read
cannot support non-blocking read.
On success, *pbuf_size should be assigned and
SPIO_S_NOERR or some other success code returned.
On failure, return a SPIO error code. Error codes with special meaning
for user_read:
SPIO_E_END_OF_FILEReturn this when there are no more data to read.
SPIO_E_WOULD_BLOCKSPIO_DEVICE_READ_OPTION_NONBLOCKING was set but the operation
would block.
SPIO_E_NOT_SUPPORTEDSome unsupported option, e.g.
SPIO_DEVICE_READ_OPTION_NONBLOCKING, was passed.
Other error codes may also be returned.
Should fill buf with up to *buf_size bytes of data. Data
should be either bytes, for a binary device, or spio_t_wchar
(32 bit) wide characters, for a text device.
cpg-ref-SP_create_stream. Defining a New Stream.