Class TBlockSerial

DescriptionHierarchyFieldsMethodsProperties

Unit

synaser

Declaration

type TBlockSerial = class(TObject)

Description

Main class implementing all communication routines

Hierarchy

TBlockSerial > TObject

Fields

 NameDescription
Public DCB

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

Methods

Overview

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

Description

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

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

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

Public function CanReadEx(Timeout: integer): boolean; virtual;

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

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

Public procedure CloseSocket; virtual;

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

Public 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.
Public 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'))

Public constructor Create;

Object constructor.

Public destructor Destroy; override;

Object destructor.

Public 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!

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

Public 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!

Public procedure GetCommState; virtual;

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

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

Public class function GetVersion: string; virtual;

Returns a string containing the version number of the library.

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

Public procedure Purge; virtual;

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

Public procedure RaiseSynaError(ErrNumber: integer); virtual;

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

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

Public 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!

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

Public function RecvBufferStr(Length: Integer; Timeout: Integer): string; virtual;

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

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

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

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

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

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

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

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

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

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

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

receive requested count of bytes to stream

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

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

Public procedure SendBlock(const Data: string); virtual;

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

Public function SendBuffer(buffer: pointer; length: integer): integer; virtual;

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

Public procedure SendByte(data: byte); virtual;

One data BYTE is sent.

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

Public procedure SendInteger(Data: integer); virtual;

send four bytes as integer.

Public procedure SendStream(const Stream: TStream); virtual;

send content of stream as block. see SendBlock

Public 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

Public procedure SendStreamRaw(const Stream: TStream); virtual;

send content of stream from current position

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

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

Public procedure SetBreak(Duration: integer); virtual;

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

Public procedure SetCommState; virtual;

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

Public procedure SetSynaError(ErrNumber: integer); virtual;

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

Public function WaitingData: integer; virtual;

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

Public function WaitingDataEx: integer; virtual;

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

Properties

Overview

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

Description

Public property ATResult: Boolean;

Indicates if the last ATCommand or ATConnect method was successful

Published property AtTimeout: integer;

Timeout for AT modem based operations

Public property Carrier: boolean;

Indicates the presence of the Carrier signal

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

Public property CTS: boolean;

Indicates the presence of the CTS signal

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

Public property Device: string;

True device name of currently used port

Public property DSR: boolean;

Exposes the status of the DSR signal.

Public property DTR: Boolean;

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

Published property Handle: THandle;

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

Public property InstanceActive: boolean;

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

Published property InterPacketTimeout: Boolean;

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

Public property LastError: integer;

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

Public property LastErrorDesc: string;

Human readable description of LastError code.

Published property LineBuffer: string;

Internally used read buffer.

Published 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!

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

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

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

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

Published property OnStatus: THookSerialStatus;

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

Published property RaiseExcept: boolean;

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

Public property Ring: boolean;

Reflects the status of the Ring signal.

Public property RTS: Boolean;

Read the value of the RTS signal.

Public property SizeRecvBuffer: integer;

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

Published property Tag: integer;

Freely usable property

Published 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!

Published 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