| D O S _ A D D F D R E L A Y ( )
| | | | | SOURCE: qdev_autodocs.txt 1.163 (12/09/2014) English
AMIGA - DOS_#?
----------------------------------------------------------------------------
NAME
dos_addfdrelay() - Starts up file descriptor relay as
a DOS device.
SYNOPSIS
res = dos_addfdrelay(name, termsig);
BOOL dos_addfdrelay(UBYTE *, ULONG);
FUNCTION
This function is a subsystem that allows to relay data
to n other file descriptors using just one call to the
write routine.
INPUTS
name - NULL terminated DOS device name. Name can be
suffixized with colon(':'), but that is not
necessary.
termsig - Device termination signal. NULL if you dont
wish for it to be terminable.
RETURNS
Returns TRUE if device was up and running, or FALSE if
it didnt init properly.
BASES
SysBase, DOSBase
NOTES
If you decide to spawn this device in sepearate process
from under your code space then make sure every fd you
attach does not emit termination signal back to you! It
is just unwise to quit in such case.
Do 'ctl_doconswitch()' on a fd of a channel you want to
be the default in order to use 'Output()' and 'CONSOLE:'
(requires setting default flag on the channel too).
Standard 'ReadArgs()' cmd line opts are as follows:
"CN=CHANNAME,CP=CHANPASS/K,CD=CHANDEF/K,TF=TERMFILES/K,
CE=CHANPIPE/K,CH=CHANPATH/K,NE=NOEOFGEN/K,DF=DESTFILE/K,
RF=REMFILE/K,CF=CLOSEFILE/K,BF=BUFFILE/K,SA=STRIPANSI/K,
TS=TERMSIG/K,LF=LINEFMT/K,RB=ROLLBUF/K,FR=FLUSHREQ/K" .
CN=CHANNAME - Channel name. Channel creation is easy,
if there is no such channel then it will
be created.
CP=CHANPASS - Channel password. To protect your chan.
with a password type it either: +<pwd>
or <pwd>, to deactivate use -<pwd>.
CD=CHANDEF - Should the channel requested right now
be the default? Argument is boolean.
TF=TERMFILES - Close down/terminate all files on this
channel if last client disconnects. In
case of files who are VCRs, delays will
be computed from scratch!
CE=CHANPIPE - Using this will allow channel to be
used as an ordinary pipe, which will
disallow any other options below! This
argument takes size. 0 = No pipe. Pipe
created with the help of this option is
synchronous, however it does some nice
tricks to avoid blocking!
CH=CHANPATH - With this 3 state switch you can turn
the channel into router(or path finder)
which will allow automatic channel
discovery per process when combined
with 'CD=CHANDEF' and "CONSOLE:". All
possible states are: 0 - dont act as
a router, 1 - seek in pipes, 2 - seek
in relays.
NE=NOEOFGEN - Dont generate EOF when in pipe mode.
This will be set per file descriptor!
DF=DESTFILE - Where to relay your data? Argument can
be ordinary file name, that must exist,
or the address of file descriptor. Note
that passing addresses that you dont
own is very bad idea. Also, there is a
protection that prevents random numbers
from being treated as functional f. d.
RF=REMFILE - Remove this file from channel. Argument
is boolean.
CF=CLOSEFILE - Should file attached to the channel be
automatically closed when it is removed
or whole relay goes down? This argument
is boolean.
BF=BUFFILE - Should buffering be used for this file
descriptor? Upto 1.48 argument was bool.
Now it is (0/1/2) where 2 activates the
data flush after each write. Note that
setting buffering is actually one time
operation and only before using FH. This
is because OS changes it internally
after first 'FWrite()'. Then this switch
has no effect and file stays buffered!
SA=STRIPANSI - Should ANSI escape codes be removed on
this file descriptor? Note that escape
code stripping works a bit different for
virtual files(ANSI is collected and can
be stripped when reading data!). This
argument is boolean(0 or 1). Aside that
options 2 and 3 will allow CSI query
and VCR mode respectively.
TS=TERMSIG - Should signal be sent to the owner if
this file descriptor is being removed
or whole relay goes down? Argument is
number in one of four numeral systems.
0 means no signal. Also, signal will be
sent only when auto closing the file is
off!
LF=LINEFMT - Should every new line be prefixed with
some header? This argument accepts text
which can contain various format opts.
Format options begin with '%' character
and are:
'A' - Address of the owner of this file
descriptor.
'a' - Address of this file descriptor.
'C' - Total channel count in the proc.
'c' - Number of clients using this chan.
'd' - Device name of this process.
'f' - F. descriptor count on this chan.
'g' - Will this channel terminate all
the files after last client is
gone?
'h' - Will this f. descriptor pass the
ANSI through?
'i' - Will this file descriptor prebuf.
the data?
'j' - Will this f. descriptor be closed
automatically?
'k' - Is this channel the default one?
'L' - Is this channel password prot.?
'l' - Line format buffer for this chan.
'N' - This file descriptor name.
'n' - Current channel name.
'r' - Num. of failed relay attempts on
this file desc.
'S' - Address of the client that curr.
sends something.
's' - Signal to be sent to the owner of
this file desc.
'T' - Amount of time this chan. exists.
't' - Current system time.
'W' - Number of all file descriptors in
the process.
'w' - Number of all clients in the proc.
'x' - Number of direct requests needed
to flush dead chans.
'y' - Number of reqs left to flush dead
channels.
'z' - Number of flushed channels.
RB=ROLLBUF - Should this channel have rollover buf?
Rollover buffer is virtual file that is
able to collect what was written to the
channel with the ability to wrap if end
of file is reached. Argument is size of
that virtual file. 0 means no file.
FR=FLUSHREQ - After how many direct requests unused
channels should be removed? 0 means no
channel removal.
To obtain relay statistics, 'Open()' your relay and do
the 'FGets()' until EOF with minimum 256 bytes buffer .
The easiest way to see the stats is to use 'type' from
shell.
If you have virtual file attached to your chan. and you
want to access it, then also 'Open()' your relay on the
requested channel and do the 'Read()' or 'FGets()'. You
dont have to worry about the cursor as writing uses
different variable. Also you cant 'Seek()' in v. file
because it is rollover!
Note that if you use 'termsig' then consoles opened
from under the relay may/will rebroadcast signals back
to relay and if there is no clients it may eventually
go down!
Maximum number of rollover files(one per chan.) is 16!
This is because virtual files use 'AllocSignal()', and
there is only 16 signals available per process!
Important! File handles as obtained with 'Open()' dont
reference public message port, but a private one that
is strictly associated with the given FH! The only way
to clone the FH is to pass it to the 'ctl_doconswitch()'
function.
Warning! File buffering in kickstarts V39.xxx and less
is a bit different than that in V40.xxx thus buffered
relay files may receive the data at literally different
times! This may be a problem if you map local virtual
files, write to them through FDR and expect data to be
in the buffer immediately. You will have to turn off
the buffering in FDR for such files while putting them
on the channel to be on the safe side! Additionally use
argument BF 2 for buffered files (1.49 feature) .
SEE ALSO
dos_remfdrelay(), dos_ctrlfdrelay()
EXAMPLE
See 'fdrelay-test.c' for more details.
BUGS
None known.
----------------------------------------------------------------------------
| |
| |