BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / telecomm / misc / devhandler102.lha / DevHandler.doc < prev next >

Wrap

Text File | 1995-02-14 | 18.0 KB | 479 lines

The DEV Handler 1.02 Console, AUX and Raw Disk Handler (c) 1995 Martin Mares, MJSoft System Software ================================================================================ Preface ======= The DEV Handler package and its documentation are Copyright (c) Martin Mares, MJSoft System Software, Prague, Czech Republic. This archive can be freely redistributed as long as all of its files are included in their original form without any additions, deletions or modifications (excluding addition of other README-style files and icons) and no more than a nominal fee is charged for its distribution. All copyright notices in the programs and accompanying documentation files must remain intact. It's especially forbidden to add various '.displayme' files and BBS advertisements. This style of distribution is generally known as FREEWARE. Special permission is given to Fred Fish to include this software on his "Fish Disks". This software is provided "AS IS" without warranty of any kind, either expressed or implied. The author is not responsible for any damage caused by it. Introduction ============ - UNIX has named consoles. Amiga doesn't. They're very useful when you need to say which console is someone logged on (a good example are the who and write utilities). - UNIX has special files representing devices. Amiga doesn't. They're very useful for tar-like programs to access the devices directly without knowing about Amiga device concept (by the way, the Amiga access is much more better than the one in UNIX, because it's completely asynchronous, but sometimes you prefer simplicity even with lower efficiency). - UNIX consoles and special files have multiuser protection. Amiga doesn't. - There was no console and AUX handler satisfying all my requirements. This handler tries to be a solution to all of these problems. It creates a disk-like volume named Devices containing devices of the following kinds: (1) Consoles. Each console can have its own screen. Also borderless windows and similar specialities are supported. You can open the screen and set its parameters (including colors) without using any other tool. The keyboard command set is slightly extended. All standard packets are supported. (2) AUX devices. Something like console, but connected to a serial-like device instead of a window. When the carrier is lost, EOF is sent to all pending read requests and a break signal is sent to processes which use the console. (3) Softlinks. You can install a soft link to any file. Icons may be handled this way. You can also make all your volumes to DEV: (4) Raw access to devices. Both stream and block devices are supported. Installation and configuration ============================== Copy DEVHandler to your handler directory (usually L:) and create a mount entry for it (in DEVS:Mountlist or DEVS:DOSDrivers/DEV, according to system version you use): DEV: Handler = L:DEVHandler /* Correct this path */ StackSize = 2048 Priority = 5 GlobVec = -1 Startup = S:DEVHandler.config /* Or any name you want */ Also copy the Force command somewhere you like to have it in. After these steps, it would be good to create the configuration file mentioned in the mount entry. This file is a normal text file with comments introduced by semicolons (everything from the first semicolon to the end of the line is ignored). It consists of definition blocks - one for each device. Possible parameters are listed here: (many of them may be omitted, the required ones are marked with [R]) (1) Screen definition: SCREEN <name> [R] Name of public screen (must be the first line) WIDTH <n> Screen width in pixels (default=as Workbench) HEIGHT <n> Screen height in pixels (default=as Workbench) DEPTH <n> Number of bitplanes (default=as Workbench) TITLE <title> Screen title DISPLAYID <mode> Display mode for this screen = MonitorType (0=default, $21000=PAL, $11000=NTSC, $31000=VGA, $41000=A2024, $61000=EURO72, $71000=EURO36, $81000=SUPER72, $91000=DBLNTSC, $A1000=DBLPAL) + $8000 for HIRES / $8020 for SUPERHIRES + $0004 for interlace + $0080 for halfbrite mode (for other idents see graphics/modeid.[ih]) BEHIND If active (set to 1), the screen is opened in behind the others. AUTOSCROLL If active, the screen is autoscrolled if it's larger than the visible display. COLOR0 <n> RGB value for color #0 ($000 to $FFF) COLOR1 <n> RGB value for color #1 ($000 to $FFF) COLOR2 <n> RGB value for color #2 ($000 to $FFF) COLOR3 <n> RGB value for color #3 ($000 to $FFF) (2) Console definition: CONSOLE <name> [R] Name of console device (must be the first line) LEFT <n> Left edge of the window (default=0) TOP <n> Top edge of the window (default=0) WIDTH <n> Width of the window (default=full screen) HEIGHT <n> Height of the window (default=full screen) TITLE <s> Window title (don't set for backdrop windows) ACTIVE If active, the window is activated when opened BORDERLESS If active, the window has no border PUBSCREEN <name> Open the window on the specified public screen CLIP If active, console clipping is allowed BUFSIZE <n> Size of input buffer (default=512 bytes) UNIXMODE If active, it behaves as on UNIX systems - if you type anything, the output is not suppressed. The only way to stop it is using of CTRL-S (XOFF), continue by CTRL-Q (XON). HISTSIZE <n> Size of history buffer (default=1024 bytes). If zero, no history is available. RMBTRAP If active, the right mouse button is ignored and doesn't stop console output. (3) AUX definition: AUX <name> [R] Name of AUX device (must be the first line) DEVICE <name> [R] Name of device to be used for I/O UNIT <n> Device unit to be used (default=0) FLAGS <n> Device flags to be used (default=0) BUFLEN <n> Device buffer size (default set by the device) BAUD <n> Baud rate (default=9600) BITS <n> Number of data bits (default=8) STOPBITS <n> Number of stop bits (default=1) SERFLAGS <n> Flags for the serial device: $00=no parity, $01=even, $03=odd + $04 for RS-232 7-wire protocol + $10 for high-speed mode + $20 for shared access + $80 for XON/XOFF mode (default=$20) CHECKCD <n> Carrier will be tested. In case it's been lost, all read requests are returned with EOF, all writes are rejected with write error and breaks are sent to all users. (default=0) TERM <n> Terminal type: 0=Amiga, 1=Amiga with CR+LF, 2=something which should work with VT100 (default=0) BUFSIZE <n> Size of input buffer (default=512 bytes) UNIXMODE If active, it behaves as on UNIX systems - if you type anything, the output is not suppressed. The only way to stop it is using of CTRL-S (XOFF), continue by CTRL-Q (XON). HISTSIZE <n> Size of history buffer (default=1024 bytes). If zero, no history is available. (4) Softlink definition: LINK <name> [R] Name of the link (must be the first line) DEST <s> [R] Link destination (5) Raw device definition: RAWDEVICE <name> [R] Name of the device (must be the first line) DEVICE <s> [R] System device to be used UNIT <n> Device unit (default=0) FLAGS <n> Device flags (default=0) BUFMEMTYPE <n> Memory type for I/O buffers (1=any, 3=chip, 5=fast ; default=1) BLOCKSIZE <n> Size of one block (not specified or zero for stream devices) BUFFER <n> Buffer size in blocks (or bytes if stream dev) Stream devices have buffered only writes (or nothing if no buffer is specified). Block devices must have some buffer. SIZE <n> Device size in bytes (0=stream, -1=infinite, -2=autodetect via ReadGeometry command) EXCLUSIVE If active, only one open at a time is allowed UPDATE If active, the UPDATE command is sent after last write request. Use for trackdisk-like devices. MOTOR If active, turn off drive motor after the device is closed. Use for trackdisk-like devices. CLEAR If active, all device buffers are flushed (via the CLEAR command) when a read/write error is detected. READCMD <n> Device command number used for reading. (default=2=CMD_READ) WRITECMD <n> Device command number used for writing. (default=3=CMD_WRITE) (6) Global parameters (can be used for any device) PERMANENT If active, the device is always in opened state. If not set, the device is activated when it's opened and deactivated when closed. (If you specify a permanent screen, it will be still open. If it is not permanent (default), it will be opened as soon as some console will try to use it.) FROM <name> Copy all settings from given device defined before this one. The device must be of the same type as the current one. Warning #1: Strings are not enclosed in quotes, even if they contain spaces. Warning #2: DEVHandler is not foolproof. If you specify incorrect values of some options, it might crash. If a fatal error in the config file is found, a small window is opened and the error is announced. After this, the handler exits normally. For some examples, see the example config file (DevHandler.config) in this archive. Differences =========== There are some differences between DEVHandler consoles and the standard CBM CON handler: - Large writes are split automatically allowing to stop any write between lines. - Control sequences are buffered, so if you send a control sequence in two consecutive writes, the console won't insert anything between them (in standard CON, you can type a character inside it!). - If you use the RCOMMAND-V (paste) combination in raw mode, the control sequence for pasting will be sent before the actually pasted data. It makes the raw mode completely transparent (all data received from console.device are sent to you, but some of them are also interpreted - such as breaks and the paste). - CTRL-S and CTRL-Q act as normal XOFF and XON characters. (Used to stop the output anywhere and to continue afterwards.) - UNIX mode may be activated. In this case, any line being edited doesn't stop display output. Some people like it. - Buffer sizes and other useful constants may be set. - You can force EOF on the console using the Force command (see below). You can use this feature if there's someone logged on your system and you want to disconnect him. This command requires the ss.library version 5.0 or higher (can be found on the AmiNet). - You can put the currently edited line to history buffer without sending it to your program by pressing CTRL-B. - It's possible to delete not only words delimited by spaces, but also words consisting only from letters, digits and underlines by CTRL-R. - All characters except $00 and $9B can be stored to the line. In the raw mode, no restrictions on character codes apply. - You can Examine() the console. In this case, the datestamp returned tells you when has then user typed the last character. (Useful for WHO-like utilities.) Multiuser protection ==================== If the multiuser.library is found, full multi-user protection mechanisms are applied: - There are no restrictions on screens - Console and AUX devices normally belong to root and are openable by anyone. In case first user opens the console, its owner is changed to that user. If it's released, the owner is set back to root. - Links are readable by anyone. - Raw devices act like normal files. Each device has usual protection bits. They may be altered by the current owner and are set back to the defaults when the device is closed. If root modifies the protections, they are set as the defaults. Access rights are cached on file open, therefore if you pass a filehandle to anyone, the access rights you had on open are used. If you are root or you're in the root group, you can do anything the owner of the file can. Some packets are available only to root. Default protection bits: CONSOLE/AUX owner rw, group w, other w LINK all r RAWDISK owner rwd (The d bit is set because the copy command duplicates protection bits and would generate undele- table files.) Supported packets ----------------- This section lists all DOS packets handled by the DEVHandler. Each of these packets is described, its arguments and access right restrictions are listed. (1) Standard packets for all devices: DIE() -> success [ONLY ROOT] Shut down the handler. Rejected if you are not root or if there still remain some locks. CURRENT_VOLUME() -> BPTR volume Get current (and the only) volume. LOCATE_OBJECT(BPTR lock,BSTR name,LONG mode) -> BPTR lock Create a lock. FREE_LOCK(BPTR lock) -> success Free a lock. COPY_DIR(BPTR lock) -> BPTR lock Duplicate a lock. SET_PROTECT(zero, BPTR lock, BSTR name, LONG mask) -> success [ONLY OWNER] Set protection bits. If you are root, the protections are set as a default. EXAMINE_OBJECT(BPTR lock, BPTR fib) -> success EXAMINE_NEXT(BPTR lock, BPTR fib) -> success Standard directory examination mechanism. DISK_INFO(BPTR infodata) -> success Get information about current volume. INFO(BPTR lock,BPTR infodata) -> success Get information about volume associated with given lock. DEVHandler gives the same result for all locks. PARENT(BPTR lock) -> BPTR lock Get parent of given lock. SAME_LOCK(BPTR lock1, BPTR lock2) -> result Compare two locks (see dos/SameLock) READ(LONG arg1,APTR buffer,LONG size) -> size [READ RIGHTS] Read data from console/aux/raw device. WRITE(LONG arg1,APTR buffer,LONG size) -> size [WRITE RIGHTS] Write data to console/aux/raw device. FINDUPDATE(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS] FINDINPUT(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS] FINDOUTPUT(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS] Open a file. In case it's a console, the file handle is redirected to the corresponding internal console handler. END(LONG arg1) -> success Close a file. SEEK(LONG arg1,LONG offset,LONG mode) -> oldpos Seek a file. IS_FILESYSTEM() -> TRUE SET_OWNER(zero, BPTR lock, BSTR name, LONG ugid) -> success [ONLY OWNER] Set owner of a file. READ_LINK(BPTR lock,STRPTR name,APTR buffer,LONG size) -> length Read contents of a soft link. (2) Standard packets for the console/AUX subhandlers. (If you want to use them, you must open the console and extract handler port from the file handle.) WAIT_CHAR(LONG ticks) -> ischar [READ RIGHTS] Wait for character is available (returns after specified time with FALSE or with TRUE as soon as some character is available). DISK_INFO(BPTR infodata) -> success [READ RIGHTS] Return information about the console: infodata->id_DiskType = 'CON'<<8 if console, 'RAW'<<8 if con in RAW mode 'CONA' if AUX, 'RAWA' if AUX in RAW mode infodata->id_VolumeNode = Window (0 if AUX) infodata->id_InUse = device IORequest READ(LONG arg1,APTR buffer,LONG size) -> size [READ RIGHTS] Read data from the console. WRITE(LONG arg1,APTR buffer,LONG size) -> size [WRITE RIGHTS] Write data to the console. SCREEN_MODE(LONG mode) [WRITE RIGHTS] Switch the console to RAW mode or back (mode=TRUE if RAW, FALSE if not). CHANGE_SIGNAL(???, APTR task) -> APTR task [WRITE RIGHTS] Set task to send breaks to. FINDINPUT,FINDOUTPUT(BPTR lock,BPTR fh,BSTR name) -> success [R or W RIGHTS] Create a new filehandle for this console. (Used to duplicate a file handle, for example by NewShell.) END(LONG arg1) -> success Close a filehandle. STACK(LONG arg1,APTR buffer,LONG size) -> size [READ AND WRITE RIGHTS] Insert something into console buffer. It will be read before all other input. QUEUE(LONG arg1,APTR buffer,LONG size) -> size [READ AND WRITE RIGHTS] Insert something into console buffer. It will be read after all other input. (3) Non-standard packets for the console: INHIBIT(BOOL flag) -> success [ONLY OWNER] If flag=TRUE, the console will be blocked until the same packet with flag set to FALSE. While in inhibited state, the device used by AUX is not touched and no IORequests are active. FORCE() -> success [ONLY OWNER] Force EOF on this console. All read requests are returned with EOF, all write packets are rejected with error. Break is sent as if CTRL-C and CTRL-D was pressed. CHANGE_TERM(LONG termtype) -> success [ONLY OWNER] Set terminal type to specified one (see DEVHandler.i: DHTERM_#?). Planned enhancements ==================== - New packet ABORT(LONG arg1) which would try to abort any operation in progress. (It's sometimes needed to break an already sent console read packet on program exit.) - More keyboard commands for the console (e.g., program priority control) - File name completion in the console - Console scrollback buffer - Some packet allowing dynamic creation of devices. (A telnet-daemon could use this feature.) - EXAMINE_FH, FH_FROM_LOCK and some other useful packets. - Setting of default protection bits and default owner in config file. History ======= 1.0 (17.1.95) - Original release (after almost six months of beta testing) 1.01 (12.2.95) - Example DevHandler.config file included in the archive (it was mentioned in original doc, but it was missing). - Two enforcer hits in lock handling functions fixed. 1.02 (14.2.95) - Small bug in DupLock packet (introduced in 1.01) removed. - The Startup field in Device structure set to 0 (reset back on exit), because some silly programs (including MUI VolumeList gadget) incorrectly assumed it to contain FileSysStartupMsg. Final words =========== Send bug reports, flames and suggestions to <mjsoft@k332.feld.cvut.cz>.