# Class TBlockSerial

Description | Hierarchy | Fields | Methods | Properties

## Unit

synaser

## Declaration

`type TBlockSerial = class(TObject)`

## Description

Main class implementing all communication routines

## Hierarchy

- TObject
- TBlockSerial

## Overview

### Fields

| `DCB: Tdcb;`

### Methods

| `constructor Create;`
| `destructor Destroy; override;`
| `class function GetVersion: string; virtual;`
| `procedure CloseSocket; virtual;`
| `procedure Config(baud, bits: integer; parity: char; stop: integer; softflow, hardflow: boolean); virtual;`
| `procedure Connect(comport: string); virtual;`
| `procedure SetCommState; virtual;`
| `procedure GetCommState; virtual;`
| `function SendBuffer(buffer: pointer; length: integer): integer; virtual;`
| `procedure SendByte(data: byte); virtual;`
| `procedure SendString(data: AnsiString); virtual;`
| `procedure SendInteger(Data: integer); virtual;`
| `procedure SendBlock(const Data: AnsiString); virtual;`
| `procedure SendStreamRaw(const Stream: TStream); virtual;`
| `procedure SendStream(const Stream: TStream); virtual;`
| `procedure SendStreamIndy(const Stream: TStream); virtual;`
| `function RecvBuffer(buffer: pointer; length: integer): integer; virtual;`
| `function RecvBufferEx(buffer: pointer; length: integer; timeout: integer): integer; virtual;`
| `function RecvBufferStr(Length: Integer; Timeout: Integer): AnsiString; virtual;`
| `function RecvPacket(Timeout: Integer): AnsiString; virtual;`
| `function RecvByte(timeout: integer): byte; virtual;`
| `function RecvTerminated(Timeout: Integer; const Terminator: AnsiString): AnsiString; virtual;`
| `function Recvstring(timeout: integer): AnsiString; virtual;`
| `function RecvInteger(Timeout: Integer): Integer; virtual;`
| `function RecvBlock(Timeout: Integer): AnsiString; virtual;`
| `procedure RecvStreamRaw(const Stream: TStream; Timeout: Integer); virtual;`
| `procedure RecvStreamSize(const Stream: TStream; Timeout: Integer; Size: Integer); virtual;`
| `procedure RecvStream(const Stream: TStream; Timeout: Integer); virtual;`
| `procedure RecvStreamIndy(const Stream: TStream; Timeout: Integer); virtual;`
| `function WaitingData: integer; virtual;`
| `function WaitingDataEx: integer; virtual;`
| `function SendingData: integer; virtual;`
| `procedure EnableRTSToggle(value: boolean); virtual;`
| `procedure Flush; virtual;`
| `procedure Purge; virtual;`
| `function CanRead(Timeout: integer): boolean; virtual;`
| `function CanWrite(Timeout: integer): boolean; virtual;`
| `function CanReadEx(Timeout: integer): boolean; virtual;`
| `function ModemStatus: integer; virtual;`
| `procedure SetBreak(Duration: integer); virtual;`
| `function ATCommand(value: AnsiString): AnsiString; virtual;`
| `function ATConnect(value: AnsiString): AnsiString; virtual;`
| `function SerialCheck(SerialResult: integer): integer; virtual;`
| `procedure ExceptCheck; virtual;`
| `procedure SetSynaError(ErrNumber: integer); virtual;`
| `procedure RaiseSynaError(ErrNumber: integer); virtual;`
| `class function GetErrorDesc(ErrorCode: integer): string;`

### Properties

| `property Device: string read FDevice;`
| `property LastError: integer read FLastError;`
| `property LastErrorDesc: string read FLastErrorDesc;`
| `property ATResult: Boolean read FATResult;`
| `property RTS: Boolean write SetRTSF;`
| `property CTS: boolean read GetCTS;`
| `property DTR: Boolean write SetDTRF;`
| `property DSR: boolean read GetDSR;`
| `property Carrier: boolean read GetCarrier;`
| `property Ring: boolean read GetRing;`
| `property InstanceActive: boolean read FInstanceActive;`
| `property MaxSendBandwidth: Integer read FMaxSendBandwidth Write FMaxSendBandwidth;`
| `property MaxRecvBandwidth: Integer read FMaxRecvBandwidth Write FMaxRecvBandwidth;`
| `property MaxBandwidth: Integer Write SetBandwidth;`
| `property SizeRecvBuffer: integer read FRecvBuffer write SetSizeRecvBuffer;`
| `property Tag: integer read FTag write FTag;`
| `property Handle: THandle read Fhandle write FHandle;`
| `property LineBuffer: AnsiString read FBuffer write FBuffer;`
| `property RaiseExcept: boolean read FRaiseExcept write FRaiseExcept;`
| `property OnStatus: THookSerialStatus read FOnStatus write FOnStatus;`
| `property TestDSR: boolean read FTestDSR write FTestDSR;`
| `property TestCTS: boolean read FTestCTS write FTestCTS;`
| `property MaxLineLength: Integer read FMaxLineLength Write FMaxLineLength;`
| `property DeadlockTimeout: Integer read FDeadlockTimeout Write FDeadlockTimeout;`
| `property LinuxLock: Boolean read FLinuxLock write FLinuxLock;`
| `property ConvertLineEnd: Boolean read FConvertLineEnd Write FConvertLineEnd;`
| `property AtTimeout: integer read FAtTimeout Write FAtTimeout;`
| `property InterPacketTimeout: Boolean read FInterPacketTimeout Write FInterPacketTimeout;`

## Description

### Fields

| `DCB: Tdcb;`

data Control Block with communication parameters. Usable only when you need to call API directly.

### Methods

| `constructor Create;`

Object constructor.

| `destructor Destroy; override;`

Object destructor.

| `class function GetVersion: string; virtual;`

Returns a string containing the version number of the library.

| `procedure CloseSocket; virtual;`

Destroy handle in use. It close connection to serial port.

| `procedure Config(baud, bits: integer; parity: char; stop: integer; softflow, hardflow: boolean); virtual;`

Reconfigure communication parameters on the fly. You must be connected to port before!

###### parameters

baud
  Define connection speed. Baud rate can be from 50 to 4000000 bits per second. (it depends on your hardware!)
bits
  Number of bits in communication.
parity
  Define communication parity (N - None, O - Odd, E - Even, M - Mark or S - Space).
stop
  Define number of stopbits. Use constants SB1, SB1andHalf and SB2.
softflow
  Enable XON/XOFF handshake.
hardflow
  Enable CTS/RTS handshake.

| `procedure Connect(comport: string); virtual;`

Connects to the port indicated by comport. Comport can be used in Windows style (COM2), or in Linux style (/dev/ttyS1). When you use windows style in Linux, then it will be converted to Linux name. And vice versa! However you can specify any device name! (other device names then standart is not converted!)

After successfull connection the DTR signal is set (if you not set hardware handshake, then the RTS signal is set, too!)

Connection parameters is predefined by your system configuration. If you need use another parameters, then you can use Config method after. Notes:

- Remember, the commonly used serial Laplink cable does not support hardware handshake.

- Before setting any handshake you must be sure that it is supported by your hardware.

- Some serial devices are slow. In some cases you must wait up to a few seconds after connection for the device to respond.

- when you connect to a modem device, then is best to test it by an empty AT command. (call ATCommand('AT'))

| `procedure SetCommState; virtual;`

Set communication parameters from the DCB structure (the DCB structure is simulated under Linux).

| `procedure GetCommState; virtual;`

Read communication parameters into the DCB structure (DCB structure is simulated under Linux).

| `function SendBuffer(buffer: pointer; length: integer): integer; virtual;`

Sends Length bytes of data from Buffer through the connected port.

| `procedure SendByte(data: byte); virtual;`

One data BYTE is sent.

| `procedure SendString(data: AnsiString); virtual;`

Send the string in the data parameter. No terminator is appended by this method. If you need to send a string with CR/LF terminator, you must append the CR/LF characters to the data string!

Since no terminator is appended, you can use this function for sending binary data too.

| `procedure SendInteger(Data: integer); virtual;`

send four bytes as integer.

| `procedure SendBlock(const Data: AnsiString); virtual;`

send data as one block. Each block begins with integer value with Length of block.

| `procedure SendStreamRaw(const Stream: TStream); virtual;`

send content of stream from current position

| `procedure SendStream(const Stream: TStream); virtual;`

send content of stream as block. see SendBlock

| `procedure SendStreamIndy(const Stream: TStream); virtual;`

send content of stream as block, but this is compatioble with Indy library. (it have swapped lenght of block). See SendStream

| `function RecvBuffer(buffer: pointer; length: integer): integer; virtual;`

Waits until the allocated buffer is filled by received data. Returns number of data bytes received, which equals to the Length value under normal operation. If it is not equal, the communication channel is possibly broken.

This method not using any internal buffering, like all others receiving methods. You cannot freely combine this method with all others receiving methods!

| `function RecvBufferEx(buffer: pointer; length: integer; timeout: integer): integer; virtual;`

Method waits until data is received. If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout. This method is used to read any amount of data (e. g. 1MB), and may be freely combined with all receviving methods what have Timeout parameter, like the Recvstring, RecvByte or RecvTerminated methods.

| `function RecvBufferStr(Length: Integer; Timeout: Integer): AnsiString; virtual;`

It is like recvBufferEx, but data is readed to dynamicly allocated binary string.

| `function RecvPacket(Timeout: Integer): AnsiString; virtual;`

Read all available data and return it in the function result string. This function may be combined with Recvstring, RecvByte or related methods.

| `function RecvByte(timeout: integer): byte; virtual;`

Waits until one data byte is received which is returned as the function result. If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout.

| `function RecvTerminated(Timeout: Integer; const Terminator: AnsiString): AnsiString; virtual;`

This method waits until a terminated data string is received. This string is terminated by the Terminator string. The resulting string is returned without this termination string! If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout.

| `function Recvstring(timeout: integer): AnsiString; virtual;`

This method waits until a terminated data string is received. The string is terminated by a CR/LF sequence. The resulting string is returned without the terminator (CR/LF)! If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout.

If ConvertLineEnd is used, then the CR/LF sequence may not be exactly CR/LF. See the description of ConvertLineEnd.

This method serves for line protocol implementation and uses its own buffers to maximize performance. Therefore do NOT use this method with the RecvBuffer method to receive data as it may cause data loss.

| `function RecvInteger(Timeout: Integer): Integer; virtual;`

Waits until four data bytes are received which is returned as the function integer result. If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout.

| `function RecvBlock(Timeout: Integer): AnsiString; virtual;`

Waits until one data block is received. See SendBlock. If no data is received within the Timeout (in milliseconds) period, LastError is set to ErrTimeout.

| `procedure RecvStreamRaw(const Stream: TStream; Timeout: Integer); virtual;`

Receive all data to stream, until some error occured. (for example timeout)

| `procedure RecvStreamSize(const Stream: TStream; Timeout: Integer; Size: Integer); virtual;`

receive requested count of bytes to stream

| `procedure RecvStream(const Stream: TStream; Timeout: Integer); virtual;`

receive block of data to stream. (Data can be sended by SendStream

| `procedure RecvStreamIndy(const Stream: TStream; Timeout: Integer); virtual;`

receive block of data to stream. (Data can be sended by SendStreamIndy

| `function WaitingData: integer; virtual;`

Returns the number of received bytes waiting for reading. 0 is returned when there is no data waiting.

| `function WaitingDataEx: integer; virtual;`

Same as WaitingData, but in respect to data in the internal LineBuffer.

| `function SendingData: integer; virtual;`

Returns the number of bytes waiting to be sent in the output buffer. 0 is returned when the output buffer is empty.

| `procedure EnableRTSToggle(value: boolean); virtual;`

Enable or disable RTS driven communication (half-duplex). It can be used to communicate with RS485 converters, or other special equipment. If you enable this feature, the system automatically controls the RTS signal.

Notes:

- On Windows NT (or higher) ir RTS signal driven by system driver.

- On Win9x family is used special code for waiting until last byte is sended from your UART.

- On Linux you must have kernel 2.1 or higher!

| `procedure Flush; virtual;`

Waits until all data to is sent and buffers are emptied. Warning: On Windows systems is this method returns when all buffers are flushed to the serial port controller, before the last byte is sent!

| `procedure Purge; virtual;`

Unconditionally empty all buffers. It is good when you need to interrupt communication and for cleanups.

| `function CanRead(Timeout: integer): boolean; virtual;`

Returns `True`, if you can from read any data from the port. Status is tested for a period of time given by the Timeout parameter (in milliseconds). If the value of the Timeout parameter is 0, the status is tested only once and the function returns immediately. If the value of the Timeout parameter is set to -1, the function returns only after it detects data on the port (this may cause the process to hang).

| `function CanWrite(Timeout: integer): boolean; virtual;`

Returns `True`, if you can write any data to the port (this function is not sending the contents of the buffer). Status is tested for a period of time given by the Timeout parameter (in milliseconds). If the value of the Timeout parameter is 0, the status is tested only once and the function returns immediately. If the value of the Timeout parameter is set to -1, the function returns only after it detects that it can write data to the port (this may cause the process to hang).

| `function CanReadEx(Timeout: integer): boolean; virtual;`

Same as CanRead, but the test is against data in the internal LineBuffer too.

| `function ModemStatus: integer; virtual;`

Returns the status word of the modem. Decoding the status word could yield the status of carrier detect signaland other signals. This method is used internally by the modem status reading properties. You usually do not need to call this method directly.

| `procedure SetBreak(Duration: integer); virtual;`

Send a break signal to the communication device for Duration milliseconds.

| `function ATCommand(value: AnsiString): AnsiString; virtual;`

This function is designed to send AT commands to the modem. The AT command is sent in the Value parameter and the response is returned in the function return value (may contain multiple lines!). If the AT command is processed successfully (modem returns OK), then the ATResult property is set to True.

This function is designed only for AT commands that return OK or ERROR response! To call connection commands the ATConnect method. Remember, when you connect to a modem device, it is in AT command mode. Now you can send AT commands to the modem. If you need to transfer data to the modem on the other side of the line, you must first switch to data mode using the ATConnect method.

| `function ATConnect(value: AnsiString): AnsiString; virtual;`

This function is used to send connect type AT commands to the modem. It is for commands to switch to connected state. (ATD, ATA, ATO,...) It sends the AT command in the Value parameter and returns the modem's response (may be multiple lines - usually with connection parameters info). If the AT command is processed successfully (the modem returns CONNECT), then the ATResult property is set to `True`.

This function is designed only for AT commands which respond by CONNECT, BUSY, NO DIALTONE NO CARRIER or ERROR. For other AT commands use the ATCommand method.

The connect timeout is 90*AtTimeout. If this command is successful (ATResult is `True`), then the modem is in data state. When you now send or receive some data, it is not to or from your modem, but from the modem on other side of the line. Now you can transfer your data. If the connection attempt failed (ATResult is `False`), then the modem is still in AT command mode.

| `function SerialCheck(SerialResult: integer): integer; virtual;`

If you "manually" call API functions, forward their return code in the SerialResult parameter to this function, which evaluates it and sets LastError and LastErrorDesc.

| `procedure ExceptCheck; virtual;`

If LastError is not 0 and exceptions are enabled, then this procedure raises an exception. This method is used internally. You may need it only in special cases.

| `procedure SetSynaError(ErrNumber: integer); virtual;`

Set Synaser to error state with ErrNumber code. Usually used by internal routines.

| `procedure RaiseSynaError(ErrNumber: integer); virtual;`

Raise Synaser error with ErrNumber code. Usually used by internal routines.

| `class function GetErrorDesc(ErrorCode: integer): string;`

Returns the descriptive text associated with ErrorCode. You need this method only in special cases. Description of LastError is now accessible through the LastErrorDesc property.

### Properties

| `property Device: string read FDevice;`

True device name of currently used port

| `property LastError: integer read FLastError;`

Error code of last operation. Value is defined by the host operating system, but value 0 is always OK.

| `property LastErrorDesc: string read FLastErrorDesc;`

Human readable description of LastError code.

| `property ATResult: Boolean read FATResult;`

Indicates if the last ATCommand or ATConnect method was successful

| `property RTS: Boolean write SetRTSF;`

Read the value of the RTS signal.

| `property CTS: boolean read GetCTS;`

Indicates the presence of the CTS signal

| `property DTR: Boolean write SetDTRF;`

Use this property to set the value of the DTR signal.

| `property DSR: boolean read GetDSR;`

Exposes the status of the DSR signal.

| `property Carrier: boolean read GetCarrier;`

Indicates the presence of the Carrier signal

| `property Ring: boolean read GetRing;`

Reflects the status of the Ring signal.

| `property InstanceActive: boolean read FInstanceActive;`

indicates if this instance of SynaSer is active. (Connected to some port)

| `property MaxSendBandwidth: Integer read FMaxSendBandwidth Write FMaxSendBandwidth;`

Defines maximum bandwidth for all sending operations in bytes per second. If this value is set to 0 (default), bandwidth limitation is not used.

| `property MaxRecvBandwidth: Integer read FMaxRecvBandwidth Write FMaxRecvBandwidth;`

Defines maximum bandwidth for all receiving operations in bytes per second. If this value is set to 0 (default), bandwidth limitation is not used.

| `property MaxBandwidth: Integer Write SetBandwidth;`

Defines maximum bandwidth for all sending and receiving operations in bytes per second. If this value is set to 0 (default), bandwidth limitation is not used.

| `property SizeRecvBuffer: integer read FRecvBuffer write SetSizeRecvBuffer;`

Size of the Windows internal receive buffer. Default value is usually 4096 bytes. Note: Valid only in Windows versions!

| `property Tag: integer read FTag write FTag;`

Freely usable property

| `property Handle: THandle read Fhandle write FHandle;`

Contains the handle of the open communication port. You may need this value to directly call communication functions outside SynaSer.

| `property LineBuffer: AnsiString read FBuffer write FBuffer;`

Internally used read buffer.

| `property RaiseExcept: boolean read FRaiseExcept write FRaiseExcept;`

If `True`, communication errors raise exceptions. If `False` (default), only the LastError value is set.

| `property OnStatus: THookSerialStatus read FOnStatus write FOnStatus;`

This event is triggered when the communication status changes. It can be used to monitor communication status.

| `property TestDSR: boolean read FTestDSR write FTestDSR;`

If you set this property to `True`, then the value of the DSR signal is tested before every data transfer. It can be used to detect the presence of a communications device.

| `property TestCTS: boolean read FTestCTS write FTestCTS;`

If you set this property to `True`, then the value of the CTS signal is tested before every data transfer. It can be used to detect the presence of a communications device. Warning: This property cannot be used if you need hardware handshake!

| `property MaxLineLength: Integer read FMaxLineLength Write FMaxLineLength;`

Use this property you to limit the maximum size of LineBuffer (as a protection against unlimited memory allocation for LineBuffer). Default value is 0 - no limit.

| `property DeadlockTimeout: Integer read FDeadlockTimeout Write FDeadlockTimeout;`

This timeout value is used as deadlock protection when trying to send data to (or receive data from) a device that stopped communicating during data transmission (e.g. by physically disconnecting the device). The timeout value is in milliseconds. The default value is 30,000 (30 seconds).

| `property LinuxLock: Boolean read FLinuxLock write FLinuxLock;`

If set to `True` (default value), port locking is enabled (under Linux only). WARNING: To use this feature, the application must run by a user with full permission to the /var/lock directory!

| `property ConvertLineEnd: Boolean read FConvertLineEnd Write FConvertLineEnd;`

Indicates if non-standard line terminators should be converted to a CR/LF pair (standard DOS line terminator). If `True`, line terminators CR, single LF or LF/CR are converted to CR/LF. Defaults to `False`. This property has effect only on the behavior of the RecvString method.

| `property AtTimeout: integer read FAtTimeout Write FAtTimeout;`

Timeout for AT modem based operations

| `property InterPacketTimeout: Boolean read FInterPacketTimeout Write FInterPacketTimeout;`

If `True` (default), then all timeouts is timeout between two characters. If `False`, then timeout is overall for whoole reading operation.

Generated by PasDoc 0.9.0 on 2012-04-23 21:38:52