The SerialPortStream is a stream class to communicate with serial port based devices. More...

Inheritance diagram for RJCP.IO.Ports.SerialPortStream:

Public Member Functions
	SerialPortStream ()
	Constructor. Create a stream that doesn't connect to any port. More...

	SerialPortStream (string port)
	Constructor. Create a stream that connects to the specified port. More...

	SerialPortStream (string port, int baud)
	Constructor. Create a stream that connects to the specified port and sets the initial baud rate. More...

	SerialPortStream (string port, int baud, int data, Parity parity, StopBits stopbits)
	Constructor. Create a stream that connects to the specified port with standard parameters. More...

void	GetPortSettings ()
	Update properties based on the current port, overwriting already existing properties. More...

void	Open ()
	Opens a new serial port connection. More...

void	OpenDirect ()
	Opens a new serial port connection with control if the port settings are initialised or not. More...

new void	Close ()
	Closes the port connection, sets the IsOpen property to false. Does not dispose the object. More...

override int	Read (byte[] buffer, int offset, int count)
	Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. More...

override IAsyncResult	BeginRead (byte[] buffer, int offset, int count, AsyncCallback callback, object state)
	Begins an asynchronous read operation. More...

override int	EndRead (IAsyncResult asyncResult)
	Waits for the pending asynchronous read to complete. More...

override int	ReadByte ()
	Synchronously reads one byte from the SerialPort input buffer. More...

int	Read (char[] buffer, int offset, int count)
	Reads a number of characters from the SerialPortStream input buffer and writes them into an array of characters at a given offset. More...

int	ReadChar ()
	Synchronously reads one character from the SerialPortStream input buffer. More...

string	ReadLine ()
	Reads up to the NewLine value in the input buffer. More...

string	ReadTo (string text)
	Reads a string up to the specified text in the input buffer. More...

string	ReadExisting ()
	Reads all immediately available bytes. More...

void	DiscardInBuffer ()
	Discards data from the serial driver's receive buffer. More...

override void	Flush ()
	Clears all buffers for this stream and causes any buffered data to be written to the underlying device. More...

override void	Write (byte[] buffer, int offset, int count)
	Write the given data into the buffered serial stream for sending over the serial port. More...

override IAsyncResult	BeginWrite (byte[] buffer, int offset, int count, AsyncCallback callback, object state)
	Begins an asynchronous write operation. More...

override void	EndWrite (IAsyncResult asyncResult)
	Ends an asynchronous write operation. More...

void	Write (char[] buffer, int offset, int count)
	Writes a specified number of characters to the serial port using data from a buffer. More...

void	Write (string text)
	Writes the specified string to the serial port. More...

void	WriteLine (string text)
	Writes the specified string and the NewLine value to the output buffer. More...

void	DiscardOutBuffer ()
	Discards data from the serial driver's transmit buffer. More...

override long	Seek (long offset, SeekOrigin origin)
	This stream does not support seeking. More...

override void	SetLength (long value)
	This stream does not support the SetLength property. More...

override string	ToString ()
	Returns a System.String that represents this instance. More...

Static Public Member Functions
static string []	GetPortNames ()
	Gets an array of serial port names for the current computer. More...

static PortDescription []	GetPortDescriptions ()
	Gets an array of serial port names and descriptions for the current computer. More...

Public Attributes
const int	InfiniteTimeout = Timeout.Infinite
	Indicates that no time out should occur. More...

Protected Member Functions
virtual void	OnDataReceived (object sender, SerialDataReceivedEventArgs args)
	Called when data is received, or the EOF character is detected by the driver. More...

virtual void	OnCommError (object sender, SerialErrorReceivedEventArgs args)
	Called when an error condition is detected. More...

virtual void	OnPinChanged (object sender, SerialPinChangedEventArgs args)
	Called when modem pin changes are detected. More...

override void	Dispose (bool disposing)
	Clean up all resources managed by this object. More...

Properties
string	Version `[get]`
	Get the version of this assembly (or components driving this assembly). More...

string	PortName `[get, set]`
	Gets the port for communications, including but not limited to all available COM ports. More...

bool	IsOpen `[get]`
	Gets a value indicating the open or closed status of the SerialPortStream object. More...

Encoding	Encoding `[get, set]`
	Gets or sets the byte encoding for pre- and post-transmission conversion of text. More...

string	NewLine `[get, set]`
	Gets or sets the value used to interpret the end of a call to the ReadLine and WriteLine methods. More...

int	DriverInQueue `[get, set]`
	Specify the driver In Queue at the time it is opened. More...

int	DriverOutQueue `[get, set]`
	Specify the driver Out Queue at the time it is opened. More...

override bool	CanTimeout `[get]`
	Gets a value that determines whether the current stream can time out. More...

override bool	CanRead `[get]`
	Check if this stream supports reading. More...

override int	ReadTimeout `[get, set]`
	Define the time out when reading data from the stream. More...

int	ReadBufferSize `[get, set]`
	Gets or sets the size of the SerialPortStream input buffer. More...

int	ReceivedBytesThreshold `[get, set]`
	Gets or sets the number of bytes in the read buffer before a DataReceived event occurs. More...

int	BytesToRead `[get]`
	Gets the number of bytes of data in the receive buffer. More...

override bool	CanWrite `[get]`
	Check if this stream supports writing. More...

override int	WriteTimeout `[get, set]`
	Define the time out when writing data to the local buffer. More...

int	WriteBufferSize `[get, set]`
	Gets or sets the size of the serial port output buffer. More...

int	BytesToWrite `[get]`
	Gets the number of bytes of data in the send buffer. More...

bool	CDHolding `[get]`
	Gets the state of the Carrier Detect line for the port. More...

bool	CtsHolding `[get]`
	Gets the state of the Clear-to-Send line. More...

bool	DsrHolding `[get]`
	Gets the state of the Data Set Ready (DSR) signal. More...

bool	RingHolding `[get]`
	Gets the state of the Ring line signal. More...

int	BaudRate `[get, set]`
	Gets or sets the serial baud rate. More...

int	DataBits `[get, set]`
	Gets or sets the standard length of data bits per byte. More...

StopBits	StopBits `[get, set]`
	Gets or sets the standard number of stop bits per byte. More...

Parity	Parity `[get, set]`
	Gets or sets the parity-checking protocol. More...

byte	ParityReplace `[get, set]`
	Gets or sets the byte that replaces invalid bytes in a data stream when a parity error occurs. More...

bool	DiscardNull `[get, set]`
	Gets or sets a value indicating whether null bytes are ignored when transmitted between the port and the receive buffer. More...

bool	DtrEnable `[get, set]`
	Gets or sets a value that enables the Data Terminal Ready (DTR) signal during serial communication. More...

bool	RtsEnable `[get, set]`
	Gets or sets a value indicating whether the Request to Send (RTS) signal is enabled during serial communication. More...

Handshake	Handshake `[get, set]`
	Gets or sets the handshaking protocol for serial port transmission of data. More...

int	XOnLimit `[get, set]`
	Define the limit of actual bytes in the transmit buffer when XON is sent. More...

int	XOffLimit `[get, set]`
	Define the limit of free bytes in the buffer before XOFF is sent. More...

bool	TxContinueOnXOff `[get, set]`
	Enable or Disable transmit of data when software flow control is enabled. More...

bool	BreakState `[get, set]`
	Gets or sets the break signal state. More...

override bool	CanSeek `[get]`
	This stream is not seekable, so always returns false. More...

override long	Length `[get]`
	This stream does not support the Length property. More...

override long	Position `[get, set]`
	This stream does not support the Position property. More...

bool	IsDisposed `[get]`
	Indicates if this object has already been disposed. More...

Events
EventHandler< SerialDataReceivedEventArgs >	DataReceived
	Occurs when data is received, or the EOF character is detected by the driver. More...

EventHandler< SerialErrorReceivedEventArgs >	ErrorReceived
	Occurs when an error condition is detected. More...

EventHandler< SerialPinChangedEventArgs >	PinChanged
	Occurs when modem pin changes are detected. More...

Detailed Description

The SerialPortStream is a stream class to communicate with serial port based devices.

This implementation is a ground up reimplementation of the Microsoft SerialPort class but one that is a stream. There are numerous small issues with the Microsoft .NET 4.0 implementation (and assumed earlier) that this class attempts to resolve.

For detailed information about serial port programming, refer to the site: http://msdn.microsoft.com/en-us/library/ms810467.aspx

When instantiating.

Constructor & Destructor Documentation

◆ SerialPortStream() [1/4]

RJCP.IO.Ports.SerialPortStream.SerialPortStream ( )

Constructor. Create a stream that doesn't connect to any port.

This constructor initialises a stream object, but doesn't assign it to any COM port. The properties then assume default settings. No COM port is opened and queried.

◆ SerialPortStream() [2/4]

RJCP.IO.Ports.SerialPortStream.SerialPortStream ( string port )

Constructor. Create a stream that connects to the specified port.

This constructor attempts to bind directly to the port given. Properties assume the settings of the port provided. Exceptions may occur if the port cannot be opened.

Parameters

port	The name of the COM port, such as "COM1" or "COM33".

◆ SerialPortStream() [3/4]

RJCP.IO.Ports.SerialPortStream.SerialPortStream	(	string	port,
		int	baud
	)

Constructor. Create a stream that connects to the specified port and sets the initial baud rate.

The stream doesn't impose any arbitrary limits on setting the baud rate. It is passed directly to the driver and it is up to the driver to determine if the baud rate is settable or not. Normally, a driver will attempt to set a baud rate that is within 5% of the requested baud rate (but not guaranteed).

Parameters

port	The name of the COM port, such as "COM1" or "COM33".
baud	The baud rate that is passed to the underlying driver.

◆ SerialPortStream() [4/4]

RJCP.IO.Ports.SerialPortStream.SerialPortStream	(	string	port,
		int	baud,
		int	data,
		Parity	parity,
		StopBits	stopbits
	)

Constructor. Create a stream that connects to the specified port with standard parameters.

The stream doesn't impose any arbitrary limits on setting the baud rate. It is passed directly to the driver and it is up to the driver to determine if the baud rate is settable or not. Normally, a driver will attempt to set a baud rate that is within 5% of the requested baud rate (but not guaranteed).

Not all combinations are supported. The driver will interpret the data and indicate if configuration is possible or not.

Parameters

port	The name of the COM port, such as "COM1" or "COM33".
baud	The baud rate that is passed to the underlying driver.
data	The number of data bits. This is checked that the driver supports the data bits provided. The special type 16X is not supported.
parity	The parity for the data stream.
stopbits	Number of stop bits.

Member Function Documentation

◆ BeginRead()

override IAsyncResult RJCP.IO.Ports.SerialPortStream.BeginRead	(	byte []	buffer,
		int	offset,
		int	count,
		AsyncCallback	callback,
		object	state
	)

Begins an asynchronous read operation.

Parameters

buffer	The buffer to read the data into.
offset	The byte offset in buffer at which to begin writing data read from the stream.
count	The maximum number of bytes to read.
callback	An optional asynchronous callback, to be called when the read is complete.
state	A user-provided object that distinguishes this particular asynchronous read request from other requests.

Returns: An IAsyncResult object to be used with EndRead.

◆ BeginWrite()

override IAsyncResult RJCP.IO.Ports.SerialPortStream.BeginWrite	(	byte []	buffer,
		int	offset,
		int	count,
		AsyncCallback	callback,
		object	state
	)

Begins an asynchronous write operation.

Parameters

buffer	The buffer to write data from.
offset	The byte offset in buffer from which to begin writing.
count	The maximum number of bytes to write.
callback	An optional asynchronous callback, to be called when the write is complete.
state	A user-provided object that distinguishes this particular asynchronous write request from other requests.

Returns: An IAsyncResult that represents the asynchronous write, which could still be pending.

Exceptions

System.ArgumentNullException	NULL buffer was provided.
System.ArgumentOutOfRangeException	Negative offset or negative count provided.
System.ArgumentException	Offset and count exceed buffer boundaries.
System.InvalidOperationException	Serial port not open.

◆ Close()

new void RJCP.IO.Ports.SerialPortStream.Close ( )

Closes the port connection, sets the IsOpen property to false. Does not dispose the object.

This method will clean up the object so far as to close the port. Internal buffers remain active that the stream can continue to read. Writes will throw an exception.

◆ DiscardInBuffer()

void RJCP.IO.Ports.SerialPortStream.DiscardInBuffer ( )

Discards data from the serial driver's receive buffer.

This function will discard the receive buffer of the SerialPortStream.

◆ DiscardOutBuffer()

void RJCP.IO.Ports.SerialPortStream.DiscardOutBuffer ( )

Discards data from the serial driver's transmit buffer.

Clears the local buffer for data not yet sent to the serial port, as well as attempting to clear the buffers in the driver itself.

◆ Dispose()

override void RJCP.IO.Ports.SerialPortStream.Dispose ( bool disposing )

protected

Clean up all resources managed by this object.

Parameters

disposing true if the user is disposing this object, false if being cleaned up by the finalizer.

◆ EndRead()

override int RJCP.IO.Ports.SerialPortStream.EndRead ( IAsyncResult asyncResult )

Waits for the pending asynchronous read to complete.

Parameters

asyncResult The reference to the pending asynchronous request to finish.

Exceptions

ObjectDisposedException

Exceptions

IOException Device Error (e.g. device removed).

Returns: The number of bytes read from the stream, between zero (0) and the number of bytes you requested. Streams return zero (0) only at the end of the stream, otherwise, they should block until at least one byte is available.

◆ EndWrite()

override void RJCP.IO.Ports.SerialPortStream.EndWrite ( IAsyncResult asyncResult )

Ends an asynchronous write operation.

Parameters

asyncResult A reference to the outstanding asynchronous I/O request.

Exceptions

System.TimeoutException	Not enough buffer space was made available before the time out expired.
System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

EndWrite must be called exactly once on every IAsyncResult from BeginWrite.

◆ Flush()

override void RJCP.IO.Ports.SerialPortStream.Flush ( )

Clears all buffers for this stream and causes any buffered data to be written to the underlying device.

Exceptions

System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.TimeoutException	Flush write time out exceeded.
System.InvalidOperationException	Serial Port not opened.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

◆ GetPortDescriptions()

static PortDescription [] RJCP.IO.Ports.SerialPortStream.GetPortDescriptions ( )

static

Gets an array of serial port names and descriptions for the current computer.

This method uses the Windows Management Interface to obtain its information. Therefore, the list may be different to the list obtained using the GetPortNames() method which uses other techniques.

On Windows 7, this method shows to return normal COM ports, but not those associated with a modem driver.

Returns: An array of serial ports for the current computer.

◆ GetPortNames()

static string [] RJCP.IO.Ports.SerialPortStream.GetPortNames ( )

static

Gets an array of serial port names for the current computer.

Returns: An array of serial port names for the current computer.

◆ GetPortSettings()

void RJCP.IO.Ports.SerialPortStream.GetPortSettings ( )

Update properties based on the current port, overwriting already existing properties.

Exceptions

System.ObjectDisposedException

Exceptions

System.InvalidOperationException Serial Port already opened.

This method opens the serial port and retrieves the current settings from Windows. These settings are then made available via the various properties, BaudRate, DataBits, Parity, ParityReplace, Handshake, StopBits, TxContinueOnXoff, DiscardNull, XOnLimit and XOffLimit.

◆ OnCommError()

virtual void RJCP.IO.Ports.SerialPortStream.OnCommError	(	object	sender,
		SerialErrorReceivedEventArgs	args
	)

protectedvirtual

Called when an error condition is detected.

Parameters

sender	The sender.
args	The SerialErrorReceivedEventArgs instance containing the event data.

◆ OnDataReceived()

virtual void RJCP.IO.Ports.SerialPortStream.OnDataReceived	(	object	sender,
		SerialDataReceivedEventArgs	args
	)

protectedvirtual

Called when data is received, or the EOF character is detected by the driver.

Parameters

sender	The sender.
args	The SerialDataReceivedEventArgs instance containing the event data.

◆ OnPinChanged()

virtual void RJCP.IO.Ports.SerialPortStream.OnPinChanged	(	object	sender,
		SerialPinChangedEventArgs	args
	)

protectedvirtual

Called when modem pin changes are detected.

Parameters

sender	The sender.
args	The SerialPinChangedEventArgs instance containing the event data.

◆ Open()

void RJCP.IO.Ports.SerialPortStream.Open ( )

Opens a new serial port connection.

Exceptions

InvalidOperationException	This object is already managing a serial port connection.
System.ObjectDisposedException	SerialPortStream is disposed of.

Opens a connection to the serial port provided by the constructor or the Port property. If this object is already managing a serial port, this object raises an exception.

When opening the port, only the settings explicitly applied will be given to the port. That is, if you read the default BaudRate as 115200, this value will only be applied if you explicitly set it to 115200. Else the default baud rate of the serial port when its opened will be used.

Normally when you instantiate this stream on a COM port, it is opened for a brief time and queried for the capabilities and default settings. This allows your application to use the settings that were already available (such as defined by the windows user in the Control Panel, or the last open application). If you require to open the COM port without briefly opening it to query its status, then you need to instantiate this object through the default constructor. Set the property UpdateOnPortSet to false and then set the Port property. Provide all the other properties you require then call the Open() method. The port will be opened using the default properties providing you with a consistent environment (independent of the state of the Operating System or the driver beforehand).

◆ OpenDirect()

void RJCP.IO.Ports.SerialPortStream.OpenDirect ( )

Opens a new serial port connection with control if the port settings are initialised or not.

Exceptions

System.ObjectDisposedException	SerialPortStream is disposed of.
System.InvalidOperationException	Serial Port already opened

Opens a connection to the serial port provided by the constructor or the Port property. If this object is already managing a serial port, this object raises an exception.

You can override the open so that no communication settings are retrieved or set. This is useful for virtual COM ports that do not manage state bits (some as some emulated COM ports or USB based communications that present themselves as a COM port but do not have any underlying physical RS232 implementation).

<note type="note">If you use this method to avoid setting parameters for the serial port, instead only to open the serial port, you should be careful not to set any properties associated with the serial port, as they will set the communications properties.</note>

◆ Read() [1/2]

override int RJCP.IO.Ports.SerialPortStream.Read	(	byte []	buffer,
		int	offset,
		int	count
	)

Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Parameters

buffer	An array of bytes. When this method returns, the buffer contains the specified byte array with the values between offset and (offset count - 1) replaced by the bytes read from the current source.
offset	The zero-based byte offset in buffer at which to begin storing the data read from the current stream.
count	The maximum number of bytes to be read from the current stream.

Exceptions

ObjectDisposedException

Exceptions

ArgumentNullException	Null buffer provided.
ArgumentOutOfRangeException	Negative offset provided, or negative count provided.
ArgumentException	Offset and count exceed buffer boundaries.
IOException	Device Error (e.g. device removed).

Returns: The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if the end of the stream has been reached.

◆ Read() [2/2]

int RJCP.IO.Ports.SerialPortStream.Read	(	char []	buffer,
		int	offset,
		int	count
	)

Reads a number of characters from the SerialPortStream input buffer and writes them into an array of characters at a given offset.

Parameters

buffer	The character array to write the input to.
offset	Offset into the buffer where to start putting the data.
count	Maximum number of bytes to read into the buffer.

Returns: The actual number of bytes copied into the buffer, 0 if there was a time out.

Exceptions

IOException Device Error (e.g. device removed).

This function converts the data in the local buffer to characters based on the encoding defined by the encoding property. The encoder used may buffer data between calls if characters may require more than one byte of data for its interpretation as a character.

◆ ReadByte()

override int RJCP.IO.Ports.SerialPortStream.ReadByte ( )

Synchronously reads one byte from the SerialPort input buffer.

Returns: The byte, cast to an Int32, or -1 if the end of the stream has been read.

Exceptions

IOException Device Error (e.g. device removed).

◆ ReadChar()

int RJCP.IO.Ports.SerialPortStream.ReadChar ( )

Synchronously reads one character from the SerialPortStream input buffer.

Returns: The character that was read. -1 indicates no data was available within the time out.

◆ ReadExisting()

string RJCP.IO.Ports.SerialPortStream.ReadExisting ( )

Reads all immediately available bytes.

Reads all data in the current buffer. If there is no data available, then no data is returned. This is different to the Microsoft implementation, that will read all data, and if there is no data, then it waits for data based on the time outs. This method employs no time outs.

Because this method returns only the data that is currently in the cached buffer and ignores the data that is actually buffered by the driver itself, there may be a slight discrepancy between the value returned by BytesToRead and the actual length of the string returned.

This method differs slightly from the Microsoft implementation in that this function doesn't initiate a read operation, as we have a dedicated thread to reading data that is running independently.

Returns: The contents of the stream and the input buffer of the SerialPortStream.

◆ ReadLine()

string RJCP.IO.Ports.SerialPortStream.ReadLine ( )

Reads up to the NewLine value in the input buffer.

Returns: The contents of the input buffer up to the first occurrence of a NewLine value.

Exceptions

TimeoutException	Data was not available in the timeout specified.
IOException	Device Error (e.g. device removed).
ObjectDisposedException

◆ ReadTo()

string RJCP.IO.Ports.SerialPortStream.ReadTo ( string text )

Reads a string up to the specified text in the input buffer.

The ReadTo() function will read text from the byte buffer up to a predetermined limit (1024 characters) when looking for the string text. If text is not found within this limit, data is thrown away and more data is read (effectively consuming the earlier bytes).

This method is provided as compatibility with the Microsoft implementation. There are some important differences however. This method attempts to fix a minor pathological problem with the Microsoft implementation. If the string text is not found, the MS implementation may modify the internal state of the decoder. As a workaround, it pushes all decoded characters back into its internal byte buffer, which fixes the problem that a second call to the ReadTo() method returns the consistent results, but a call to Read(byte[], ..) may return data that was not actually transmitted by the DCE. This would happen in case that an invalid byte sequence was found, converted to a fall back character. The original byte sequence is removed and replaced with the byte equivalent of the fall back character.

This method is rather slow, because it tries to preserve the byte buffer in case of failure.

In case the data cannot be read, an exception is always thrown. So you may assume that if this method returns, you have valid data.

Parameters

text	The text to indicate where the read operation stops.

Returns: The contents of the input buffer up to the specified text.

Exceptions

TimeoutException	Data was not available in the timeout specified.
IOException	Device Error (e.g. device removed).
ObjectDisposedException

◆ Seek()

override long RJCP.IO.Ports.SerialPortStream.Seek	(	long	offset,
		SeekOrigin	origin
	)

This stream does not support seeking.

Parameters

offset	A byte offset relative to the origin parameter.
origin	A value of type T:System.IO.SeekOrigin indicating the reference point used to obtain the new position.

Returns: The new position within the current stream.

Exceptions

System.NotSupportedException This stream doesn't support seeking.

◆ SetLength()

override void RJCP.IO.Ports.SerialPortStream.SetLength ( long value )

This stream does not support the SetLength property.

Parameters

value The desired length of the current stream in bytes.

Exceptions

System.NotSupportedException This stream doesn't support the SetLength property.

◆ ToString()

override string RJCP.IO.Ports.SerialPortStream.ToString ( )

Returns a System.String that represents this instance.

Returns: A System.String that represents this instance.

◆ Write() [1/3]

override void RJCP.IO.Ports.SerialPortStream.Write	(	byte []	buffer,
		int	offset,
		int	count
	)

Write the given data into the buffered serial stream for sending over the serial port.

Parameters

buffer	The buffer containing data to send.
offset	Offset into the array buffer where data begins.
count	Number of bytes to copy into the local buffer.

Exceptions

System.TimeoutException	Not enough buffer space was made available before the time out expired.
System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.ArgumentNullException	NULL buffer was provided.
System.ArgumentOutOfRangeException	Negative offset or negative count provided.
System.ArgumentException	Offset and count exceed buffer boundaries.
System.InvalidOperationException	Serial port not open.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

Data is copied from the array provided into the local stream buffer. It does not guarantee that data will be sent over the serial port. So long as there is enough local buffer space to accept the write of count bytes, this function will succeed. In case that the buffered serial stream doesn't have enough data, the function will wait up to WriteTimeout milliseconds for enough buffer data to become available. In case that there is not enough space before the write time out expires, no data is copied to the local stream and the function fails with an exception.

For reliability, this function will only write data to the write buffer if the complete set of data requested can be written. This implies that the parameter count be less or equal to the number of bytes that are available in the write buffer. Equivalently, you must make sure that you have a write buffer with at least count allocated bytes or this function will always raise an exception.

◆ Write() [2/3]

void RJCP.IO.Ports.SerialPortStream.Write	(	char []	buffer,
		int	offset,
		int	count
	)

Writes a specified number of characters to the serial port using data from a buffer.

Parameters

buffer	The buffer containing data to send.
offset	Offset into the array buffer where data begins.
count	Number of characters to copy into the local buffer.

Exceptions

System.TimeoutException	Not enough buffer space was made available before the time out expired.
System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.ArgumentNullException	NULL buffer was provided.
System.ArgumentOutOfRangeException	Negative offset or negative count provided.
System.ArgumentException	Offset and count exceed buffer boundaries.
System.InvalidOperationException	Serial port not open.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

◆ Write() [3/3]

void RJCP.IO.Ports.SerialPortStream.Write ( string text )

Writes the specified string to the serial port.

Parameters

text	The string for output.

Exceptions

System.TimeoutException	Not enough buffer space was made available before the time out expired.
System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.ArgumentNullException	NULL buffer was provided.
System.ArgumentOutOfRangeException	Negative offset or negative count provided.
System.ArgumentException	Offset and count exceed buffer boundaries.
System.InvalidOperationException	Serial port not open.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

◆ WriteLine()

void RJCP.IO.Ports.SerialPortStream.WriteLine ( string text )

Writes the specified string and the NewLine value to the output buffer.

Parameters

text	The string to write to the output buffer.

Exceptions

System.TimeoutException	Not enough buffer space was made available before the time out expired.
System.ObjectDisposedException	Object is disposed, or disposed during flush operation.
System.ArgumentNullException	NULL buffer was provided.
System.ArgumentOutOfRangeException	Negative offset or negative count provided.
System.ArgumentException	Offset and count exceed buffer boundaries.
System.InvalidOperationException	Serial port not open.
System.IO.IOException	Serial Port was closed during the flush operation; or there was a device error.

Member Data Documentation

◆ InfiniteTimeout

const int RJCP.IO.Ports.SerialPortStream.InfiniteTimeout = Timeout.Infinite

Indicates that no time out should occur.

Property Documentation

◆ BaudRate

int RJCP.IO.Ports.SerialPortStream.BaudRate

getset

Gets or sets the serial baud rate.

The stream doesn't impose any arbitrary limits on setting the baud rate. It is passed directly to the driver and it is up to the driver to determine if the baud rate is settable or not. Normally, a driver will attempt to set a baud rate that is within 5% of the requested baud rate (but not guaranteed).

If the serial driver doesn't support setting the baud rate, setting this property is silently ignored and the baud rate isn't updated.

◆ BreakState

bool RJCP.IO.Ports.SerialPortStream.BreakState

getset

Gets or sets the break signal state.

The break signal state occurs when a transmission is suspended and the line is placed in a break state (all low, no stop bit) until released. To enter a break state, set this property to true. If the port is already in a break state, setting this property again to true does not result in an exception. It is not possible to write to the SerialPortStream while BreakState is true.

◆ BytesToRead

int RJCP.IO.Ports.SerialPortStream.BytesToRead

get

Gets the number of bytes of data in the receive buffer.

This method returns the number of bytes available in the input read buffer. Bytes that are cached by the driver itself are not accounted for, as they haven't yet been read by the local thread.

This has the effect, that if the local buffer is full (let's say that it is arbitrarily picked to be 64KB) and the local driver also has buffered 4KB, only the size of the local buffer is given, so 64KB (instead of the expected 68KB).

◆ BytesToWrite

int RJCP.IO.Ports.SerialPortStream.BytesToWrite

get

Gets the number of bytes of data in the send buffer.

The send buffer includes the serial driver's send buffer as well as internal buffering in the SerialPortStream itself.

◆ CanRead

override bool RJCP.IO.Ports.SerialPortStream.CanRead

get

Check if this stream supports reading.

Supported so long as the stream is not disposed.

◆ CanSeek

override bool RJCP.IO.Ports.SerialPortStream.CanSeek

get

This stream is not seekable, so always returns false.

◆ CanTimeout

override bool RJCP.IO.Ports.SerialPortStream.CanTimeout

get

Gets a value that determines whether the current stream can time out.

Returns: A value that determines whether the current stream can time out.

◆ CanWrite

override bool RJCP.IO.Ports.SerialPortStream.CanWrite

get

Check if this stream supports writing.

Supported so long as the stream is not disposed.

◆ CDHolding

bool RJCP.IO.Ports.SerialPortStream.CDHolding

get

Gets the state of the Carrier Detect line for the port.

This property can be used to monitor the state of the carrier detection line for a port. No carrier usually indicates that the receiver has hung up and the carrier has been dropped.

Windows documentation sometimes refers to the Carrier Detect line as the RLSD (Receive Line Signal Detect).

◆ CtsHolding

bool RJCP.IO.Ports.SerialPortStream.CtsHolding

get

Gets the state of the Clear-to-Send line.

The Clear-to-Send (CTS) line is used in Request to Send/Clear to Send (RTS/CTS) hardware handshaking. The CTS line is queried by a port before data is sent.

◆ DataBits

int RJCP.IO.Ports.SerialPortStream.DataBits

getset

Gets or sets the standard length of data bits per byte.

The range of values for this property is from 5 through 8 and 16. A check is made by setting this property against the advertised capabilities of the driver. That is, a driver lists its capabilities to say what byte sizes it can support. If the driver cannot support the byte size requested, an exception is raised.

Not all possible combinations are allowed by all drivers. That implies, that an exception may be raised for a valid setting of the DataBits property, if the other parameters are not valid. Such an example might be that 5-bits are only supported with 2 stop bits and not otherwise. The driver itself will raise an exception to the application in this case.

If the serial driver doesn't support setting the data bits, setting this property is silently ignored and the number of data bits isn't updated.

◆ DiscardNull

bool RJCP.IO.Ports.SerialPortStream.DiscardNull

getset

Gets or sets a value indicating whether null bytes are ignored when transmitted between the port and the receive buffer.

This value should normally be set to false, especially for binary transmissions. Setting this property to true can cause unexpected results for UTF32- and UTF16-encoded bytes.

◆ DriverInQueue

int RJCP.IO.Ports.SerialPortStream.DriverInQueue

getset

Specify the driver In Queue at the time it is opened.

This provides the driver a recommended internal input buffer, in bytes.

◆ DriverOutQueue

int RJCP.IO.Ports.SerialPortStream.DriverOutQueue

getset

Specify the driver Out Queue at the time it is opened.

This provides the driver a recommended internal output buffer, in bytes.

◆ DsrHolding

bool RJCP.IO.Ports.SerialPortStream.DsrHolding

get

Gets the state of the Data Set Ready (DSR) signal.

This property is used in Data Set Ready/Data Terminal Ready (DSR/DTR) handshaking. The Data Set Ready (DSR) signal is usually sent by a modem to a port to indicate that it is ready for data transmission or data reception.

◆ DtrEnable

bool RJCP.IO.Ports.SerialPortStream.DtrEnable

getset

Gets or sets a value that enables the Data Terminal Ready (DTR) signal during serial communication.

Data Terminal Ready (DTR) is typically enabled during XON/XOFF software handshaking and Request to Send/Clear to Send (RTS/CTS) hardware handshaking, and modem communications.

◆ Encoding

Encoding RJCP.IO.Ports.SerialPortStream.Encoding

getset

Gets or sets the byte encoding for pre- and post-transmission conversion of text.

The encoding is used for encoding string information to byte format when sending over the serial port, or receiving data via the serial port. It is only used with the read/write functions that accept strings (and not used for byte based reading and writing).

◆ Handshake

Handshake RJCP.IO.Ports.SerialPortStream.Handshake

getset

Gets or sets the handshaking protocol for serial port transmission of data.

Enables handshaking on the serial port. We support three types of handshaking: RTS/CTS; XON/XOFF; and DTR/DTS. The Microsoft implementation SerialPort only supports RTS/CTS and XON/XOFF.

This method is not 100% compatible with the Microsoft implementation. By disabling RTS flow control, it sets behaviour so that the RTS line is enabled. You must set the property RtsEnable as appropriate. Although the Microsoft implementation doesn't support DSR/DTR at all, setting this property will also set the DTR line to enabled. You must set the property DtrEnable as appropriate.

When enabling DTR flow control, the DsrSensitivity flag is set, so the driver ignores any bytes received, unless the DSR modem input line is high. Otherwise, if DTR flow control is disabled, the DSR line is ignored. For more detailed information about how windows works with flow control, see the site: http://msdn.microsoft.com/en-us/library/ms810467.aspx. When DTR flow control is specified, the fOutxDsrFlow is set along with fDsrSensitivity.

Note, the windows feature RTS_CONTROL_TOGGLE is not supported by this class. This is also not supported by the Microsoft implementation.

◆ IsDisposed

bool RJCP.IO.Ports.SerialPortStream.IsDisposed

get

Indicates if this object has already been disposed.

◆ IsOpen

bool RJCP.IO.Ports.SerialPortStream.IsOpen

get

Gets a value indicating the open or closed status of the SerialPortStream object.

The IsOpen property tracks whether the port is open for use by the caller, not whether the port is open by any application on the machine.

True if the serial port is open; otherwise, false. The default is false.

◆ Length

override long RJCP.IO.Ports.SerialPortStream.Length

get

This stream does not support the Length property.

Exceptions

NotSupportedException This stream doesn't support the Length property.

◆ NewLine

string RJCP.IO.Ports.SerialPortStream.NewLine

getset

Gets or sets the value used to interpret the end of a call to the ReadLine and WriteLine methods.

A value that represents the end of a line. The default is a line feed, (NewLine).

◆ Parity

Parity RJCP.IO.Ports.SerialPortStream.Parity

getset

Gets or sets the parity-checking protocol.

Parity is an error-checking procedure in which the number of 1s must always be the same — either even or odd — for each group of bits that is transmitted without error. In modem-to-modem communications, parity is often one of the parameters that must be agreed upon by sending parties and receiving parties before transmission can take place.

◆ ParityReplace

byte RJCP.IO.Ports.SerialPortStream.ParityReplace

getset

Gets or sets the byte that replaces invalid bytes in a data stream when a parity error occurs.

If the value is set to the null character, parity replacement is disabled. This property only has an effect if the Parity property is not Parity.None.

◆ PortName

string RJCP.IO.Ports.SerialPortStream.PortName

getset

Gets the port for communications, including but not limited to all available COM ports.

A list of valid port names can be obtained using the GetPortNames method.

When changing the port name, and the property UpdateOnPortSet is true, setting this property will cause the port to be opened, status read and the port then closed. Thus, you can use this behaviour to determine the actual settings of the port (which remain constant until a program actually changes the port settings).

Setting this property to itself, while having UpdateOnPortSet to true has the effect of updating the local properties based on the current port settings.

◆ Position

override long RJCP.IO.Ports.SerialPortStream.Position

getset

This stream does not support the Position property.

Exceptions

NotSupportedException This stream doesn't support the Position property.

◆ ReadBufferSize

int RJCP.IO.Ports.SerialPortStream.ReadBufferSize

getset

Gets or sets the size of the SerialPortStream input buffer.

Sets the amount of buffering to use when reading data from the serial port. Data is read locally into this buffered stream through another port.

The Microsoft implementation uses this to set the buffer size of the underlying driver. This implementation interprets the ReadBufferSize differently by setting the local buffer which can be much larger (megabytes) and independent of the low level driver.

Exceptions

InvalidOperationException An attempt was used to change the size of the buffer while the port is open (and therefore buffering is active).

◆ ReadTimeout

override int RJCP.IO.Ports.SerialPortStream.ReadTimeout

getset

Define the time out when reading data from the stream.

This defines the time out when data arrives in the buffered memory of this stream, that is, when the driver indicates that data has arrived to the application.

Should the user perform a read operation and no data is available to copy in the buffer, a time out will occur.

Set this property to InfiniteTimeout for an infinite time out.

◆ ReceivedBytesThreshold

int RJCP.IO.Ports.SerialPortStream.ReceivedBytesThreshold

getset

Gets or sets the number of bytes in the read buffer before a DataReceived event occurs.

◆ RingHolding

bool RJCP.IO.Ports.SerialPortStream.RingHolding

get

Gets the state of the Ring line signal.

The ring line is a separate line from a modem that indicates if there is an incoming call.

◆ RtsEnable

bool RJCP.IO.Ports.SerialPortStream.RtsEnable

getset

Gets or sets a value indicating whether the Request to Send (RTS) signal is enabled during serial communication.

The Request to Transmit (RTS) signal is typically used in Request to Send/Clear to Send (RTS/CTS) hardware handshaking.

Note, the windows feature RTS_CONTROL_TOGGLE is not supported by this class.

◆ StopBits

StopBits RJCP.IO.Ports.SerialPortStream.StopBits

getset

Gets or sets the standard number of stop bits per byte.

Gets or sets the stop bits that should be used when transmitting and receiving data over the serial port. If the serial driver doesn't support setting the stop bits, setting this property is silently ignored and the number of stop bits isn't updated.

◆ TxContinueOnXOff

bool RJCP.IO.Ports.SerialPortStream.TxContinueOnXOff

getset

Enable or Disable transmit of data when software flow control is enabled.

MSDN documentation states this flag as follows:

If this member is TRUE, transmission continues after the input buffer has come within XOffLimit bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.

When the driver buffer fills up and sends the XOFF character (and software flow control is active), this property defines if the driver should continue to send data over the serial port or not.

The Microsoft SerialPort implementation doesn't provide this option (in fact, in .NET 4.0 it doesn't appear to control this at all).

Some DCE devices will resume sending after any character arrives. The TxContinueOnXOff member should be set to FALSE when communicating with a DCE device that resumes sending after any character arrives.

◆ Version

string RJCP.IO.Ports.SerialPortStream.Version

get

Get the version of this assembly (or components driving this assembly).

The version of the assembly and/or subcomponents.

◆ WriteBufferSize

int RJCP.IO.Ports.SerialPortStream.WriteBufferSize

getset

Gets or sets the size of the serial port output buffer.

Defines the size of the buffered stream write buffer, used to send data to the serial port. It does not affect the buffers in the serial port hardware itself.

The Microsoft implementation uses this to set the buffer size of the underlying driver. This implementation interprets the WriteBufferSize differently by setting the local buffer which can be much larger (megabytes) and independent of the low level driver.

Exceptions

InvalidOperationException An attempt was used to change the size of the buffer while the port is open (and therefore buffering is active).

◆ WriteTimeout

override int RJCP.IO.Ports.SerialPortStream.WriteTimeout

getset

Define the time out when writing data to the local buffer.

This defines the time out when writing data to the local buffer. No guarantees are given to when the data will actually be transferred over to the serial port as this is dependent on the hardware configuration and flow control.

When writing data to the stream buffer, a time out will occur if not all data can be written to the local buffer and the buffer wasn't able to empty itself in the period given by the time out.

Naturally then, this depends on the size of the send buffer in use, how much data is already in the buffer, how fast the data can leave the buffer.

In case the data cannot be written to the buffer in the given time out, no data will be written at all.

◆ XOffLimit

int RJCP.IO.Ports.SerialPortStream.XOffLimit

getset

Define the limit of free bytes in the buffer before XOFF is sent.

The XOFF character (19 or ^S) is sent when the input buffer comes within XOffLimit bytes of being full, and the XON character (17 or ^Q) is sent when the input buffer comes within XOnLimit bytes of being empty.

◆ XOnLimit

int RJCP.IO.Ports.SerialPortStream.XOnLimit

getset

Define the limit of actual bytes in the transmit buffer when XON is sent.

The XOFF character (19 or ^S) is sent when the input buffer comes within XOffLimit bytes of being full, and the XON character (17 or ^Q) is sent when the input buffer comes within XOnLimit bytes of being empty.

Event Documentation

◆ DataReceived

EventHandler<SerialDataReceivedEventArgs> RJCP.IO.Ports.SerialPortStream.DataReceived

Occurs when data is received, or the EOF character is detected by the driver.

◆ ErrorReceived

EventHandler<SerialErrorReceivedEventArgs> RJCP.IO.Ports.SerialPortStream.ErrorReceived

Occurs when an error condition is detected.

◆ PinChanged

EventHandler<SerialPinChangedEventArgs> RJCP.IO.Ports.SerialPortStream.PinChanged

Occurs when modem pin changes are detected.

The documentation for this class was generated from the following file:

C:/PROJECTS/C#/BSL430.NET/src/BSL430.NET/Library/serialportstream/2.1.4/src/SerialPortStream.cs

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Properties

Events

Detailed Description

Constructor & Destructor Documentation

◆ SerialPortStream() [1/4]

◆ SerialPortStream() [2/4]

◆ SerialPortStream() [3/4]

◆ SerialPortStream() [4/4]

Member Function Documentation

◆ BeginRead()

◆ BeginWrite()

◆ Close()

◆ DiscardInBuffer()

◆ DiscardOutBuffer()

◆ Dispose()

◆ EndRead()

◆ EndWrite()

◆ Flush()

◆ GetPortDescriptions()

◆ GetPortNames()

◆ GetPortSettings()

◆ OnCommError()

◆ OnDataReceived()

◆ OnPinChanged()

◆ Open()

◆ OpenDirect()

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadByte()

◆ ReadChar()

◆ ReadExisting()

◆ ReadLine()

◆ ReadTo()

◆ Seek()

◆ SetLength()

◆ ToString()

◆ Write() [1/3]

◆ Write() [2/3]

◆ Write() [3/3]

◆ WriteLine()

Member Data Documentation

◆ InfiniteTimeout

Property Documentation

◆ BaudRate

◆ BreakState

◆ BytesToRead

◆ BytesToWrite

◆ CanRead

◆ CanSeek

◆ CanTimeout

◆ CanWrite

◆ CDHolding

◆ CtsHolding

◆ DataBits

◆ DiscardNull

◆ DriverInQueue

◆ DriverOutQueue

◆ DsrHolding

◆ DtrEnable

◆ Encoding

◆ Handshake

◆ IsDisposed

◆ IsOpen

◆ Length

◆ NewLine

◆ Parity

◆ ParityReplace

◆ PortName

◆ Position

◆ ReadBufferSize

◆ ReadTimeout

◆ ReceivedBytesThreshold

◆ RingHolding

◆ RtsEnable

◆ StopBits

◆ TxContinueOnXOff