MODBUS Porting Layer (UDP)
[MODBUS Porting Layer]


Defines

#define MBP_UDPHDL_INVALID   NULL
#define MBP_UDP_CLIENTADDR_COPY(source, dest)
#define MBP_UDP_CLIENTADDR_FREE(addr)

Typedefs

typedef eMBErrorCode(* peMBPUDPClientNewDataCB )(xMBHandle xMBHdl) MB_CDECL_SUFFIX
typedef void * xMBPUDPHandle

Functions

eMBErrorCode eMBPUDPClientInit (xMBPUDPHandle *pxUDPHdl, xMBHandle xMBHdl, const CHAR *pcUDPBindAddress, LONG uUDPListenPort, peMBPUDPClientNewDataCB eMBPUDPClientNewDATAFN)
eMBErrorCode eMBPUDPConWrite (xMBPUDPHandle xUDPHdl, const CHAR *pcUDPClientAddress, USHORT usUDPSlavePort, const UBYTE *pubBuffer, USHORT usBufferLen)
eMBErrorCode eMBPUDPConRead (xMBPUDPHandle xUDPHdl, UBYTE *pubBuffer, USHORT *pusBufferLen, USHORT usBufferMax)
eMBErrorCode eMBPUDPConReadExt (xMBPUDPHandle xUDPHdl, CHAR **pucClientAddress, USHORT *pusClientPort, UBYTE *pubBuffer, USHORT *pusBufferLen, USHORT usBufferMax)
eMBErrorCode eMBPUDPClientClose (xMBPUDPHandle xUDPHdl)

Define Documentation

#define MBP_UDP_CLIENTADDR_COPY (  source,
dest   ) 
 

Value:

do { \
    if( source != NULL ) \
    { \
        dest = strdup( source ); \
    } \
    else \
    { \
        dest = NULL; \
    } \
} while( 0 )
Make a copy a client address.

You can either use strdup (default), an assigment or a custom function.

Parameters:
source Address to copy.
dest Pointer of type const CHAR * where the copied source address should be stored.

#define MBP_UDP_CLIENTADDR_FREE (  addr   ) 
 

Value:

do { \
    free( addr ); \
    addr = NULL; \
} while( 0 )
Free a previously copied address.

Parameters:
addr Address to release. It must be safe to pass a NULL pointer.

#define MBP_UDPHDL_INVALID   NULL
 

UDP porting layer invalid handle.

Typedef Documentation

typedef eMBErrorCode( * peMBPUDPClientNewDataCB)(xMBHandle xMBHdl) MB_CDECL_SUFFIX
 

Called by the UDP porting layer when new data has been received.

Returns:
eMBErrorCode::MB_ENOERR if the data was handled. If the data could not be processed right now then the stack returns eMBErrorCode::MB_EAGAIN. The caller than can either discard the data in which case the request is lost or call again later when the stack is ready to handle the data.

typedef void* xMBPUDPHandle
 

UDP porting layer instance handle.

Function Documentation

eMBErrorCode eMBPUDPClientClose (  xMBPUDPHandle  xUDPHdl  ) 
 

Shutdown a UDP instance for handling client connections.

All resources for this instance should be freed. This includes closing all sockets and dropping any possibly remaining data.

Parameters:
xUDPHdl A UDP handle for a client instance.
Returns:
MBErrorCode::MB_ENOERR if the client instance has been closed.

eMBErrorCode eMBPUDPClientInit (  xMBPUDPHandle *  pxUDPHdl,
xMBHandle  xMBHdl,
const CHAR *  pcUDPBindAddress,
LONG  uUDPListenPort,
peMBPUDPClientNewDataCB  eMBPUDPClientNewDATAFN
) 
 

Create a new UDP instance used by a MODBUS master.

This function should create two new sockets for sending and receiving data. If pcUDPBindAddress is not equal to NULL the sockets should be bound to the address specified in pcUDPBindAddress. Otherwise it should bind to all available interfaces. If uUDPListenPort equals -1 this function should allocate a free port used as a source port for sending data and as a listening port for receiving data.

Parameters:
pxUDPHdl A pointer to a handle. If the function succeeds the pointer contains a valid handle.
xMBHdl A valid handle for the MODBUS stack which handels this client connection.
pcUDPBindAddress Not used within the stack but passed to the porting layer. This argument can be used to bind only to a specific IP address.
uUDPListenPort Use -1 if the listing port should be allocated dynamically by the porting layer. Otherwise pass a valid port number between 0 and 65535.
eMBPUDPClientNewDATAFN Callback function if new client data is available.
Returns:
eMBErrorCode::MB_ENOERR if a new instance has been created. In case of invalid arguments it should return eMBErrorCode::MB_EINVAL. Otherweise eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPUDPConRead (  xMBPUDPHandle  xUDPHdl,
UBYTE *  pubBuffer,
USHORT *  pusBufferLen,
USHORT  usBufferMax
) 
 

This function is called by the MODBUS after the porting layer has called the eMBPUDPClientNewDATAFN.

This function shall return an entire UDP message in one call. This is a typical behaviour also for example for the Unix/OpenGroup recvfrom call for datagram sockets (http://pubs.opengroup.org/onlinepubs/009695399/functions/recvfrom.html)

Parameters:
xUDPHdl A handle to a UDP instance.
pusBufferLen Number of bytes received.
pubBuffer A buffer of usBufferMax bytes.
usBufferMax Size of buffer.
Returns:
The function should store up to usBufferMax in the buffer. If no error has occured it should return eMBErrorCode::MB_ENOERR. If the message has been truncated it shall return MB_EIO. Incase of an invalid handle or invalid arguments it should return eMBErrorCode::MB_EINVAL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPUDPConReadExt (  xMBPUDPHandle  xUDPHdl,
CHAR **  pucClientAddress,
USHORT *  pusClientPort,
UBYTE *  pubBuffer,
USHORT *  pusBufferLen,
USHORT  usBufferMax
) 
 

This function is identical to eMBPUDPConRead with the exception that is stores the source address and the source port of the client from whom we have received the data.

Parameters:
xUDPHdl A handle to a UDP instance.
pucClientAddress Pointer where the source address of the received UDP datagram shall be stored. It must be allocated such that the MBP_UDP_CLIENTADDR_FREE macros can be used. This buffer is freed by the stack so it is NOT allowed to pass a temporary static buffer.
pusClientPort Source port for the UDP datagram received.
pusBufferLen Number of bytes received.
pubBuffer A buffer of usBufferMax bytes.
usBufferMax Size of buffer.
Returns:
The function should store up to usBufferMax in the buffer. If no error has occured it should return eMBErrorCode::MB_ENOERR. If the message has been truncated it shall return MB_EIO. Incase of an invalid handle or invalid arguments it should return eMBErrorCode::MB_EINVAL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPUDPConWrite (  xMBPUDPHandle  xUDPHdl,
const CHAR *  pcUDPClientAddress,
USHORT  usUDPSlavePort,
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:
xUDPHdl A handle to a UDP instance.
pcUDPClientAddress UDP address where packet should be sent to.
usUDPSlavePort UDP port where packet should be sent to.
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.

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