The Device Kit: BSerialPort

The Device Kit Table of Contents | The Device Kit Index

# BSerialPort

Derived from: none

Declared in: be/device/SerialPort.h

Library: libdevice.so

###### Summary

A BSerialPort object represents an RS-232 serial connection to the computer. Through BSerialPort functions, you can read data received at a serial ports 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. To find the names of all the serial ports on the computer, use the `CountDevices()` and `GetDeviceName()` functions:

       BSerialPort serial;
       char devName[B_OS_NAME_LENGTH];
       int32 n = 0;

       for (int32 n = serial.CountDevices()-1; n >= 0; n--) {
          serial.GetDeviceName(n, devName);

          if ( serial.Open(devName) > 0 )
              ....
       }

The BSerialPort object communicates with the driver for the port it has open. The driver maintains an input buffer to collect incoming data and a smaller output buffer to hold outgoing data. When the object reads and writes data, it reads from and writes to these buffers.

The serial port drivers, and therefore BSerialPort objects, send and receive data asynchronously only.

## Constructor and Destructor

### BSerialPort()

`BSerialPort(`void`) `

Initializes the BSerialPort object to the following default values:

- Hardware flow control (see `SetFlowControl()`)

- A data rate of 19,200 bits per second (see `SetDataRate()`)

- A serial unit with 8 bits of data, 1 stop bit, and no parity (see `SetDataBits()`)

- Blocking with no time limit—an infinite timeout—for reading data (see `Read()`)

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()`

### ~BSerialPort()

virtual `~BSerialPort() `

Makes sure the port is closed before the object is destroyed.

## Member Functions

### ClearInput() , ClearOutput()

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()`

### Close() see Open()

### DataBits() see SetDataBits()

### IsCTS()

bool `IsCTS(`void`) `

Returns `true` if the Clear to Send (CTS) pin is asserted, and `false` if not.

### IsDCD()

bool `IsDCD(`void`) `

Returns `true` if the Data Carrier Detect (DCD) pin is asserted, and `false` if not.

### IsDSR()

bool `IsDSR(`void`) `

Returns `true` if the Data Set Ready (DSR) pin is asserted, and `false` if not.

### IsRI()

bool `IsRI(`void`) `

Returns `true` if the Ring Indicator (RI) pin is asserted, and `false` if not.

### Open() , Close()

status_t `Open(`const char *name`) `
void `Close(`void`) `

These functions open the name serial port and close it again. To get a serial port name, use the GetDeviceName() function; an example is shown in the introduction.

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.)

When a serial port is opened, its input and output buffers are emptied and the Data Terminal Ready (DTR) pin is asserted.

RETURN CODES

positive integers (not 0). Success.

- `B_PERMISSION_DENIED. The port is already open.

  `

### ParityMode() see SetDataBits()

### Read() , SetBlocking() , SetTimeout()

ssize_t `Read(`void *buffer, size_t maxBytes`) `
void `SetBlocking(`bool shouldBlock`) `
status_t `SetTimeout(`bigtime_t timeout`) `

`Read()` takes incoming data from the serial port driver and places it in the data buffer provided. In no case will it read more than maxBytes—a value that should reflect the capacity of the buffer. The input buffer of the driver, from which `Read()` takes the data, holds a maximum of 2,024 bytes (2048 on Mac hardware). This function fails if the BSerialPort object doesn't have a port open.

The number of bytes that `Read()` will read 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.

  The default shouldBlock setting is `true`.

- `SetTimeout()` sets a time limit on how long `Read()` will block while waiting for data to arrive at the port's 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, regardless of the shouldBlock setting.

  There is no time limit if the timeout is set to `B_INFINITE_TIMEOUT`—`Read()` (and `WaitForInput()`) will block forever. Otherwise, the timeout is expressed in microseconds and can range from a minimum of 100,000 (0.1 second) through a maximum of 25,500,000 (25.5 seconds); differences less than 100,000 microseconds are not recognized; they're rounded to the nearest tenth of a second.

RETURN CODES

`Read()` returns...

- non-negative integer. Success; the value is the number of bytes that were read.

RETURN CODES

`SetTimeout()` returns...

- `B_OK`. Success.

### SetBlocking() see Read()

### SetDataBits() , SetStopBits() , SetParityMode() , DataBits() , StopBits() , ParityMode() , data_bits , stop_bits , parity_mode

void `SetDataBits(`data_bits count`) `
void `SetStopBits(`stop_bits count`) ```
data_bits `DataBits(`void`) `
stop_bits `StopBits(`void`) ```
typedef enum { `B_DATA_BITS_7`, `B_DATA_BITS_8` } `data_bits`
typedef enum { `B_STOP_BITS_1`, `B_STOP_BITS_2` } `stop_bits`

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 default is `B_DATA_BITS_8`.

- `SetStopBits()` sets the number of stop bits in each unit; the default is `B_STOP_BITS_2`.

- `SetParityMode()` sets whether the serial unit contains a parity bit and, if so, the type of parity used; the default is `B_NO_PARITY`.

### SetDataRate() , DataRate() , data_rate

status_t `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.

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.

RETURN CODES

`SetDataRate() returns...`

- `B_OK. The rate was successfully set.

  `

### SetDTR()

status_t `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`. The function should always returns `B_OK`.

### SetFlowControl() , FlowControl()

void `SetFlowControl(`uint32 mask`) `
uint32 `FlowControl(`void`) `

These functions set and return the type of flow control the driver should use. There are four possibilities:

Control Code | Meaning
--- | ---
`B_SOFTWARE_CONT ROL` | Control is maintained through XON and XOFF characters inserted into the data stream.
`B_HARDWARE_CONT ROL` | Control is maintained through the Clear to Send (CTS) and Request to Send (RTS) pins.
`B_SOFTWARE_CONT ROL` + `B_HARDWARE_CONT ROL` | Both of the above.
0 (zero) | No control.

`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.

### SetParityMode() see SetDataBits()

### SetRTS()

status_t `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`. The function always returns `B_OK`.

### SetStopBits() see SetDataBits()

### SetTimeout() see Read()

### WaitForInput()

ssize_t `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 already waiting, the function returns immediately.

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.

### Write()

ssize_t `Write(`const void *data, size_t 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 (1024 on Mac hardware).

RETURN CODES

non-negative integer. Success; the value is the number of bytes that were written.

- `B_INTERRUPTED`. The operation was interrupted by a signal.

The Device Kit Table of Contents | The Device Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..