Derived from: public BObject
Declared in: <device/SerialPort.h>
A BSerialPort object represents an RS-232 serial port connection to the BeBox. There are four such ports on the back of the machine.
Through BSerialPort functions, you can read data received at a serial port and write data over the connection. You can also configure the connection--for example, set the number of data and stop bits, determine the rate at which data is sent and received, and select the type of flow control (hardware or software) that should be used.
To read and write data, a BSerialPort object must first open one of the serial ports by name. For example:
BSerialPort *connection = new BSerialPort;
if ( connection->Open("serial2") > 0 ) {
. . .
}
The BSerialPort object communicates with the driver for the port it has open. The driver maintains an input buffer of 1K bytes to collect incoming data and an output buffer half that size to hold outgoing data. When the object reads and writes data, it reads from and writes to these buffers.
BSerialPort(void)
Initializes the BSerialPort object to the following default values:
The new object doesn't represent any particular serial port. After construction, it's necessary to open one of the ports by name.
The type of flow control must be decided before a port is opened. But the other default settings listed above can be changed before or after opening a port.
See also: Open()
virtual ~BSerialPort(void)
Makes sure the port is closed before the object is destroyed.
void ClearInput(void)
void ClearOutput(void)
These functions empty the serial port driver's input and output buffers, so that the contents of the input buffer won't be read (by the Read() function) and the contents of the output buffer (after having been written by Write()) won't be transmitted over the connection.
The buffers are cleared automatically when a port is opened.
See also: Read(), Write(), Open()
bool IsCTS(void)
Returns TRUE if the Clear to Send (CTS) pin is asserted, and FALSE if not.
bool IsDCD(void)
Returns TRUE if the Data Carrier Detect (DCD) pin is asserted, and FALSE if not.
bool IsDSR(void)
Returns TRUE if the Data Set Ready (DSR) pin is asserted, and FALSE if not.
bool IsRI(void)
Returns TRUE if the Ring Indicator (RI) pin is asserted, and FALSE if not.
long Open(const char *name)
void Close(void)
These functions open the name serial port and close it again. Ports are identified by names that correspond to their labels on the back panel of the BeBox:
"serial1"
"serial2"
"serial3"
"serial4"
To be able to read and write data, the BSerialPort object must have a port open. It can open first one port and then another, but it can have no more than one open at a time. If it already has a port open when Open() is called, that port is closed before an attempt is made to open the name port. (Thus, both Open() and Close() close the currently open port.)
Open() can't open the name port if some other entity already has it open. (If the BSerialPort itself has name open, Open() first closes it, then opens it again.)
If it's able to open the port, Open() returns a positive integer. If unable, it returns B_ERROR.
When a serial port is opened, its input and output buffers are emptied and the Data Terminal Ready (DTR) pin is asserted.
See also: Read()
long Read(void *buffer, long maxBytes)
void SetBlocking(bool shouldBlock)
void SetTimeout(double timeout)
Read() takes incoming data from the serial port driver and places it in the data buffer specified. In no case will it read more than maxBytes--a value that should reflect the capacity of the buffer; it returns the actual number of bytes read. Read() fails if the BSerialPort object doesn't have a port open.
The number of bytes that Read() reads before returning depends not only on maxBytes, but also on the shouldBlock flag and the timeout set by the other two functions.
SetBlocking() determines whether Read() should block and wait for maxBytes of data to arrive at the serial port if that number isn't already available to be read. If the shouldBlock flag is TRUE, Read() will block. However, if shouldBlock is FALSE, Read() will take however many bytes are waiting to be read, up to the maximum asked for, then return immediately. If no data is waiting at the serial port, it returns without reading anything.
SetTimeout() sets a time limit on how long Read() will block while waiting for data to arrive at the input buffer. The timeout is relevant to Read() only if the shouldBlock flag is TRUE. (However, the time limit also applies to the WaitForInput() function, which always blocks if the limit is greater than 0.0, regardless of the shouldBlock flag.)
The timeout is expressed in microseconds and is limited to 25,500,000.0 (25.5 seconds); it's set to the maximum value if a greater amount of time is specified. Differences less than 100,000.0 microseconds (0.1 second) are not recognized; they're rounded to the nearest tenth of a second. If the timeout is set to 0.0 microseconds, Read() (and WaitForInput() ) will not block.
The default shouldBlock setting is TRUE, but the default timeout is 0.0, which prevents blocking in any case. < In future releases, the default timeout will be an infinite amount of time; it won't impose a time limit on blocking. >
Like the standard read() system function, Read() returns the number of bytes it succeeded in placing in the buffer , which may be 0. It returns B_ERROR (-1) if there's an error of any kind--for example, if the BSerialPort object doesn't have a port open. It's not considered an error if a timeout expires.
See also: Write(), Open(), WaitForInput()
void SetDataBits(data_bits count)
void SetStopBits(stop_bits count)
void SetParityMode(parity_mode mode)
data_bits DataBits(void)
stop_bits StopBits(void)
parity_mode ParityMode(void)
These functions set and return characteristics of the serial unit used to send and receive data. SetDataBits() sets the number of bits of data in each unit. The count can be:
B_DATA_BITS_7
or
B_DATA_BITS_8
The default is B_DATA_BITS_8.
SetStopBits() sets the number of stop bits in each unit. It can be:
B_STOP_BITS_1
or
B_STOP_BITS_2
The default is B_STOP_BITS_1.
SetParityMode() sets whether the serial unit contains a parity bit and, if so, the type of parity used. The mode can be:
B_EVEN_PARITY
,
B_ODD_PARITY
, or
B_NO_PARITY
The default is B_NO_PARITY.
void SetDataRate(data_rate bitsPerSecond)
data_rate DataRate(void)
These functions set and return the rate (in bits per second) at which data is both transmitted and received. Permitted values are:
| B_0_BPS | B_200_BPS | B_4800_BPS |
| B_50_BPS | B_300_BPS | B_9600_BPS |
| B_75_BPS | B_600_BPS | B_19200_BPS |
| B_110_BPS | B_1200_BPS | B_38400_BPS |
| B_134_BPS | B_1800_BPS | B_57600_BPS |
| B_150_BPS | B_2400_BPS | B_115200_BPS |
The default data rate is B_19200_BPS. If the rate is set to 0 (B_0_BPS), data will be sent and received at an indeterminate number of bits per second.
long SetDTR(bool pinAsserted)
Asserts the Data Terminal Ready (DTR) pin if the pinAsserted flag is TRUE, and de-asserts it if the flag is FALSE .
See also: SetRTS()
void SetFlowControl(ulong mask)
ulong FlowControl(void)
These functions set and return the type of flow control the driver should use. There are two possibilities:
| B_SOFTWARE_CONTROL | Control is maintained through XON and XOFF characters inserted into the data stream. |
| B_HARDWARE_CONTROL | Control is maintained through the Clear to Send (CTS) and Request to Send (RTS) pins. |
The mask passed to SetFlowControl() and returned by FlowControl() can be just one of these constants--or it can be a combination of the two, in which case the driver will use both types of flow control together. It can also be 0, in which case the driver won't use any flow control. B_HARDWARE_CONTROL is the default.
SetFlowControl() should be called before a specific serial port is opened. You can't change the type of flow control the driver uses in midstream.
long SetRTS(bool pinAsserted)
Asserts the Request to Send (RTS) pin if the pinAsserted flag is TRUE, and de-asserts it if the flag is FALSE.
See also: SetDTR()
long WaitForInput(void)
Waits for input data to arrive at the serial port and returns the number of bytes available to be read.
If data is ready to be read when this function is called, it immediately returns without blocking and reports how many bytes there are. If data hasn't arrived, it blocks and waits for the first bytes to be transmitted. When they're detected, it immediately reports how many have arrived.
This function doesn't respect the flag set by SetBlocking(); it blocks even if blocking is turned off for the Read() function. However, it does respect the timeout set by SetTimeout(). If the timeout expires before input data arrives at the serial port, it returns 0. A timeout of 0.0 microseconds doesn't give WaitForInput() enough time to block; it returns immediately.
See also: Read()
long Write(const void *data, long numBytes)
Writes up to numBytes of data to the serial port's output buffer. This function will be successful in writing the data only if the BSerialPort object has a port open. The output buffer holds a maximum of 512 bytes.
Like the write() system function, Write() returns the actual number of bytes written, which will never be more than numBytes, and may be 0. If it fails (for example, if the BSerialPort object doesn't have a serial port open) or if it's interrupted before it can write anything, it returns B_ERROR (-1).
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.