.TH SXSTREAM_OPEN 3 "28 March 2016" "SXMP" "SXMP Library Manual"
.SH NAME
sxstream_open \- Open a stream on the pointed sxlink.
.br
sxstream_openwch \- Open a stream on the pointed sxlink using already opened channel.
.br
sxstream_close \- Close stream and free all associated buffers.
.SH SYNOPSIS
.B #include <sxmp/sxmp.h>
.sp
sxstream_t *sxstream_open(sxlink_t *link, const char *opt, int stid,
                          int flags);

sxstream_t *sxstream_openwch(sxlink_t *link, sxchnl_t *channel,
                             const char *opt, int stid,
                             int flags);

int sxstream_close(sxstream_t *stream);

.br
.sp
.SH DESCRIPTION
.B sxstream_open
will open a stream on the pointed by
.B link
sxlink with optional parameter
.B opt.
Stream with
.B stid
type will be opened with applied
.B flags.
.br
Flags is ored the following ones:
.br
.B SXE_O_BINARY
- Opening stream desired to be binary (not to use with
.B SXE_O_NAMED
)
.br
.B SXE_O_READ
- Opening stream has read access
.br
.B SXE_O_WRITE
- Opening stream has write access
.br
.B SXE_O_ASYNC
- Currently not implemented
.br
.B SXE_O_TRUNC
- Stream will be truncated to zero (might be used with SXE_O_WRITE only)
.br
.B SXE_O_NAMED
- Opening stream desired to be a named list data (not to use with SXE_O_BINARY)
.br
.B sxstream_openwch
will do the same, but will use already opened channel pointed by
.B channel.
.br
.B sxstream_close
will close a
.B stream
and destroy all buffers dedicated for the stream.
.br
Please note: stream functions are not thread safe you need to care about using it in multithreaded
applications.
.br
.SH RETURN VALUE
Upon successful completion, the functions 
.B sxstream_open
and
.B sxstream_openwch 
will return a valid pointer to the newly created stream. Otherwise NULL will be returned and 
.B errno will be set with appropriate error.
.B sxstream_close
will return 
.B SXE_SUCCESS
on successful case, otherwise it will return an error described below.
.SH ERRORS
.B SXE_FAILED 
will be returned in case of bad params given.
.br
.B SXE_ENOMEM
will be returned if there are no memory available.
.br
.B SXE_BADPROTO
will be returned if other side has an invalid protocol.
.B SXE_EPERM
will be returned if permission was denied.
.br
.B SXE_NOSUCHSTREAMTYPE
will be returned in case if no such stream exist on the requested side.
.br
.B SXE_LINKERROR
or
.B SXE_LINKBROKEN
will be returned if connection link is broken i.e. SSL read or write was failed due to the broken TCP connection.
.br
.SH BUGS
Not known yet.
.SH EXAMPLE
None.
.SH APPLICATION USAGE
This type of data transfer is very useful when you need to get a lot of typed data i.e. lists of lists,
or if you need to get a blob data.
.SH RATIONALE
Writing to the stream isn't a fast operation, since base 64 used to transfer a data from client
to master (master send a raw data instead of base 64 encoded). But it will be changed in the
future versions.
.br
Better to know: fastest stream is not named list of the lists stream, it's also has a cache i.e.
each read operation doesn't means a real message initiation.
.SH SEE ALSO
.BI sxlink_connect(3)
,
.BI sxchannel_open(3)
,
.BI sxchannel_close(3)
,
.BI sxstream_read(3)
,
.BI sxstream_readnamed(3)
,
.BI sxstream_bread(3)
.SH COPYRIGHT
This software licensed under GNU LGPL v3. See COPYING for further details.
.br
(c) Askele Group 2013-2015 <http://askele.com>, (c) libsxmp dev team 2016 <http://libsxmp.sf.net>
.SH AUTHOR
Alexander Vdolainen (avdolainen@zoho.com)