Class TBlockSerial

DescriptionHierarchyFieldsMethodsProperties

Unit

synaser

Declaration

type TBlockSerial = class(TObject)

Description

Main class implementing all communication routines

Hierarchy

Overview

Fields

Public DCB: Tdcb;

Methods

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

Properties

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

Description

Fields

Public DCB: Tdcb;

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

Methods

Public constructor Create;

Object constructor.

Public destructor Destroy; override;

Object destructor.

Public class function GetVersion: string; virtual;

Returns a string containing the version number of the library.

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 procedure SetCommState; virtual;

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

Public procedure GetCommState; virtual;

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

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

Public procedure SendInteger(Data: integer); virtual;

send four bytes as integer.

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

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

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

send content of stream from current position

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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 SetSynaError(ErrNumber: integer); virtual;

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

Public procedure RaiseSynaError(ErrNumber: integer); virtual;

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

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.

Properties

Public property Device: string read FDevice;

True device name of currently used port

Public property LastError: integer read FLastError;

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

Public property LastErrorDesc: string read FLastErrorDesc;

Human readable description of LastError code.

Public property ATResult: Boolean read FATResult;

Indicates if the last ATCommand or ATConnect method was successful

Public property RTS: Boolean write SetRTSF;

Read the value of the RTS signal.

Public property CTS: boolean read GetCTS;

Indicates the presence of the CTS signal

Public property DTR: Boolean write SetDTRF;

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

Public property DSR: boolean read GetDSR;

Exposes the status of the DSR signal.

Public property Carrier: boolean read GetCarrier;

Indicates the presence of the Carrier signal

Public property Ring: boolean read GetRing;

Reflects the status of the Ring signal.

Public property InstanceActive: boolean read FInstanceActive;

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

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

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

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

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

Published property Tag: integer read FTag write FTag;

Freely usable property

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

Published property LineBuffer: AnsiString read FBuffer write FBuffer;

Internally used read buffer.

Published property RaiseExcept: boolean read FRaiseExcept write FRaiseExcept;

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

Published property OnStatus: THookSerialStatus read FOnStatus write FOnStatus;

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

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

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

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

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

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

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

Published property AtTimeout: integer read FAtTimeout Write FAtTimeout;

Timeout for AT modem based operations

Published 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:59