Table of Contents
6.0 Class Stream (gb)
A stream is to be understood as a data stream flowing between processes or a process and a data end connection.
Overview of the different types of data end connections, globally referred to as a file in Linux:
- Regular files (regular file).
- directories (directory)
- Symbolic links (symbolic link)
- Block-oriented devices (block device)
- Character-oriented devices (char device)
- Data links between processes according to the FIFO principle (named pipe)
- communication endpoints (unix-socket).
Notes:
- Regular files include the files you know as image or text files, for example.
- Directories are to be understood as containers for files.
- A symbolic link is a link to a file or directory.
- In the case of device files, a distinction is made between block-oriented devices such as RAM, hard disks, partitions or USB stick and character-oriented devices such as serial and parallel interfaces, terminal or sound interface. Under Linux, the device file /dev/stdin (file descriptor = 0) corresponds to standard input, the device file /dev/stdout (file descriptor = 1) to standard output and the device file /dev/stderr (file descriptor = 2) to standard error output. The standard error output is another output data stream to output error and status messages. Under Gambas, the device files (stdin, stdout and stderr) can be accessed via the static properties File.In, File.Out and File.Err provided in the File class. See Chapter “6.5 Class File” for an example of writing data to File.In and reading it from File.Out or File.Err.
- A named pipe is a volatile memory into which one process writes data and another reads the data from the named pipe. As volatile FIFO memory, it is therefore empty after data has been read out! A named pipe represents a simplex connection. You can either only read or write on a given pipe.
- Sockets embody the stream that is sent through them. If a socket is connected to another, it represents that stream. If a socket symbolises a stream of data from a connection to the Internet, then you are using a TCP socket for which you must specify a hostname and port. In contrast, with a Unix socket as a local socket, you only have to specify a path - a special file in the file system then belongs to the Unix socket. With the command ~ $ netstat -a -p –unix you can list the current local Unix sockets in a console - you will be surprised!
The interface stream specifies which methods are implemented. A stream has these four methods, among others:
Open, Read file, Write file, Close.
The Stream class is the parent class for any Gambas object that represents a stream. This means that every class that inherits from the class Stream (gb) as a base class has at least these four methods. You cannot create this (base) class. Which functionality of a Stream object you can use depends on its exact class and also on the way the object is created.
For practical work, it is thus largely irrelevant whether you write data to or read data from, for example, a regular file, a serial port or a Unix socket.Here is the list of classes that inherit from the Stream class and are described in the Gambas book:
Compress Chapter 28.1.1 Uncompress Chapter 28.1.2 Process Chapter 21 SerialPort Chapter 24.1.5 Curl Chapter 24 (FTPClient and HTTPClient.) File Chapter 6.5 Named Pipe Chapter 6.2.1 Socket Chapter 24 (TCP- and Local-Unix-Socket) VideoDevice Chapter 24
6.0.1 Properties
In Gambas, a Stream is an object that inherits from the Stream class (gb) and therefore implements its properties and methods. The Stream class has these properties:
| Property | Data type | Description |
|---|---|---|
| Blocking | Boolean | Returns or sets the truth value True if the stream is blocked. If this property is set to True, reading from the stream is blocked if there is nothing to read. Writing to the stream is blocked if, for example, the internal system buffer is full. |
| ByteOrder | Integer | Returns the byte order or sets the byte order used to read or write binary data to the stream. The property can take the following values: gb.BigEndian as “Big endian byte order” or gb.LittleEndian as “Little endian byte order”. |
| EndOfFile | Boolean | This property signals whether the last use of LINE INPUT reached the end of the file instead of reading an entire line with an end-of-line character. |
| EndOfLine | Integer | Returns or sets the line break separator used by the current stream. The possible values are: gb.Unix for lines separated by Chr$(10), gb.Windows for lines separated by Chr$(13) and Chr$(10), gb.Mac for lines separated by Chr$(13). The value of this property is used by LINE INPUT, PRINT and the Stream.Lines property. Note that you can read both Unix and Windows line formats with gb.Unix. But it only writes the Unix format! |
| Handle | Integer | Returns the system file descriptor associated with the current stream. |
| IsTerm | Boolean | Returns True if a stream is associated with a terminal. |
| Lines | .Stream.Lines | Returns a virtual object (type string array) with which you can read a stream line by line. |
| Tag | Variant | Returns the value of the Tag property assigned to the stream or sets the value. This property of data type Variant is intended for free use by the programmer and is not used by the component. |
| Term | .Stream.Term | Returns a virtual object that can be used to manage the terminal associated with the stream. The virtual class Stream.Term (gb) has the properties Echo, FlowControl, Height, Width and Name and the method Resize. Link: http://gambaswiki.org/wiki/comp/gb/.stream.term |
Table 6.0.1.1 : Properties of the Stream class
6.0.2 Methods
The Stream class has these six methods:
| Method | Return type | Description |
|---|---|---|
| Begin() | - | Starts buffering the data written to the stream so that when the Send method is called, everything is sent at once. |
| Close() | - | Closes the stream. The method is exactly the same as the CLOSE statement. |
| Drop() | - | Deletes the data buffered since the last call of the Begin() method. |
| ReadLine([ Escape As String ]) | String | Reads a line of text from the stream, just like the LINE INPUT statement. If Escape is specified, line breaks between two escape characters are ignored. This method is very useful when reading CSV files. |
| Send() | - | Sends all data at once that has been buffered since the last call of the Begin() method. |
| Watch ( Mode As Integer, Watch As Boolean ) | - | Starts or stops watching the stream file descriptor for reading or writing after it has been opened. Mode is the observation type: gb.Read to observe while reading or gb.Write to observe while writing. Watch is TRUE to enable watching and FALSE to disable watching. |
Table 6.0.2.1 : Methods of the class Stream
6.0.3 Digression
6.0.3.1 Project
The project in the download area demonstrates how to use the Type property of a Stat object to determine the type of file:
Figure 6.0.3.1.1: Determining the type of files
The characters -, d, l, b, c, p and s characterise the type of a file in the context of the command ls -l and displaying the output in a console.
6.0.3.2 Use file command
Also in a console, you can use the file command to quickly determine what type of file a given file is:
Regular file ------------------------------- hans@mint-183 ~ $ file nwm.xml nwm.xml: exported SGML document, ASCII text Directory ------------------------- hans@mint-183 ~/BildTon $ file Fractals Fractals: directory Symbolic links --------------------------------- hans@mint-183 ~/Schreibtisch $ file Formatting_DokuWiki_Tables Formatting_DokuWiki_Tables: symbolic link to /home/hans/DW/0_DW_Convert/librewriter2dokuwiki.gambas Blocked devices (block devices) -------------------------------------- hans@mint-183 ~/Schreibtisch $ file /dev/sdd1 /dev/sdd1: block special (8/49) Character-oriented devices (char devices) --------------------------------------- hans@mint-183 ~ $ file /dev/ttyUSB0 /dev/ttyUSB0: character special (188/0) Data links between processes (named pipe) ------------------------------------------------- hans@mint-183 ~ $ mknod mypipe p ' Generate Named Pipe hans@mint-183 ~ $ file mypipe mypipe: fifo (named pipe) hans@mint-183 ~ $ rm mypipe ' Delete Named Pipe Communication endpoint (unix socket) ------------------------------------ hans@mint-183 ~ $ file /run/user/1000/unix_socket.sock /run/user/1000/unix_socket.sock: socket
6.0.3.3 The # character
For example, the documentation states.
FLUSH [ [ # ] Stream ]
where the # sign is marked as optional. In Gambas, you can prepend the # character to the variable name of a stream object, but only for the CLOSE, READ, WRITE, SEEK, INPUT, LINE INPUT, PRINT, UNLOCK and FLUSH instructions. This does not work in function calls like LOF(…), EOF(…) or the instruction LOCK.
In a Socket_Read event, you can use the following assignment, for example:
vData = Read #Last, -4096
In Last, the Socket object is returned that triggered the Read event and from which data can be read. You should prefer the “#Last” to “Last” because “Last” alone is not seen to be a stream in this case.