libsxmp/man/sxhub_stream_register.3

.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)