[manpages] sxhub_stream_register() man page added;

man/Makefile.am

@@ -5,4 +5,4 @@ man_MANS = sxmsg_rreply.3 sxhub_create.3 sxhub_init.3 sxhub_destroy.3 sxhub_free
 	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 \
-	sxstream_open.3 sxstream_openwch.3 sxstream_close.3
+	sxstream_open.3 sxstream_openwch.3 sxstream_close.3 sxhub_stream_register.3

man/sxhub_stream_register.3

@@ -0,0 +1,182 @@
+.TH SXHUB_STREAM_REGISTER 3 "28 March 2016" "SXMP" "SXMP Library Manual"
+.SH NAME
+sxhub_stream_register \- Register stream type implementation on the given sxhub.
+.br
+.SH SYNOPSIS
+.B #include <sxmp/sxmp.h>
+.sp
+int sxhub_stream_register(sxhub_t *hub,
+                          const struct sxstream_description
+                          *s_desc);
+
+.br
+.sp
+.SH DESCRIPTION
+.B sxhub_stream_register
+will register a new stream type available on the sxhub peers. This function takes
+.B hub
+as a subject
+to register on and
+.B s_desc
+as a description of the stream. Where the
+.B struct sxstream_description
+has the following entries:
+.sp
+struct sxstream_description {
+  uint16_t stid; /** < stream type ID */
+  uint16_t pcid; /** < pinned channel type ID */
+  uint16_t type; /** < type: 0||SXE_O_NAMED||SXE_O_BINARY */
+  uint16_t flags; /** < possible flags */
+  struct sxstream_ops *ops; /** < operations */
+  list_head_t *named; /** < named entries order */
+  usrtc_node_t node; /** < internal node struct */
+};
+.br
+.sp
+Where
+.B stid
+is a type ID of the stream,
+.B pcid
+is a channel type ID where stream might be opened,
+.B type
+is a type of the registering stream should has the following values:
+.br
+.B 0
+- stream is a simple listing data
+.br
+.B SXE_O_NAMED
+- stream is a named listing data
+.br
+.B SXE_O_BINARY
+- stream provide a binary data
+.br
+
+.br
+Flags might be used pointed by
+.B flags
+, the following flags might be or'ed:
+.br
+.B SXE_O_READ
+- stream has read capability
+.br
+.B SXE_O_WRITE
+- stream has write capability
+.br
+.B SXE_O_TRUNC
+- opening/creating stream should truncate to zero all underlaying data
+.br
+.B SXE_O_ASYNC
+- operations on the stream might be async
+.br
+
+.br
+Operations i.e. stream implementation must be provided via
+.B ops
+which actually a structure:
+.sp
+struct sxstream_ops {
+  int (*s_open)(sxlink_t *, struct sxstream_opened *,
+                const char *);
+  int (*s_close)(struct sxstream_opened *);
+  union {
+    size_t (*s_bread)(struct sxstream_opened *, size_t,
+                      uint64_t, void *);
+    size_t (*s_eread)(struct sxstream_opened *, size_t,
+                      uint64_t, list_head_t **);
+  };
+  union {
+    size_t (*s_bwrite)(struct sxstream_opened *, size_t,
+                       uint64_t, const void *);
+    size_t (*s_ewrite)(struct sxstream_opened *, uint64_t,
+                       list_head_t *);
+  };
+};
+
+.br
+.sp
+Where
+.B struct sxstream_opened
+is an opened stream of the provided type, to assign a special
+implementation specific data for stream use:
+.br
+.B sxstream_opened_setpriv(n, p)
+- where
+.B n
+is a struct sxstream_opened,
+.B p
+implementation specific data pointer
+.br
+.B sxstream_opened_getpriv(n)
+- where
+.B n
+is a struct sxstream_opened
+.br
+
+.br
+Functions
+.B s_open,
+.B s_close must return
+.B SXE_SUCCESS
+on success or any other error from sxmp error codes in case of failure.
+Functions
+.B s_bread,
+.B s_bwrite
+intended for binary streams operations, since
+.B s_eread,
+.B s_ewrite
+for listing data streams.
+.br
+
+.br
+
+
+.SH RETURN VALUE
+Upon successful completion, the function 
+.B sxhub_stream_register
+will return 0, otherwise:
+.br
+.B ENOMEM
+- not enough memory i.e. failed to allocate specific data
+.br
+.B EEXIST
+- this stream type already exist
+.br
+.SH BUGS
+Returning something else except
+.B SXE_SUCCESS
+on
+.B s_close
+will not free structure and stream will be opened,
+but on link destroy it will be called again and will destroy any data of the stream.
+.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>,
+.br
+(c) libsxmp dev team 2016 <http://libsxmp.sf.net>
+.SH AUTHOR
+Alexander Vdolainen (avdolainen@zoho.com)