MODBUS Porting Layer (TCP)
[MODBUS Porting Layer]


Typedefs

typedef eMBErrorCode(* peMBPTCPClientConnectedCB )(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX
typedef eMBErrorCode(* peMBPTCPClientNewDataCB )(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX
typedef eMBErrorCode(* peMBPTCPClientDisconnectedCB )(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX

Functions

eMBErrorCode eMBPTCPClientInit (xMBPTCPHandle *pxTCPHdl, xMBHandle xMBHdl, peMBPTCPClientNewDataCB eMBPTCPClientNewDATAFN, peMBPTCPClientDisconnectedCB eMBPTCPClientDisconnectedFN)
eMBErrorCode eMBPTCPClientClose (xMBPTCPHandle xTCPHdl)
eMBErrorCode eMBPTCPClientOpen (xMBPTCPHandle xTCPHdl, xMBPTCPClientHandle *pxTCPClientHdl, const CHAR *pcConnectAddress, USHORT usTCPPort)
eMBErrorCode eMBPTCPServerInit (xMBPTCPHandle *pxTCPHdl, CHAR *pcBindAddress, USHORT usTCPPort, xMBHandle xMBHdl, peMBPTCPClientNewDataCB eMBPTCPClientNewDataFN, peMBPTCPClientDisconnectedCB eMBPTCPClientDisconnectedFN, peMBPTCPClientConnectedCB eMBPTCPClientConnectedFN)
eMBErrorCode eMBTCPServerClose (xMBPTCPHandle xTCPHdl)
eMBErrorCode eMBPTCPConRead (xMBPTCPHandle xTCPHdl, xMBPTCPClientHandle xTCPClientHdl, UBYTE *pubBuffer, USHORT *pusBufferLen, USHORT usBufferMax)
eMBErrorCode eMBPTCPConWrite (xMBPTCPHandle xTCPHdl, xMBPTCPClientHandle xTCPClientHdl, const UBYTE *pubBuffer, USHORT usBufferLen)
eMBErrorCode eMBPTCPConClose (xMBPTCPHandle xTCPHdl, xMBPTCPClientHandle xTCPClientHdl)

Typedef Documentation

typedef eMBErrorCode( * peMBPTCPClientConnectedCB)(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX
 

This function is called by the TCP porting layer when a new client connection is made.

The stack will check if it can still handle more clients. This value is configured by the compile time configuration directive MBS_TCP_MAX_CLIENTS.

Parameters:
xMBHdl A handle to a MODBUS stack.
xTCPClientHdl New client handle.
Returns:
eMBErrorCode::MB_ENOERR if the stack has accepted this client. If no more clients can be handled the function returns eMBErrorCode::MB_ENORES. In this case the porting layer should drop the client connection. In case of an invalid handle this function returns eMBErrorCode::MB_EINVAL.

typedef eMBErrorCode( * peMBPTCPClientDisconnectedCB)(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX
 

Called by the porting layer when a client has disconnected.

Returns:
eMBErrorCode::MB_ENOERR if the stack was notified correctly that the client has been disconnected. eMBErrorCode::MB_EINVAL if the MODBUS handle or the client index was invalid.

typedef eMBErrorCode( * peMBPTCPClientNewDataCB)(xMBHandle xMBHdl, xMBPTCPClientHandle xTCPClientHdl) MB_CDECL_SUFFIX
 

Called by the TCP porting layer when new data is available for a TCP client.

This function shall be called by the porting layer when new data is available. It is important that the actual state, i.e. the availability of data is used for calling this function and not the event of receiving some data on a connection. On BSD socket like implementations using select with FD_READ is a proper way to do it. In case the TCP/IP stack uses event based semantics the data should be buffered by the porting layer and the function should be called.

Note:
Please note that it is not guranteed that the stack is actually going to read the data when this function is called. For example this could happen if it is internally in a state for sending a response to another client. The porting layer should simply continuing calling this function with a small delay.
Parameters:
xMBHdl A handle to a MODBUS stack.
xTCPClientHdl A handle for a TCP client.
Returns:
eMBErrorCode::MB_ENOERR if the data was handled. eMBErrorCode::MB_EINVAL if the MODBUS handle or the client index was invalid.

Function Documentation

eMBErrorCode eMBPTCPClientClose (  xMBPTCPHandle  xTCPHdl  ) 
 

Shutdown a TCP instance for handling client connections.

Parameters:
xTCPHdl A TCP handle for a client instance.
Returns:
MBErrorCode::MB_ENOERR if the client instances has been closed.

eMBErrorCode eMBPTCPClientInit (  xMBPTCPHandle *  pxTCPHdl,
xMBHandle  xMBHdl,
peMBPTCPClientNewDataCB  eMBPTCPClientNewDATAFN,
peMBPTCPClientDisconnectedCB  eMBPTCPClientDisconnectedFN
) 
 

Create a new TCP instance for handling client connections.

Parameters:
pxTCPHdl A TCP handle for the client instance.
xMBHdl A handle for the MODBUS stack.
eMBPTCPClientNewDATAFN Callback function if new client data is available.
eMBPTCPClientDisconnectedFN Callback function if a client connection is broken.
Returns:
eMBErrorCode::MB_ENOERR if a new instance has been crated. In case of invalid arguments it should return eMBErrorCode::MB_EINVAL. Otherweise eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTCPClientOpen (  xMBPTCPHandle  xTCPHdl,
xMBPTCPClientHandle *  pxTCPClientHdl,
const CHAR *  pcConnectAddress,
USHORT  usTCPPort
) 
 

Open a new client connection.

The client connection can be used to read and write data. If the stack wants to transmit data it calls the function eMBPTCPWrite. If new data is available the porting layer executes the callback function eMBPTCPClientNewDataCB. The stack can then read the data by a call to the function eMBPTCPRead.

Parameters:
xTCPHdl A handle to the TCP client instance.
pxTCPClientHdl If the function returns eMBErrorCode::MB_ENOERR this pointer holds a valid client handle.
pcConnectAddress The IP address to connect to.
usTCPPort The TCP port to use.
Returns:
eMBErrorCode::MB_ENOERR if the connection has been opened and is ready for use. In case of a connection error eMBErrorCode::MB_EIO. All other errors are mapped to eMBErrorCode::MB_EPORTERR indicating that the WHOLE TCP client instance is faulty.

eMBErrorCode eMBPTCPConClose (  xMBPTCPHandle  xTCPHdl,
xMBPTCPClientHandle  xTCPClientHdl
) 
 

Close a TCP client connection.

Called by the stack when a TCP client connection should be closed.

Parameters:
xTCPHdl A handle to a TCP server instance.
xTCPClientHdl A handle for a TCP client which should be closed.
Returns:
The function should return eMBErrorCode::MB_ENOERR if the client connection has been closed. If any of the handles are invalid it should return eMBErrorCode::MB_EINVAL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTCPConRead (  xMBPTCPHandle  xTCPHdl,
xMBPTCPClientHandle  xTCPClientHdl,
UBYTE *  pubBuffer,
USHORT *  pusBufferLen,
USHORT  usBufferMax
) 
 

This function is called by the MODBUS stack when new data should be read from a client.

This function must not block and should read up to usBufferMax bytes and store them into the buffer pubBuffer. The value of pusBufferLen should be set to the number of bytes read where 0 is used when there is no data available.

Parameters:
xTCPHdl A handle to a TCP server instance.
xTCPClientHdl A handle for a TCP client.
pubBuffer A buffer of at least usBufferMax bytes where the read bytes from the client should be stored.
pusBufferLen On return the value should hold the number of bytes written into the buffer.
usBufferMax Maximum number of bytes which can be stored in the buffer.
Returns:
The function should return eMBErrorCode::MB_ENOERR if zero or more bytes have been stored in the buffer and no error occurred. In case of a client error it should return eMBErrorCode::MB_EIO. In case of an invalid handle is should return eMBErrorCode::MB_EINVAL. Other errors should be mapped to eMBErrorCode::MB_EPORTERR signaling the stack that the porting layer is no longer functional.

eMBErrorCode eMBPTCPConWrite (  xMBPTCPHandle  xTCPHdl,
xMBPTCPClientHandle  xTCPClientHdl,
const UBYTE *  pubBuffer,
USHORT  usBufferLen
) 
 

This function is called by the MODBUS stack when new data should be sent over a client connection.

This function should not block and should transmit usBufferLen bytes over the client connection.

Parameters:
xTCPHdl A handle to a TCP server instance.
xTCPClientHdl A handle for a TCP client.
pubBuffer A buffer of usBufferLen bytes which should be transmitted.
usBufferLen Number of bytes to transmit.
Returns:
The function should return eMBErrorCode::MB_ENOERR if all bytes have been written. In case of an I/O error it should return eMBErrorCode::MB_EIO. In case of an invalid handle or invalid arguments it should return eMBErrorCode::MB_EINVAL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTCPServerInit (  xMBPTCPHandle *  pxTCPHdl,
CHAR *  pcBindAddress,
USHORT  usTCPPort,
xMBHandle  xMBHdl,
peMBPTCPClientNewDataCB  eMBPTCPClientNewDataFN,
peMBPTCPClientDisconnectedCB  eMBPTCPClientDisconnectedFN,
peMBPTCPClientConnectedCB  eMBPTCPClientConnectedFN
) 
 

Create a new listening server on address usTCPPort which accepts connection for the addresses specificed in pcBindAddress.

The exact meaning of pcBindAddress is application and platform dependent and therefore not further specified.

Parameters:
pxTCPHdl If a new listening server has been created this handle should point to the server.
pcBindAddress The address to bind to. The exact meaning is port dependent.
usTCPPort The TCP port.
xMBHdl A handle which is used for the callback functions to identify the stack.
eMBPTCPClientNewDataFN Callback function if new client data is available.
eMBPTCPClientDisconnectedFN Callback function if a client connection is broken.
eMBPTCPClientConnectedFN Callback function if a client connects to the server.
Returns:
eMBErrorCode::MB_ENOERR if a new server was created. In case of invalid arguments it should return eMBErrorCode::MB_EINVAL. Otherwise eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBTCPServerClose (  xMBPTCPHandle  xTCPHdl  ) 
 

Closes a server instance.

Parameters:
xTCPHdl A handle for a TCP server.
Returns:
eMBErrorCode::MB_ENOERR if the server has shut down (and closed all client connections). eMBErrorCode::MB_EINVAL if the handle was not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

(C) 2007 Embedded Solutions. Last updated on 14 Jun 2015.