/*-------------------------------------------------------------*/
/***************************************************************
* Functions herein are examples of frequently needed *
* netwib_io. *
***************************************************************/
/*-------------------------------------------------------------*/
/***************************************************************
* FINAL LINKS *
***************************************************************/
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_null
Description :
Create an io junking data and giving nothing.
Input parameter(s) :
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_null(netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_mem
Description :
Create an io storing and reading data from memory.
Input parameter(s) :
pbufread : buffer where data is read
pbufwrite : buffer where data is written
*plockbufread : lock used when another thread want to
access pbufread
*plockbufwrite : lock used when another thread want to
access pbufwrite
closebufsatend : if the buffers are closed when the io
is closed (in locked version, this also
close rwlocks)
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_mem(netwib_buf *pbufread,
netwib_buf *pbufwrite,
netwib_bool closebufsatend,
netwib_io **ppio);
netwib_err netwib_io_init_mem_lock(netwib_thread_rwlock *plockbufread,
netwib_buf *pbufread,
netwib_thread_rwlock *plockbufwrite,
netwib_buf *pbufwrite,
netwib_bool closebufsatend,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_tlv
Description :
Create an io storing and reading data from memory.
Input parameter(s) :
pbufread : buffer where data is read
pbufwrite : buffer where data is written
*plockbufread : lock used when another thread want to
access pbufread
*plockbufwrite : lock used when another thread want to
access pbufwrite
closebufsatend : if the buffers are closed when the io
is closed (in locked version, this also
close rwlocks)
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
Note :
If canslide is set on pbufread or pbufwrite, it will be
faster.
*/
netwib_err netwib_io_init_tlv(netwib_buf *pbufread,
netwib_buf *pbufwrite,
netwib_bool closebufsatend,
netwib_io **ppio);
netwib_err netwib_io_init_tlv_lock(netwib_thread_rwlock *plockbufread,
netwib_buf *pbufread,
netwib_thread_rwlock *plockbufwrite,
netwib_buf *pbufwrite,
netwib_bool closebufsatend,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_exec
Description :
Create an io redirecting read and write requests to
a sub process.
Input parameter(s) :
pbufcommand : command (for example "/bin/ls /")
providedway : if user will read or write from the io
killonclose : if true, a close kills the process
pexitednormally : address of a boolean which will receive :
- NETWIB_TRUE : if program exited normally
- NETWIB_FALSE : else
if NULL, do not set it
preturnedvalue : address of a uint32 which will receive
value returned by the program
if NULL, do not set it
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
Example 1 :
/bin/ls a b "c"
corresponds to :
filename = /bin/ls
argv[0] = ls
argv[1] = a
argv[2] = b
argv[3] = c
Example 2 :
ls "a \"'\t\\a\x41"
corresponds to :
filename = ls
argv[0] = ls
argv[1] = a "'_tabulation_\a_0x41_
argv[3] = NULL
Note : \ sequences recognized inside "" are : abtnr
*/
netwib_err netwib_io_init_exec(netwib_constbuf *pbufcommand,
netwib_io_waytype providedway,
netwib_bool killonclose,
netwib_bool *pexitednormally,
netwib_uint32 *preturnedvalue,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_shellserver
Description :
Create an io redirecting read and write requests to
a shell.
It should be used with netwib_io_init_shellclient.
IMPORTANT: It is currently only implemented for Linux.
Input parameter(s) :
uid : requested user id
*pbufterm : TERM environment variable
*pbufpath : PATH environment variable
killonclose : if true, a close kills the process
pexitednormally : address of a boolean which will receive :
- NETWIB_TRUE : if program exited normally
- NETWIB_FALSE : else
if NULL, do not set it
preturnedvalue : address of a uint32 which will receive
value returned by the last command executed
in the shell
if NULL, do not set it
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
NETWIB_ERR_LONOTIMPLEMENTED : not on Linux
*/
netwib_err netwib_io_init_shellserver(netwib_uint32 uid,
netwib_constbuf *pbufterm,
netwib_bool killonclose,
netwib_bool *pexitednormally,
netwib_uint32 *preturnedvalue,
netwib_io **ppio);
#define NETWIB_IO_INIT_SHELLSERVER_UID_NONE 0xFFFFFFFFu
#define NETWIB_IO_INIT_SHELLSERVER_TERM_NONE NULL
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_shellclient
Description :
Create an io redirecting read and write requests to
a console.
It should be used with netwib_io_init_shellserver.
IMPORTANT: It is currently only implemented for Linux.
Input parameter(s) :
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
NETWIB_ERR_LONOTIMPLEMENTED : not on Linux
*/
netwib_err netwib_io_init_shellclient(netwib_io **ppio);
/* to obtain term for netwib_io_init_shellserver() */
netwib_err netwib_shellclient_term(netwib_bufext *pbufterm);
/*-------------------------------------------------------------*/
/***************************************************************
* INTERMEDIARY LINKS *
***************************************************************/
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_data
Description :
Create several type of io. For example line io can be used
like this to read line by line :
netwib_er(netwib_io_init_file_read("/tmp/f", &pio));
netwib_er(netwib_io_init_data_line(&pioline));
netwib_er(netwib_io_plug_read(&pioline, &pio));
netwib_er(netwib_io_read(&pioline, &b));
etc.
netwib_er(netwib_io_close_read(&pioline);
Input parameter(s) :
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
typedef enum {
NETWIB_IO_INIT_DATA_TYPE_LINE = 1,
NETWIB_IO_INIT_DATA_TYPE_CHUNK,
NETWIB_IO_INIT_DATA_TYPE_FIXED,
NETWIB_IO_INIT_DATA_TYPE_TRANSPARENT
} netwib_io_init_data_type;
netwib_err netwib_io_init_data(netwib_io_init_data_type rdtype,
netwib_io_init_data_type wrtype,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* read/write line by line */
#define netwib_io_init_data_line(ppio) netwib_io_init_data(NETWIB_IO_INIT_DATA_TYPE_LINE,NETWIB_IO_INIT_DATA_TYPE_LINE,ppio)
/* If write writes '\r\n'(true) or '\n'(false) */
/* netwib_err f(netwib_io *pio, netwib_bool add_r); */
#define netwib_io_ctl_set_data_line_msdos(pio,add_r) netwib_io_ctl_set(pio,NETWIB_IO_WAYTYPE_WRITE,NETWIB_IO_CTLTYPE_DATA_LINE_MSDOS,NULL,add_r)
#define netwib_io_ctl_get_data_line_msdos(pio,padd_r) netwib_io_ctl_get(pio,NETWIB_IO_WAYTYPE_WRITE,NETWIB_IO_CTLTYPE_DATA_LINE_MSDOS,NULL,padd_r)
/*-------------------------------------------------------------*/
/* read/write a chunk of data */
/* note : when end is reached, last returned chunk might be smaller */
#define netwib_io_init_data_chunk(ppio) netwib_io_init_data(NETWIB_IO_INIT_DATA_TYPE_CHUNK,NETWIB_IO_INIT_DATA_TYPE_CHUNK,ppio)
/* To change size of read/written data : between minsize and maxsize */
/* netwib_err f(netwib_io *pio, netwib_io_waytype way, netwib_uint32 size); */
#define netwib_io_ctl_set_data_chunk_minsize(pio,way,minsize) netwib_io_ctl_set(pio,way,NETWIB_IO_CTLTYPE_DATA_CHUNK_MINSIZE,NULL,minsize)
#define netwib_io_ctl_set_data_chunk_maxsize(pio,way,maxsize) netwib_io_ctl_set(pio,way,NETWIB_IO_CTLTYPE_DATA_CHUNK_MAXSIZE,NULL,maxsize)
/* netwib_err f(netwib_io *pio, netwib_io_waytype way, netwib_uint32 *psize); */
#define netwib_io_ctl_get_data_chunk_minsize(pio,way,pminsize) netwib_io_ctl_get(pio,way,NETWIB_IO_CTLTYPE_DATA_CHUNK_MINSIZE,NULL,pminsize)
#define netwib_io_ctl_get_data_chunk_maxsize(pio,way,pmaxsize) netwib_io_ctl_get(pio,way,NETWIB_IO_CTLTYPE_DATA_CHUNK_MAXSIZE,NULL,pmaxsize)
/*-------------------------------------------------------------*/
/* read/write fixed size of data */
/* note : when end is reached, last returned data might be smaller */
#define netwib_io_init_data_fixed(ppio) netwib_io_init_data(NETWIB_IO_INIT_DATA_TYPE_FIXED,NETWIB_IO_INIT_DATA_TYPE_FIXED,ppio)
/* To change size of read data. */
/* netwib_err f(netwib_io *pio, netwib_io_waytype way, netwib_uint32 size); */
#define netwib_io_ctl_set_data_fixed_size(pio,way,size) netwib_io_ctl_set(pio,way,NETWIB_IO_CTLTYPE_DATA_FIXED_SIZE,NULL,size)
/* netwib_err f(netwib_io *pio, netwib_io_waytype way, netwib_uint32 *psize); */
#define netwib_io_ctl_get_data_fixed_size(pio,way,psize) netwib_io_ctl_get(pio,way,NETWIB_IO_CTLTYPE_DATA_FIXED_SIZE,NULL,psize)
/*-------------------------------------------------------------*/
/* transparent : does nothing */
#define netwib_io_init_data_transparent(ppio) netwib_io_init_data(NETWIB_IO_INIT_DATA_TYPE_TRANSPARENT,NETWIB_IO_INIT_DATA_TYPE_TRANSPARENT,ppio)
/*-------------------------------------------------------------*/
/* To change io type */
/* netwib_err f(netwib_io *pio, netwib_io_init_data_type type); */
#define netwib_io_ctl_set_data_type(pio,way,type) netwib_io_ctl_set(pio,way,NETWIB_IO_CTLTYPE_DATA_TYPE,NULL,type)
/* netwib_err f(netwib_io *pio, netwib_io_init_data_type *ptype); */
#define netwib_io_ctl_get_data_type(pio,way,ptype) netwib_io_ctl_get(pio,way,NETWIB_IO_CTLTYPE_DATA_TYPE,NULL,ptype)
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_storage
Description :
Create an io buffering data. It can be plugged in front
of low level io not supporting unread for example.
Input parameter(s) :
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_storage(netwib_io **ppio);
#define netwib_io_ctl_set_storage_flush(pio) netwib_io_ctl_set(pio,NETWIB_IO_WAYTYPE_SUPPORTED,NETWIB_IO_CTLTYPE_STORAGE_FLUSH,NULL,0)
/*-------------------------------------------------------------*/
/***************************************************************
* MULTIPLEX LINKS *
***************************************************************/
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_rdwr
Description :
Create an io redirecting read an write requests to two
distinct io.
Input parameter(s) :
preadio : io where data is read
pwriteio : io where data is written
closeiosatend : if the io are closed when the io
is closed
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_rdwr(netwib_io *preadio,
netwib_io *pwriteio,
netwib_bool closeiosatend,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_tee
Description :
Write data to 2 io.
Read data from 2 io.
Input parameter(s) :
pio1 : first io where data is read/written
pio2 : second io where data is read/written
closeiosatend : if pio1/pio2 are closed when the io
is closed
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_tee(netwib_io *pio1,
netwib_io *pio2,
netwib_bool closeiosatend,
netwib_io **ppio);
/*-------------------------------------------------------------*/
/* Name : netwib_io_init_debug
Description :
Display information for each request.
Input parameter(s) :
pnormalio : io where normal data is read/written
pdebugio : io where debugging data is written
closeiosatend : if io are closed when the io
is closed
Input/output parameter(s) :
Output parameter(s) :
**ppio : io created
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_io_init_debug(netwib_io *pnormalio,
netwib_io *pdebugio,
netwib_bool closeiosatend,
netwib_io **ppio);