[manpages] Added sxstream_open, sxstream_openwch, sxstream_close;

9 years ago · 14bb9d5452
parent 907ab884d3
commit 14bb9d5452
4 changed files with 133 additions and 1 deletions
--- a/man/Makefile.am
+++ b/man/Makefile.am
@ -4,4 +4,5 @@ man_MANS = sxmsg_rreply.3 sxhub_create.3 sxhub_init.3 sxhub_destroy.3 sxhub_free
 	sxhub_set_authcheck.3 sxhub_set_rpcvalidator.3 sxhub_set_channelcall.3 \
 	sxlink_master_accept.3 sxlink_connect.3 sxlink_close.3 sxchannel_open.3 \
 	sxchannel_close.3 sxmsg_send.3 sxmsg_send_pp.3 sxmsg_clean.3 sxmp_finalize.3 sxmsg_pulse.3 \
-	sxmsg_reply.3 sxmsg_reply_pp.3 sxmsg_return.3 sxmsg_return_pp.3 sxlink_connect_at.3
+	sxmsg_reply.3 sxmsg_reply_pp.3 sxmsg_return.3 sxmsg_return_pp.3 sxlink_connect_at.3 \
+	sxstream_open.3 sxstream_openwch.3 sxstream_close.3
--- a/man/sxstream_close.3
+++ b/man/sxstream_close.3
@ -0,0 +1 @@
+sxstream_open.3
--- a/man/sxstream_open.3
+++ b/man/sxstream_open.3
@ -0,0 +1,129 @@
+.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)
--- a/man/sxstream_openwch.3
+++ b/man/sxstream_openwch.3
@ -0,0 +1 @@
+sxstream_open.3