# Class TBlockSerial

Description | Hierarchy | Fields | Methods | Properties

## Unit

synaser

## Declaration

`type TBlockSerial = class(TObject)`

## Description

Main class implementing all communication routines

## Hierarchy

TBlockSerial > TObject

## Fields

| Name | Description
--- | --- | ---
| `DCB` | data Control Block with communication parameters. Usable only when you need to call API directly.

## Methods

### Overview

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

### Description

| `function ATCommand(value: string): string; 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: string): string; 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 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 CanReadEx(Timeout: integer): boolean; virtual;`

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

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

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

| `constructor Create;`

Object constructor.

| `destructor Destroy; override;`

Object destructor.

| `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 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 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 GetCommState; virtual;`

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

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

| `class function GetVersion: string; virtual;`

Returns a string containing the version number of the library.

| `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 Purge; virtual;`

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

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

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

| `function RecvBlock(Timeout: Integer): string; 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.

| `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): string; virtual;`

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

| `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 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 RecvPacket(Timeout: Integer): string; virtual;`

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

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

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

| `function Recvstring(timeout: integer): string; 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 RecvTerminated(Timeout: Integer; const Terminator: string): string; 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.

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

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

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

| `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 SendInteger(Data: integer); virtual;`

send four bytes as integer.

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

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

send content of stream from current position

| `procedure SendString(data: string); 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.

| `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 SetBreak(Duration: integer); virtual;`

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

| `procedure SetCommState; virtual;`

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

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

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

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

## Properties

### Overview

| `property ATResult: Boolean;`
| `property AtTimeout: integer;`
| `property Carrier: boolean;`
| `property ConvertLineEnd: Boolean;`
| `property CTS: boolean;`
| `property DeadlockTimeout: Integer;`
| `property Device: string;`
| `property DSR: boolean;`
| `property DTR: Boolean;`
| `property Handle: THandle;`
| `property InstanceActive: boolean;`
| `property InterPacketTimeout: Boolean;`
| `property LastError: integer;`
| `property LastErrorDesc: string;`
| `property LineBuffer: string;`
| `property LinuxLock: Boolean;`
| `property MaxBandwidth: Integer;`
| `property MaxLineLength: Integer;`
| `property MaxRecvBandwidth: Integer;`
| `property MaxSendBandwidth: Integer;`
| `property OnStatus: THookSerialStatus;`
| `property RaiseExcept: boolean;`
| `property Ring: boolean;`
| `property RTS: Boolean;`
| `property SizeRecvBuffer: integer;`
| `property Tag: integer;`
| `property TestCTS: boolean;`
| `property TestDSR: boolean;`

### Description

| `property ATResult: Boolean;`

Indicates if the last ATCommand or ATConnect method was successful

| `property AtTimeout: integer;`

Timeout for AT modem based operations

| `property Carrier: boolean;`

Indicates the presence of the Carrier signal

| `property ConvertLineEnd: Boolean;`

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 CTS: boolean;`

Indicates the presence of the CTS signal

| `property DeadlockTimeout: Integer;`

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 Device: string;`

True device name of currently used port

| `property DSR: boolean;`

Exposes the status of the DSR signal.

| `property DTR: Boolean;`

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

| `property Handle: THandle;`

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

| `property InstanceActive: boolean;`

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

| `property InterPacketTimeout: Boolean;`

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

| `property LastError: integer;`

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

| `property LastErrorDesc: string;`

Human readable description of LastError code.

| `property LineBuffer: string;`

Internally used read buffer.

| `property LinuxLock: Boolean;`

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 MaxBandwidth: Integer;`

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 MaxLineLength: Integer;`

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 MaxRecvBandwidth: Integer;`

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 MaxSendBandwidth: Integer;`

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 OnStatus: THookSerialStatus;`

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

| `property RaiseExcept: boolean;`

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

| `property Ring: boolean;`

Reflects the status of the Ring signal.

| `property RTS: Boolean;`

Read the value of the RTS signal.

| `property SizeRecvBuffer: integer;`

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

| `property Tag: integer;`

Freely usable property

| `property TestCTS: boolean;`

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 TestDSR: boolean;`

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.

Generated by PasDoc 0.8.8.2 on 2005-01-19 20:01:20