From 78fea5bd627b4158e1731e1088b0bbb9695d93a4 Mon Sep 17 00:00:00 2001 From: Alexander Vdolainen Date: Wed, 6 Apr 2016 00:36:47 +0300 Subject: [PATCH] [manpages] sxhub_stream_register() man page added; --- man/Makefile.am | 2 +- man/sxhub_stream_register.3 | 182 ++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 man/sxhub_stream_register.3 diff --git a/man/Makefile.am b/man/Makefile.am index 97bdb4d..d200905 100644 --- a/man/Makefile.am +++ b/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 diff --git a/man/sxhub_stream_register.3 b/man/sxhub_stream_register.3 new file mode 100644 index 0000000..be43dd0 --- /dev/null +++ b/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 +.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 , +.br +(c) libsxmp dev team 2016 +.SH AUTHOR +Alexander Vdolainen (avdolainen@zoho.com)