MbusTcpSlaveProtocol Class Reference
[MODBUS/TCP Protocol]

Inheritance diagram for MbusTcpSlaveProtocol:

Collaboration diagram for MbusTcpSlaveProtocol:

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.

Version:: 1.0

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 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 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) f )

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]