BSL430.NET 1.2.1

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Properties | Events | List of all members
RJCP.IO.Ports.SerialPortStream Class Reference

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
| ) |  |
| protected virtual

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
| ) |  |
| protected virtual

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
| ) |  |
| protected virtual

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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
| get set

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