This file implements the base interface for all Serial and Ethernet ports. More...

#include <sbgCommon.h>

Data Structures
struct	_SbgInterface

Macros
#define	SBG_IF_NAME_MAX_SIZE (48)

#define	SBG_IF_TYPE_UNKNOW (0)

#define	SBG_IF_TYPE_SERIAL (1)

#define	SBG_IF_TYPE_ETH_UDP (2)

#define	SBG_IF_TYPE_ETH_TCP_IP (3)

#define	SBG_IF_TYPE_FILE (4)

#define	SBG_IF_TYPE_LAST_RESERVED (999)

#define	SBG_IF_FLUSH_INPUT ((uint32_t)1 << 0)

#define	SBG_IF_FLUSH_OUTPUT ((uint32_t)1 << 1)

#define	SBG_IF_FLUSH_ALL (SBG_IF_FLUSH_INPUT \| SBG_IF_FLUSH_OUTPUT)

Typedefs
typedef struct _SbgInterface	SbgInterface

typedef void *	SbgInterfaceHandle

typedef SbgErrorCode(*	SbgInterfaceDestroyFunc) (SbgInterface *pInterface)

typedef SbgErrorCode(*	SbgInterfaceWriteFunc) (SbgInterface pInterface, const void pBuffer, size_t bytesToWrite)

typedef SbgErrorCode(*	SbgInterfaceReadFunc) (SbgInterface pInterface, void pBuffer, size_t *pReadBytes, size_t bytesToRead)

typedef SbgErrorCode(*	SbgInterfaceFlushFunc) (SbgInterface *pInterface, uint32_t flags)

typedef SbgErrorCode(*	SbgInterfaceSetSpeed) (SbgInterface *pInterface, uint32_t speed)

typedef uint32_t(*	SbgInterfaceGetSpeed) (const SbgInterface *pInterface)

typedef uint32_t(*	SbgInterfaceGetDelayFunc) (const SbgInterface *pInterface, size_t numBytes)

Functions
SBG_COMMON_LIB_API void	sbgInterfaceZeroInit (SbgInterface *pInterface)

SBG_COMMON_LIB_API SbgErrorCode	sbgInterfaceDestroy (SbgInterface *pInterface)

SBG_INLINE uint32_t	sbgInterfaceTypeGet (const SbgInterface *pInterface)

SBG_COMMON_LIB_API const char *	sbgInterfaceTypeGetAsString (const SbgInterface *pInterface)

SBG_INLINE const char *	sbgInterfaceNameGet (const SbgInterface *pInterface)

SBG_COMMON_LIB_API void	sbgInterfaceNameSet (SbgInterface pInterface, const char pName)

SBG_INLINE SbgErrorCode	sbgInterfaceWrite (SbgInterface pInterface, const void pBuffer, size_t bytesToWrite)

SBG_INLINE SbgErrorCode	sbgInterfaceRead (SbgInterface pInterface, void pBuffer, size_t *pReadBytes, size_t bytesToRead)

SBG_INLINE SbgErrorCode	sbgInterfaceFlush (SbgInterface *pInterface, uint32_t flags)

SBG_INLINE SbgErrorCode	sbgInterfaceSetSpeed (SbgInterface *pInterface, uint32_t speed)

SBG_INLINE uint32_t	sbgInterfaceGetSpeed (const SbgInterface *pInterface)

SBG_INLINE uint32_t	sbgInterfaceGetDelay (const SbgInterface *pInterface, size_t numBytes)

Detailed Description

This file implements the base interface for all Serial and Ethernet ports.

Author: SBG Systems

Date: 10 December 2012

An interface is used to provide a common API for both serial and Ethernet ports. An interface can be opened/closed and some data can be written or read from it.

Copyright: Copyright (C) 2022, SBG Systems SAS. All rights reserved.

License

The MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

◆ SBG_IF_NAME_MAX_SIZE

#define SBG_IF_NAME_MAX_SIZE (48)

Maximum size in bytes for the interface name string

◆ SBG_IF_TYPE_UNKNOW

#define SBG_IF_TYPE_UNKNOW (0)

Type values reserved for standard interface types. The interface type is not defined.

◆ SBG_IF_TYPE_SERIAL

#define SBG_IF_TYPE_SERIAL (1)

The interface is a serial com port.

◆ SBG_IF_TYPE_ETH_UDP

#define SBG_IF_TYPE_ETH_UDP (2)

The interface is an UDP one.

◆ SBG_IF_TYPE_ETH_TCP_IP

#define SBG_IF_TYPE_ETH_TCP_IP (3)

The interface is an TCP/IP one.

◆ SBG_IF_TYPE_FILE

#define SBG_IF_TYPE_FILE (4)

The interface is a file.

◆ SBG_IF_TYPE_LAST_RESERVED

#define SBG_IF_TYPE_LAST_RESERVED (999)

Last reserved value for standard types.

◆ SBG_IF_FLUSH_INPUT

#define SBG_IF_FLUSH_INPUT ((uint32_t)1 << 0)

Flush input data flag.

◆ SBG_IF_FLUSH_OUTPUT

#define SBG_IF_FLUSH_OUTPUT ((uint32_t)1 << 1)

Flush output data flag.

◆ SBG_IF_FLUSH_ALL

#define SBG_IF_FLUSH_ALL (SBG_IF_FLUSH_INPUT | SBG_IF_FLUSH_OUTPUT)

Flag combination to flush both input and output data.

Typedef Documentation

◆ SbgInterface

typedef struct _SbgInterface SbgInterface

Interface structure pre-definition.

◆ SbgInterfaceHandle

typedef void* SbgInterfaceHandle

Handle that stores the internal interface handle (ie Serial or Ethernet)

◆ SbgInterfaceDestroyFunc

typedef SbgErrorCode(* SbgInterfaceDestroyFunc) (SbgInterface *pInterface)

Method to implement that close and destroy an interface.

Parameters

[in] pInterface Interface instance.

Returns: SBG_NO_ERROR if the interface has been closed successfully.

◆ SbgInterfaceWriteFunc

typedef SbgErrorCode(* SbgInterfaceWriteFunc) (SbgInterface *pInterface, const void *pBuffer, size_t bytesToWrite)

Method to implement to write a buffer to an interface.

This method should return an error only if all bytes were not written successfully. If you try to write zero byte, the method shouldn't return any error.

Parameters

[in]	pInterface	Interface instance.
[in]	pBuffer	Pointer on an allocated buffer that contains the data to write
[in]	bytesToWrite	Number of bytes we would like to write (can be zero).

Returns: SBG_NO_ERROR if exactly bytesToWrite have been written successfully.

◆ SbgInterfaceReadFunc

typedef SbgErrorCode(* SbgInterfaceReadFunc) (SbgInterface *pInterface, void *pBuffer, size_t *pReadBytes, size_t bytesToRead)

Method to implement to read data from an interface.

This method returns an error only if there is a 'low level' error on the interface. If no byte is read at all or less bytes than bytesToRead, this method returns SBG_NO_ERROR. You have to check pReadBytes field to know the number of bytes actually read.

Parameters

[in]	pInterface	Interface instance.
[in]	pBuffer	Pointer on an allocated buffer that can hold at least bytesToRead bytes of data.
[out]	pReadBytes	Returns the number of bytes actually read (can be zero and up to bytesToRead).
[in]	bytesToRead	Maximum number of bytes to try to read on the interface.

Returns: SBG_NO_ERROR if zero or some bytes have been read successfully.

◆ SbgInterfaceFlushFunc

typedef SbgErrorCode(* SbgInterfaceFlushFunc) (SbgInterface *pInterface, uint32_t flags)

Make an interface flush pending input and/or output data.

If flags include SBG_IF_FLUSH_INPUT, all pending input data is discarded. If flags include SBG_IF_FLUSH_OUTPUT, the function blocks until all output data has been written out.

WARNING: The method has no action if not applicable for a type of interface

Parameters

[in]	pInterface	Interface instance.
[in]	flags	Combination of the SBG_IF_FLUSH_INPUT and SBG_IF_FLUSH_OUTPUT flags.

Returns: SBG_NO_ERROR if successful.

◆ SbgInterfaceSetSpeed

typedef SbgErrorCode(* SbgInterfaceSetSpeed) (SbgInterface *pInterface, uint32_t speed)

Change an interface input and output speed in bps (bit per second)

This method will try to change the speed immediately even if there are pending bytes in the send buffer.

If you would like to make sure that all bytes in the Tx buffer have been sent before changing the speed, please flush the interface before.

WARNING: The method has no action if not applicable for a type of interface

Parameters

[in]	pInterface	Interface instance.
[in]	speed	The new interface speed to set in bps.

Returns: SBG_NO_ERROR if successful.

◆ SbgInterfaceGetSpeed

typedef uint32_t(* SbgInterfaceGetSpeed) (const SbgInterface *pInterface)

Returns the current interface baud rate in bps (bit per second)

WARNING: The method will returns zero if not applicable for a type of interface

Parameters

[in] pInterface Interface instance.

Returns: The current interface baud rate in bps or zero if not applicable.

◆ SbgInterfaceGetDelayFunc

typedef uint32_t(* SbgInterfaceGetDelayFunc) (const SbgInterface *pInterface, size_t numBytes)

Compute and return the delay needed by the interface to transmit / receive X number of bytes.

WARNING: The method will returns zero if not applicable for a type of interface.

Parameters

[in]	pInterface	Interface instance.
[in]	numBytes	The number of bytes to transmit / receive to evaluate the needed delay.

Returns: The expected delay in us needed to transmit / receive the specified number of bytes or 0 if not applicable.

Function Documentation

◆ sbgInterfaceZeroInit()

SBG_COMMON_LIB_API void sbgInterfaceZeroInit ( SbgInterface * pInterface )

Initialize an interface instance to zero.

Parameters

[in] pInterface The interface instance.

◆ sbgInterfaceDestroy()

SBG_COMMON_LIB_API SbgErrorCode sbgInterfaceDestroy ( SbgInterface * pInterface )

Close and destroy the interface gracefully.

This method will call the specialized interface destructor if any.

Parameters

[in] pInterface The interface instance.

Returns: SBG_NO_ERROR if the interface has been destroyed successfully.

◆ sbgInterfaceTypeGet()

SBG_INLINE uint32_t sbgInterfaceTypeGet ( const SbgInterface * pInterface )

Returns the interface type.

Parameters

[in] pInterface Interface instance

Returns: The interface type.

References _SbgInterface::type.

◆ sbgInterfaceTypeGetAsString()

SBG_COMMON_LIB_API const char* sbgInterfaceTypeGetAsString ( const SbgInterface * pInterface )

Returns the interface as string.

Parameters

[in] pInterface Interface instance

Returns: The interface type.

◆ sbgInterfaceNameGet()

SBG_INLINE const char* sbgInterfaceNameGet ( const SbgInterface * pInterface )

Returns the interface name string.

Parameters

[in] pInterface Interface instance

Returns: The interface name as a NULL terminated C string.

References _SbgInterface::name.

◆ sbgInterfaceNameSet()

SBG_COMMON_LIB_API void sbgInterfaceNameSet	(	SbgInterface *	pInterface,
		const char *	pName
	)

Define the interface name as a NULL terminated C string.

This method make sure that the provided string will always fit within the allocated name buffer.

If the interface name you would like to set is too long, only the end of the string will be kept.

Parameters

[in]	pInterface	Interface instance
[in]	pName	The interface name to set as a NULL terminated C string

◆ sbgInterfaceWrite()

SBG_INLINE SbgErrorCode sbgInterfaceWrite	(	SbgInterface *	pInterface,
		const void *	pBuffer,
		size_t	bytesToWrite
	)

Write some data to an interface.

This method should return an error only if all bytes were not written successfully. If you try to write zero byte, the method shouldn't return any error.

Parameters

[in]	pInterface	Interface instance.
[in]	pBuffer	Pointer on an allocated buffer that contains the data to write
[in]	bytesToWrite	Number of bytes we would like to write (can be zero).

Returns: SBG_NO_ERROR if exactly bytesToWrite have been written successfully. SBG_INVALID_PARAMETER if the interface doesn't support write operations.

References _SbgInterface::pWriteFunc, and SBG_INVALID_PARAMETER.

◆ sbgInterfaceRead()

SBG_INLINE SbgErrorCode sbgInterfaceRead	(	SbgInterface *	pInterface,
		void *	pBuffer,
		size_t *	pReadBytes,
		size_t	bytesToRead
	)

Try to read some data from an interface.

This method returns an error only if there is a 'low level' error on the interface. If no byte is read at all or less bytes than bytesToRead, this method returns SBG_NO_ERROR. You have to check pReadBytes field to know the number of bytes actually read.

Parameters

[in]	pInterface	Interface instance.
[in]	pBuffer	Pointer on an allocated buffer that can hold at least bytesToRead bytes of data.
[out]	pReadBytes	Returns the number of bytes actually read (can be zero and up to bytesToRead).
[in]	bytesToRead	Maximum number of bytes to try to read on the interface.

Returns: SBG_NO_ERROR if zero or some bytes have been read successfully. SBG_INVALID_PARAMETER if the interface doesn't support read operations.

References _SbgInterface::pReadFunc, and SBG_INVALID_PARAMETER.

◆ sbgInterfaceFlush()

SBG_INLINE SbgErrorCode sbgInterfaceFlush	(	SbgInterface *	pInterface,
		uint32_t	flags
	)

Make an interface flush pending input and/or output data.

If flags include SBG_IF_FLUSH_INPUT, all pending input data is discarded. If flags include SBG_IF_FLUSH_OUTPUT, the function blocks until all output data has been written out.

WARNING: The method has no action if not applicable for a type of interface

Parameters

[in]	pInterface	Interface instance.
[in]	flags	Combination of the SBG_IF_FLUSH_INPUT and SBG_IF_FLUSH_OUTPUT flags.

Returns: SBG_NO_ERROR if successful.

References _SbgInterface::pFlushFunc, SBG_IF_FLUSH_ALL, and SBG_NO_ERROR.

◆ sbgInterfaceSetSpeed()

SBG_INLINE SbgErrorCode sbgInterfaceSetSpeed	(	SbgInterface *	pInterface,
		uint32_t	speed
	)

Change an interface input and output speed in bps (bit per second)

This method will try to change the speed immediately even if there are pending bytes in the send buffer.

If you would like to make sure that all bytes in the Tx buffer have been sent before changing the speed, please flush the interface before.

WARNING: The method has no action if not applicable for a type of interface

Parameters

[in]	pInterface	Interface instance.
[in]	speed	The new interface speed to set in bps.

Returns: SBG_NO_ERROR if successful.

References _SbgInterface::pSetSpeedFunc, and SBG_NO_ERROR.

◆ sbgInterfaceGetSpeed()

SBG_INLINE uint32_t sbgInterfaceGetSpeed ( const SbgInterface * pInterface )

Returns the current interface baud rate in bps (bit per second)

WARNING: The method will returns zero if not applicable for a type of interface

Parameters

[in] pInterface Interface instance.

Returns: The current interface baud rate in bps or zero if not applicable.

References _SbgInterface::pGetSpeedFunc.

◆ sbgInterfaceGetDelay()

SBG_INLINE uint32_t sbgInterfaceGetDelay	(	const SbgInterface *	pInterface,
		size_t	numBytes
	)

Compute and return the delay needed by the interface to transmit / receive X number of bytes.

WARNING: The method will returns zero if not applicable for a type of interface.

Parameters

[in]	pInterface	Interface instance.
[in]	numBytes	The number of bytes to transmit / receive to evaluate the needed delay.

Returns: The expected delay in us needed to transmit / receive the specified number of bytes or 0 if not applicable.

References _SbgInterface::pDelayFunc.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SBG_IF_NAME_MAX_SIZE

◆ SBG_IF_TYPE_UNKNOW

◆ SBG_IF_TYPE_SERIAL

◆ SBG_IF_TYPE_ETH_UDP

◆ SBG_IF_TYPE_ETH_TCP_IP

◆ SBG_IF_TYPE_FILE

◆ SBG_IF_TYPE_LAST_RESERVED

◆ SBG_IF_FLUSH_INPUT

◆ SBG_IF_FLUSH_OUTPUT

◆ SBG_IF_FLUSH_ALL

Typedef Documentation

◆ SbgInterface

◆ SbgInterfaceHandle

◆ SbgInterfaceDestroyFunc

◆ SbgInterfaceWriteFunc

◆ SbgInterfaceReadFunc

◆ SbgInterfaceFlushFunc

◆ SbgInterfaceSetSpeed

◆ SbgInterfaceGetSpeed

◆ SbgInterfaceGetDelayFunc

Function Documentation

◆ sbgInterfaceZeroInit()

◆ sbgInterfaceDestroy()

◆ sbgInterfaceTypeGet()

◆ sbgInterfaceTypeGetAsString()

◆ sbgInterfaceNameGet()

◆ sbgInterfaceNameSet()

◆ sbgInterfaceWrite()

◆ sbgInterfaceRead()

◆ sbgInterfaceFlush()

◆ sbgInterfaceSetSpeed()

◆ sbgInterfaceGetSpeed()

◆ sbgInterfaceGetDelay()