BSerialPort provides an interface for communicating with devices connected through a serial port. More...

Public Member Functions
	BSerialPort ()
	Creates and initializes a BSerialPort object.

virtual	~BSerialPort ()
	Frees the resources associated with the object.

void	ClearInput ()
	Clears the input buffer. This discards the data received but not read by Read().

void	ClearOutput ()
	Clears the output buffer. This discards the data written to the output buffer with Write() but not yet transmitted to the other endpoint.

void	Close ()
	Closes the port.

int32	CountDevices ()
	Counts the number of available serial ports.

data_bits	DataBits ()
	Gets the current data bits.

data_rate	DataRate ()
	Gets the current baud rate.

uint32	FlowControl ()
	Returns the selected flow control.

status_t	GetDeviceName (int32 index, char *name, size_t bufSize=B_OS_NAME_LENGTH)
	Gets the device name by the given index.

bool	IsCTS ()
	Checks if the Clear To Send (CTS) pin is asserted (in an active state).

bool	IsDCD ()
	Checks if the Data Carrier Detect (DCD) pin is asserted (in an active state).

bool	IsDSR ()
	Checks if the Data Set Ready (DSR) pin is asserted (in an active state).

bool	IsRI ()
	Checks if the Ring Indicator (RI) pin is asserted (in an active state).

status_t	NumCharsAvailable (int32 *waitThisMany)
	Unimplemented.

status_t	Open (const char *portName)
	Opens a serial port represented by portName.

parity_mode	ParityMode ()
	Gets the parity mode.

ssize_t	Read (void *buf, size_t count)
	Reads some bytes from the serial port.

void	SetBlocking (bool blocking)
	Sets the blocking mode.

void	SetDataBits (data_bits numBits)
	Sets the data bits.

status_t	SetDataRate (data_rate bitsPerSecond)
	Sets the baud rate for the port.

status_t	SetDTR (bool asserted)
	Sets the Data Terminal Ready (DTR) pin active if asserted is `true`, or inactive if it is `false`.

void	SetFlowControl (uint32 method)
	Sets the flow control.

void	SetParityMode (parity_mode which)
	Sets the parity mode.

status_t	SetRTS (bool asserted)
	Sets the Request To Send (RTS) pin active if asserted is `true`, or inactive if it is `false`.

void	SetStopBits (stop_bits numBits)
	Sets the stop bits.

status_t	SetTimeout (bigtime_t microSeconds)
	Sets the timeout period for how long Read() and WaitForInput() will wait for the data to arrive to the port's input buffer before returning.

stop_bits	StopBits ()
	Gets the current stop bits.

ssize_t	WaitForInput ()
	Waits until there is something to read from the serial port.

ssize_t	Write (const void *buf, size_t count)
	Writes some bytes to the serial port.

Detailed Description

BSerialPort provides an interface for communicating with devices connected through a serial port.

To start a connection with a serial port:

Create a BSerialPort object
Use Open() to open a specific serial port
If the port is successfully open, use Read() and Write() to communicate.

For example:

status_t
SendDataToSerialPort(const char* port, const void* data, size_t length)
{
    // Creates an object and configures it.
    // At this point the object is not yet connected to any serial port
    BSerialPort serialPort;
    serialPort.SetDataRate(B_57600_BPS);
    serialPort.SetFlowControl(B_SOFTWARE_CONTROL);
 
    // Opens the serial port
    if (serialPort.Open(port) <= 0)
        return B_ERROR;
 
    // Performs any operations...
    ssize_t writtenBytes = serialPort.Write(data, length);
 
    // ...
 
    serialPort.Close();
    return (writtenBytes >= 0) ? B_OK : B_IO_ERROR;
}

To know which serial ports are available to the system, the methods CountDevices() and GetDeviceName() allow to retrieve a list of them:

void
GetSerialPortsNames(BStringList& outPortList)
{
    BSerialPort serialPort;
    char portName[B_OS_NAME_LENGTH]; // Ports paths temporary storage
 
    outPortList.MakeEmpty();
 
    for (int32 i = 0; i < serialPort.CountDevices(); i++) {
        // For each found port...
        if (serialPort.GetDeviceName(i, portName) == B_OK) {
            // try to open it to know if it is available to us
            if (serialPort.Open(portName) > 0) {
                // Add it to the list because we can access it,
                // and close it so we can test the next
                outPortList.Add(portName);
                serialPort.Close();
            }
        }
    }
}

Since: BeOS R3

Constructor & Destructor Documentation

◆ BSerialPort()

BSerialPort::BSerialPort ( )

Creates and initializes a BSerialPort object.

Queries the driver, and builds a list of the available serial ports. The BSerialPort object is initialized to these values:

B_19200_BPS
B_DATA_BITS_8
B_STOP_BIT_1
B_NO_PARITY
B_HARDWARE_CONTROL
B_INFINITE_TIMEOUT
Blocking mode enabled

At this point the object does not have any specific serial port selected. To connect and work with a serial port it has to be opened using Open().

Since: BeOS R3

◆ ~BSerialPort()

BSerialPort::~BSerialPort ( )

virtual

Frees the resources associated with the object.

Closes the port, if it is open, and deletes the devices list.

Since: BeOS R3

Member Function Documentation

◆ ClearInput()

void BSerialPort::ClearInput ( )

Clears the input buffer. This discards the data received but not read by Read().

Since: BeOS R3

◆ ClearOutput()

void BSerialPort::ClearOutput ( )

Clears the output buffer. This discards the data written to the output buffer with Write() but not yet transmitted to the other endpoint.

Since: BeOS R3

◆ Close()

void BSerialPort::Close ( )

Closes the port.

See also: Open()

Since: BeOS R3

◆ CountDevices()

int32 BSerialPort::CountDevices ( )

Counts the number of available serial ports.

Returns: An integer which represents the number of available serial ports.

See also: GetDeviceName()

Since: BeOS R3

◆ DataBits()

data_bits BSerialPort::DataBits ( )

Gets the current data bits.

Returns: The current data bits.

See also: SetDataBits()

Since: BeOS R3

◆ DataRate()

data_rate BSerialPort::DataRate ( )

Gets the current baud rate.

Returns: The current baud rate.

See also: SetDataRate()

Since: BeOS R3

◆ FlowControl()

uint32 BSerialPort::FlowControl ( )

Returns the selected flow control.

Returns: The flow control for the current open port.

See also: SetFlowControl()

Since: BeOS R3

◆ GetDeviceName()

status_t BSerialPort::GetDeviceName	(	int32	index,
		char *	name,
		size_t	bufSize = `B_OS_NAME_LENGTH`
	)

Gets the device name by the given index.

Parameters

[in]	index	Index number of the device to know the name of.
[out]	name	The buffer where to store the name.
[in]	bufSize	The size of the buffer.

Return values

B_OK	The device name of the device at index was copied successfully.
B_ERROR	No device was found at index.

See also: CountDevices()

Since: BeOS R3

◆ IsCTS()

bool BSerialPort::IsCTS ( )

Checks if the Clear To Send (CTS) pin is asserted (in an active state).

Return values

true	CTS is asserted.
false	CTS is not asserted.

Since: BeOS R3

◆ IsDCD()

bool BSerialPort::IsDCD ( )

Checks if the Data Carrier Detect (DCD) pin is asserted (in an active state).

Return values

true	DCD is asserted.
false	DCD is not asserted.

Since: BeOS R3

◆ IsDSR()

bool BSerialPort::IsDSR ( )

Checks if the Data Set Ready (DSR) pin is asserted (in an active state).

Return values

true	DSR is asserted.
false	DSR is not asserted.

Since: BeOS R3

◆ IsRI()

bool BSerialPort::IsRI ( )

Checks if the Ring Indicator (RI) pin is asserted (in an active state).

Return values

true	RI is asserted.
false	RI is not asserted.

Since: BeOS R3

◆ NumCharsAvailable()

status_t BSerialPort::NumCharsAvailable ( int32 * waitThisMany )

Unimplemented.

Since: BeOS R3

◆ Open()

status_t BSerialPort::Open ( const char * portName )

Opens a serial port represented by portName.

Parameters

[in] portName A valid port name (i.e. "/dev/ports/serial2").

Returns: A positive number (a file descriptor) if the serial port has been succesfully opened or an error code (negative integer) if an error has occurred.

Return values

B_BAD_BALUE portName is NULL.

See also: Close()

Since: BeOS R3

◆ ParityMode()

parity_mode BSerialPort::ParityMode ( )

Gets the parity mode.

Returns: The current parity mode.

See also: SetParityMode()

Since: BeOS R3

◆ Read()

ssize_t BSerialPort::Read	(	void *	buf,
		size_t	count
	)

Reads some bytes from the serial port.

If blocking mode is enabled, Read() will block, returning either after the whole count bytes arrive or the time limit set with SetTimeout() is not infinite and reaches zero. If the timeout is B_INFINITE_TIMEOUT it will keep blocking forever.

With blocking mode disabled, it takes as much bytes as there are in the port's input buffer up to count bytes, if any, and returns immediately.

Parameters

[out]	buf	The buffer where to copy the data.
[in]	count	The maximum amount of bytes to read.

Returns: The amount of data read or an error code.

Return values

B_FILE_ERROR	The serial port is not available or it was closed.
B_WOULD_BLOCK	The operation cannot be performed immediately and the request must not block.
B_TIMED_OUT	Blocking mode is enabled and the timeout period has ended before the count amount of data arrived at the serial port.
B_INTERRUPTED	The operation was interrupted by a signal.

Since: BeOS R3

◆ SetBlocking()

void BSerialPort::SetBlocking ( bool blocking )

Sets the blocking mode.

Parameters

[in] blocking If true, enables the blocking mode. If false, disables it.

Since: BeOS R3

◆ SetDataBits()

void BSerialPort::SetDataBits ( data_bits numBits )

Sets the data bits.

This operation will fail silently if the driver does not support the requested number of data bits. To make sure the setting was applied it is required to check DataBits().

Parameters

[in] numBits The number of data bits.

See also: DataBits()

Since: BeOS R3

◆ SetDataRate()

status_t BSerialPort::SetDataRate ( data_rate bitsPerSecond )

Sets the baud rate for the port.

To set a custom data rate not defined in the data_rate enumeration you can pass the number of bits per second directly in bitsPerSecond, but the value has to be above 50.

Parameters

[in] bitsPerSecond The baud rate.

Returns: B_OK if successful, or an error code if something went wrong.

See also: DataRate()

Since: BeOS R3

◆ SetDTR()

status_t BSerialPort::SetDTR ( bool asserted )

Sets the Data Terminal Ready (DTR) pin active if asserted is true, or inactive if it is false.

Parameters

[in] asserted The DTR status wanted.

Return values

B_OK	DTR pin state was changed.
B_ERROR	DTR pin state could not be changed or an error has occurred.

Since: BeOS R3

◆ SetFlowControl()

void BSerialPort::SetFlowControl ( uint32 method )

Sets the flow control.

Valid values for method are:

B_NOFLOW_CONTROL to not perform flow control.
B_HARDWARE_CONTROL to perform flow control via hardware.
B_SOFTWARE_CONTROL to perform flow control via software.
B_HARDWARE_CONTROL | B_SOFTWARE_CONTROL to perform flow control via both hardware and software.

Parameters

[in] method The type of flow control.

See also: FlowControl()

Since: BeOS R3

◆ SetParityMode()

void BSerialPort::SetParityMode ( parity_mode which )

Sets the parity mode.

Valid values for which are:

B_NO_PARITY to not send a parity bit.
B_ODD_PARITY to send a parity bit and set it to have an odd number of "1" bits in the transmission.
B_EVEN_PARITY to send a parity bit and set it to have an even number of "1" bits in the transmission.

Parameters

[in] which The parity mode to set.

See also: ParityMode()

Since: BeOS R3

◆ SetRTS()

status_t BSerialPort::SetRTS ( bool asserted )

Sets the Request To Send (RTS) pin active if asserted is true, or inactive if it is false.

Parameters

[in] asserted The RTS status wanted.

Return values

B_OK	RTS pin state was changed.
B_ERROR	RTS pin state could not be changed or an error has occurred.

Since: BeOS R3

◆ SetStopBits()

void BSerialPort::SetStopBits ( stop_bits numBits )

Sets the stop bits.

This operation will fail silently if the driver does not support the requested number of stop bits. To make sure the setting was applied it is required to check StopBits().

Parameters

[in] numBits The number of stop bits.

See also: StopBits()

Since: BeOS R3

◆ SetTimeout()

status_t BSerialPort::SetTimeout ( bigtime_t microSeconds )

Sets the timeout period for how long Read() and WaitForInput() will wait for the data to arrive to the port's input buffer before returning.

The timeout period only applies when in blocking mode. In non-blocking mode it takes no effect.

Parameters

[in]

microSeconds

The timeout for the port. Valid values are:

B_INFINITE_TIMEOUT to wait forever
Any value between 0 and 25000000 microseconds.

Return values

B_OK	Timeout changed successfully.
B_BAD_VALUE	The timeout value provided by microSeconds was invalid.

Since: BeOS R3

◆ StopBits()

stop_bits BSerialPort::StopBits ( )

Gets the current stop bits.

Returns: The current stop bits.

See also: SetStopBits()

Since: BeOS R3

◆ WaitForInput()

ssize_t BSerialPort::WaitForInput ( )

Waits until there is something to read from the serial port.

If no data is ready, it will always block, ignoring the value of SetBlocking(); however, it respects the timeout set by SetTimeout().

Returns: The number of bytes available to be read or an error code.

Since: BeOS R3

◆ Write()

ssize_t BSerialPort::Write	(	const void *	buf,
		size_t	count
	)

Writes some bytes to the serial port.

In blocking mode, Write() will write exactly the full contents of buf, even if this makes it to wait.

In non-blocking mode, it will write as many bytes as it can, which may not be the complete buffer, and then returns immediately.

Parameters

[in]	buf	The buffer from where to copy the data.
[in]	count	The amount of bytes to write.

Returns: The amount of data written or an error code.

Return values

B_FILE_ERROR	The serial port is not available or it was closed.
B_WOULD_BLOCK	The operation cannot be performed immediately and the request must not block.
B_INTERRUPTED	The operation was interrupted by a signal.

Since: BeOS R3

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BSerialPort()

◆ ~BSerialPort()

Member Function Documentation

◆ ClearInput()

◆ ClearOutput()

◆ Close()

◆ CountDevices()

◆ DataBits()

◆ DataRate()

◆ FlowControl()

◆ GetDeviceName()

◆ IsCTS()

◆ IsDCD()

◆ IsDSR()

◆ IsRI()

◆ NumCharsAvailable()

◆ Open()

◆ ParityMode()

◆ Read()

◆ SetBlocking()

◆ SetDataBits()

◆ SetDataRate()

◆ SetDTR()

◆ SetFlowControl()

◆ SetParityMode()

◆ SetRTS()

◆ SetStopBits()

◆ SetTimeout()

◆ StopBits()

◆ WaitForInput()

◆ Write()