libstream

Section: Linux Simple I/O Library (2)
Updated: 21 December 2018
Index Return to Main Contents

NAME

libstream -- Linux Simple I/O Library: Stream Framing Protocol Module

SYNOPSIS

#include <libsimpleio/libstream.h>

typedef ssize_t (*STREAM_readfn_t)(int fd, void *buf, size_t count);

typedef ssize_t (*STREAM_writefn_t)(int fd, const void *buf,
  size_t count);

void STREAM_change_readfn(STREAM_readfn_t newread, int32_t *error);

void STREAM_change_writefn(STREAM_writefn_t newwrite, int32_t *error);

void STREAM_encode_frame(void *src, int32_t srclen, void *dst,
  int32_t dstsize, int32_t *dstlen, int32_t *error);

void STREAM_decode_frame(void *src, int32_t srclen, void *dst,
  int32_t dstsize, int32_t *dstlen, int32_t *error);

void STREAM_send_frame(int32_t fd, void *buf, int32_t bufsize,
  int32_t *count, int32_t *error);

void STREAM_receive_frame(int32_t fd, void *buf, int32_t bufsize,
  int32_t *framesize, int32_t *error);

Link with -lsimpleio.

DESCRIPTION

These functions encode, decode, send, and receive frames to and from a bidirectional byte stream, which will typically be either a serial port or a network socket. The frames are encoded according the the Stream Framing Procotol. See below for a link to the protocol specification.

All functions return either 0 (upon success) or an errno value (upon failure) in *error.

STREAM_change_readfn() changes the function used to read from the underlying stream from the default read() to some other compatible function.

STREAM_change_writefn() changes the function used to write to the underlying stream from the default write() to some other compatible function.

STREAM_encode_frame() encodes the message passed in *src, with its length passed in srclen. Empty messages (srclen==0) are allowed. The encoded frame will be returned in *dst, whose maximum size must be passed in dstsize. The size of the destination buffer must be at least 2 * srclen + 8 bytes. The actual size of the encoded frame will be returned in *dstlen.

STREAM_decode_frame() decodes the frame passed in *src, with its length passed in srclen. The decoded message will be returned in *dst, whose maximum size must be passed in dstsize. The actual size of the decoded message will be returned in *dstlen.

STREAM_send_frame() writes an encoded frame to the bidirectional byte stream indicated by the file descriptor fd. The encoded frame is passed in buf and its size is passed in bufsize. Upon success, the number of bytes actually sent will be returned in *count.

STREAM_receive_frame() reads one byte from the bidirectional byte stream indicated by the file descriptor fd and attempts to assemble a frame. It should be called repeatedly with the same *buf, bufsize, and *framesize parameters. The *framesize parameter is incremented for each byte received, and zeroed if an error occurs. The *error parameter will be set to EAGAIN while a frame is being assembled. Upon successful assembly of a complete frame, its size will be returned in *framesize and zero returned in *error.

AUTHOR

Philip Munts dba Munts Technologies

This document was created by man2html, using the manual pages.
Time: 03:28:51 GMT, October 30, 2023