FieldTalk^™ Modbus^® Slave Library
C++ Editions

MbusTcpSlaveProtocol Class Reference
[MODBUS/TCP Protocol]

Inheritance diagram for MbusTcpSlaveProtocol:

Collaboration diagram for MbusTcpSlaveProtocol:

List of all members.

Detailed Description

MODBUS/TCP Slave Protocol class.

This class realises the MODBUS/TCP slave protocol. It provides functions to start-up and to execute the server engine. This server engine can handle multiple master connections and is implemented as a single threaded TCP server. Upon receipt of a valid master query the server engine calls Data Provider methods to exchange data with the user application. For a more detailed description which Modbus data and control functions have been implemented in the server engine see section Server Functions common to all Protocol Flavours.

See also:: Server Functions common to all Protocol Flavours, MbusSlaveServer


MODBUS/TCP Server Management Functions
	MbusTcpSlaveProtocol ()
	Constructs a MbusTcpSlaveProtocol object.
	MbusTcpSlaveProtocol (MbusDataTableInterface *dataTablePtr)
	Constructs a MbusTcpSlaveProtocol object data and associates it with a Data Provider.
int	startupServer ()
	Puts the Modbus server into operation.
int	startupServer (const char *const hostName)
	Puts the Modbus server into operation.
int	startupServer (int slaveAddr)
	Puts the Modbus server into operation using a single slave address and data table.
int	startupServer (int slaveAddr, const char *const hostName)
	Puts the Modbus server into operation using a single slave address and data table.
void	shutdownServer ()
	Shuts down the Modbus server.
int	serverLoop ()
	MODBUS/TCP slave server loop.
int	isStarted ()
	Returns if server has been started up.
int	getConnectionStatus ()
	Checks if a Modbus master is polling periodically.
int	setPort (unsigned short portNo)
	Sets the TCP port number to be used by the protocol.
void	installIpAddrValidationCallBack (int(f)(char masterIpAddrSz))
	This function installs a callback handler for validating a master's IP address.
unsigned short	getPort ()
	Returns the TCP port number used by the protocol.
Server Management Functions
int	addDataTable (int slaveAddr, MbusDataTableInterface *dataTablePtr)
	Associates a protocol object with a Data Provider and a slave address.
Protocol Configuration
long	setTimeout (long timeOut)
	Configures master transmit time-out supervision.
long	getTimeout ()
	Returns the master time-out supervision value.
Transmission Statistic Functions
unsigned long	getTotalCounter ()
	Returns how often a message transfer has been executed.
void	resetTotalCounter ()
	Resets total message transfer counter.
unsigned long	getSuccessCounter ()
	Returns how often a message transfer was successful.
void	resetSuccessCounter ()
	Resets successful message transfer counter.
Utility Functions
static char *	getPackageVersion ()
	Returns the package version number.

Constructor & Destructor Documentation

MbusTcpSlaveProtocol

(

)

Constructs a MbusTcpSlaveProtocol object.

The association with a Data Provider is done after construction using the addDataTable method.

MbusTcpSlaveProtocol

(

MbusDataTableInterface *

dataTablePtr

)

Constructs a MbusTcpSlaveProtocol object data and associates it with a Data Provider.

Function is kept for compatibility with previous API versions, do not use for new implementations.

Parameters:

dataTablePtr

Modbus data table pointer. Must point to a Data Provider object derived from the MbusDataTableInterface class. The Data Provider is the interface between your application data and the Modbus network.

Deprecated:: This function is deprecated. The preferred way of assigning a dataTable is using the default constructor and configuring data table and slave address using addDataTable method.

Member Function Documentation

int startupServer

(

)

Puts the Modbus server into operation.

The server accepts connections on any interface.

This function opens a TCP/IP socket, binds the configured TCP port to the Modbus/TCP protocol and initialises the server engine.

Note:: If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

int startupServer

(

const char *const

hostName

)

Puts the Modbus server into operation.

The server accepts connections only on the interfaces which match the supplied hostname or IP address. This method allows to run different servers on multiple interfaces (so called multihomed servers).

This function opens a TCP/IP socket, binds the configured TCP port to the Modbus/TCP protocol and initialises the server engine.

Note:: If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Parameters:

hostName

String with IP address for a specific host interface or NULL if connections are accepted on any interface

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

int startupServer

(

int

slaveAddr

)

Puts the Modbus server into operation using a single slave address and data table.

The server accepts connections on any interface.

Function is kept for compatibility with previous API versions, do not use for new implementations.

Note:: If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Parameters:

slaveAddr

Modbus slave address for server to listen on (-1 - 255). 0 is regarded as a valid value for a MODBUS/TCP server address. A value of -1 means the server disregards the slave address and listens to all slave addresses.

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

Deprecated:: This function is deprecated. The preferred way of assigning a slave address is using the default constructor and configuring data table and slave address using addDataTable method.

int startupServer	(	int	slaveAddr,
		const char *const	hostName
	)

Puts the Modbus server into operation using a single slave address and data table.

Function is kept for compatibility with previous API versions, do not use for new implementations.

Parameters:

	slaveAddr	Modbus slave address for server to listen on (-1 - 255). 0 is regarded as a valid value for a MODBUS/TCP server address. A value of -1 means the server disregards the slave address and listens to all slave addresses.
	hostName	String with IP address for a specific host interface or NULL if connections are accepted on any interface

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

Deprecated:: This function is deprecated. The preferred way of assigning a slave address is using the default constructor and configuring data table and slave address using addDataTable method.

void shutdownServer ( ) [virtual]

Shuts down the Modbus server.

This function closes all TCP/IP connections to MODBUS/TCP masters and releases any system resources associated with the connections.

Reimplemented from MbusSlaveServer.

int serverLoop ( ) [virtual]

MODBUS/TCP slave server loop.

This server loop must be called continuously. It must not be blocked. The server has to be started before calling the serverLoop() method. This server engine can handle multiple TCP/IP connections at the same time.

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

Implements MbusSlaveServer.

int isStarted ( ) [virtual]

Returns if server has been started up.

Return values:

	true	= started
	false	= shutdown

Implements MbusSlaveServer.

int getConnectionStatus ( ) [virtual]

Checks if a Modbus master is polling periodically.

Return values:

	true	= A master is polling at a frequency higher than the master transmit time-out value
	false	= No master is polling within the time-out period

Note:: The master transmit time-out value must be set > 0 in order for this function to work.

Implements MbusSlaveServer.

int setPort

(

unsigned short

portNo

)

Sets the TCP port number to be used by the protocol.

Remarks:: Usually the port number remains unchanged and defaults to 502. In this case no call to this function is necessary. However if the port number has to be different from 502 this function must be called before starting the server with startupServer().

Note:: If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Parameters:

portNo

Port number the server shall listen on

Return values:

	FTALK_SUCCESS	Success
	FTALK_ILLEGAL_STATE_ERROR	Server already running

void installIpAddrValidationCallBack

(

int(*)(char *masterIpAddrSz)

)

This function installs a callback handler for validating a master's IP address.

Pass a pointer to a function with checks a master's IP address and either accepts or rejects a master's connection.

Parameters:

masterIpAddrSz

IPv4 Internet host address string in the standard numbers-and-dots notation.

Returns:: Returns 1 to accept a connection or 0 to reject it.

unsigned short getPort

(

)

Returns the TCP port number used by the protocol.

Returns:: Port number used by the protocol

MbusTcpSlaveProtocol Class Reference [MODBUS/TCP Protocol]

Detailed Description

MODBUS/TCP Server Management Functions

Server Management Functions

Protocol Configuration

Transmission Statistic Functions

Utility Functions

Constructor & Destructor Documentation

Member Function Documentation

MbusTcpSlaveProtocol Class Reference
[MODBUS/TCP Protocol]