BotSense bsProxy Dynamically Linked Library module interface. More...

#include "rnr/rnrconfig.h"
#include "rnr/netmsgs.h"
#include "botsense/BotSense.h"

Classes
struct	BsModInfo_T
	Standard bsProxy static interface module information structure type. More...

struct	BsModRsrcTbl_T
	Useful indirect indexing of handle to resource instance structure. More...

struct	BsModIter_T
	Module Iterator Type. More...

struct	BsModProxyCb_T
	Interface Module callbacks to bsProxy services type. More...

Macros
#define	BSMOD_SYM_INIT bsModInit
	Required Module Symbols. See below for function prototypes. More...

#define	BSMOD_SYM_EXIT bsModExit
	module deinit exit function

#define	BSMOD_SYM_OPEN bsModOpen
	open device function

#define	BSMOD_SYM_CLOSE bsModClose
	close device function

#define	BSMOD_SYM_REQUEST bsModRequest
	process client request function

#define	BSMOD_SYM_TRACE bsModTrace
	enable/disable tracing function

#define	BSMOD_SYM_INFO bsModInfo
	get module static info function

#define	_S_EXP(x) _S_LIT(x)
	Convert expanded macro parameter to string literal. More...

#define	_S_LIT(x) #x
	Convert macro parameter to string literal. More...

#define	BSMOD_SYM_INIT_S _S_EXP(BSMOD_SYM_INIT)
	Required Module Symbols Strings. More...

#define	BSMOD_SYM_EXIT_S _S_EXP(BSMOD_SYM_EXIT)
	exit function string

#define	BSMOD_SYM_OPEN_S _S_EXP(BSMOD_SYM_OPEN)
	open function string

#define	BSMOD_SYM_CLOSE_S _S_EXP(BSMOD_SYM_CLOSE)
	close function string

#define	BSMOD_SYM_REQUEST_S _S_EXP(BSMOD_SYM_REQUEST)
	request func string

#define	BSMOD_SYM_TRACE_S _S_EXP(BSMOD_SYM_TRACE)
	tracing func string

#define	BSMOD_SYM_INFO_S _S_EXP(BSMOD_SYM_INFO)
	info function string

#define	BSMOD_IS_VCONN_HANDLE(hndVConn)
	Test if the handle is in the valid module virtual connection range. More...

#define	BSMOD_RSRC_IS_FREE(pRsrcTbl, hndVConn)
	Test if the resource table resource handle slot is free. More...

#define	BSMOD_RSRC_IS_INUSE(pRsrcTbl, hndVConn)
	Test if the resource table resource handle slot is in-use. More...

#define	BSMOD_RSRC_INDEX(pRsrcTbl, hndVConn)
	Get the resource index given the handle. More...

#define	BSMOD_RSRC(pRsrcTbl, hndVConn)
	Get the resource given the handle. More...

#define	BSMOD_RSRC_INUSE_COUNT(pRsrcTbl) ((pRsrcTbl)->m_uInUseCount)
	Get the resouce table current in-use count. More...

#define	BSMOD_LOG_WARN(hndVConn, ecode, wfmt, ...)
	Log Interface Module Warning. More...

#define	BSMOD_LOG_ERROR(hndVConn, ecode, efmt, ...)
	Log Interface Module Error. More...

#define	BSMOD_LOG_NMERROR(hndVConn, nmecode, efmt, ...)
	Log Interface Module NetMsgs (Un)Packing Error. More...

#define	BSMOD_LOG_SYSERROR(hndVConn, efmt, ...)
	Log Interface Module System Error. More...

#define	BSMOD_SEND_ERROR_RSP(pCb, hndVConn, uTid, ecode, efmt, ...)
	Log *BotSense* Error and Send Error Response. More...

#define	BSMOD_SEND_NMERROR_RSP(pCb, hndVConn, uTid, nmecode, efmt, ...)
	Log NetMsgs (Un)Packing Error and Send Error Response. More...

#define	BSMOD_SEND_SYSERROR_RSP(pCb, hndVConn, uTid, efmt, ...)
	Log System Error and Send Error Response. More...

#define	BSMOD_TRY_VCONN_HND_RANGE(hndVConn)
	Check if handle is within the range of module handles. More...

Typedefs
typedef int(	BsModInitFunc_T) (const char sModUri, const BsModProxyCb_T pCallbacks)
	Initialize module. More...

typedef BsModInitFunc_T *	BsModInitFunc_P
	pointer to init function

typedef void(	BsModExitFunc_T) ()
	Exit module. More...

typedef BsModExitFunc_T *	BsModExitFunc_P
	pointer to exit function

typedef int(	BsModOpenFunc_T) (BsVConnHnd_T hndVConn, bool_t bTrace, const char *sDevUri, byte_t argbuf[], size_t uArgLen)
	Open device controlled by module and associate with handle. More...

typedef BsModOpenFunc_T *	BsModOpenFunc_P
	pointer to open function

typedef int(	BsModCloseFunc_T) (BsVConnHnd_T hndVConn)
	Close device controlled by module and disassociate handle. More...

typedef BsModCloseFunc_T *	BsModCloseFunc_P
	pointer to close function

typedef int(	BsModRequestFunc_T) (BsVConnHnd_T hndVConn, BsTid_T uTid, BsMsgId_T uMsgIdReq, byte_t bufReq[], size_t uReqLen)
	Service client-specific request directed to this interface module. More...

typedef BsModRequestFunc_T *	BsModRequestFunc_P
	pointer to request func.

typedef int(	BsModTraceFunc_T) (BsVConnHnd_T hndVConn, bool_t bTrace)
	Enable/disable message tracing on handle. More...

typedef BsModTraceFunc_T *	BsModTraceFunc_P
	pointer to msg trace func.

typedef const BsModInfo_T *(	BsModInfoFunc_T) ()
	Query for the static module information. More...

typedef BsModInfoFunc_T *	BsModInfoFunc_P
	pointer to mod info function

Enumerations
enum	BsModIterOver_T { BsModIterOverDevUri, BsModIterOverModUri, BsModIterOverVConn }
	What to iterate over. More...

Variables
BsModInitFunc_T	bsModInit
	init prototype

BsModExitFunc_T	bsModExit
	exit prototype

BsModOpenFunc_T	bsModOpen
	open prototype

BsModCloseFunc_T	bsModClose
	close prototype

BsModRequestFunc_T	bsModRequest
	request prototype

BsModTraceFunc_T	bsModTrace
	trace prototype

BsModInfoFunc_T	bsModInfo
	mod info prototype

Detailed Description

BotSense bsProxy Dynamically Linked Library module interface.

LastChangedDate: 2010-08-20 11:36:38 -0600 (Fri, 20 Aug 2010)

Rev: 568

The client side assumes responsibility for "doing the right thing". So, bsProxy does minimal consistency checking.

A bsProxy module must be thread safe. The bsProxy device thread provides context control and sequencing.

The bsProxy provides a unique handle to identify a specific device-module instance (virtual connection).

A bsProxy interface module:

Typically supports simultaneous multiple device-module instances.
Should support different devices of the same class simultaneously. (e.g. /dev/ttyS0 and /dev/ttyUSB0).
Should support different handles to the same device-module association.

Author: Robin Knight (robin.nosp@m..kni.nosp@m.ght@r.nosp@m.oadn.nosp@m.arrow.nosp@m.s.co.nosp@m.m)

Copyright: © 2010-2017. RoadNarrows LLC.
http://www.roadnarrows.com
All Rights Reserved

Definition in file bsProxyModIF.h.

Macro Definition Documentation

#define _S_EXP ( x ) _S_LIT(x)

Convert expanded macro parameter to string literal.

Parameters

x	Parameter.

Definition at line 92 of file bsProxyModIF.h.

#define _S_LIT ( x ) #x

Convert macro parameter to string literal.

Parameters

x	Parameter.

Definition at line 98 of file bsProxyModIF.h.

#define BSMOD_IS_VCONN_HANDLE ( hndVConn )

Value:

(((int)(hndVConn) >= BSPROXY_VCONN_MOD_MIN) && \

((int)(hndVConn) <= BSPROXY_VCONN_MOD_MAX))

BSPROXY_VCONN_MOD_MIN

#define BSPROXY_VCONN_MOD_MIN

minimum module-specific handle value

Definition: BotSense.h:141

BSPROXY_VCONN_MOD_MAX

#define BSPROXY_VCONN_MOD_MAX

maximum module-specific handle value

Definition: BotSense.h:142

Test if the handle is in the valid module virtual connection range.

Parameters

hndVConn Virtual connection handle.

Definition at line 149 of file bsProxyModIF.h.

Referenced by bsModI2CReqRead(), bsModI2CReqScan(), bsModI2CReqTrans(), bsModI2CReqWrite(), bsModNullReqWrite(), bsModRequest(), bsModSerialReqRead(), bsModSerialReqTrans(), bsModSerialReqWrite(), bsModTrace(), ModCbRsrcAdd(), and ModCbRsrcRemove().

#define BSMOD_LOG_ERROR	(	hndVConn,
		ecode,
		efmt,
		...
	)

Value:

LOGERROR("VConn=%d: %s(): %s(ecode=%d): " efmt, \
      hndVConn, LOGFUNCNAME, \
      bsStrError(ecode), (ecode>=0? ecode: -ecode), \
      ##__VA_ARGS__)

Log Interface Module Error.

Parameters

hndVConn	Virtual connection handle.
ecode

Definition at line 405 of file bsProxyModIF.h.

Referenced by bsModClose(), bsModOpen(), and bsModTrace().

#define BSMOD_LOG_NMERROR	(	hndVConn,
		nmecode,
		efmt,
		...
	)

Value:

BSMOD_LOG_ERROR(hndVConn, BS_ECODE_BAD_MSG, "%s(nmecode=%d): " efmt, \
      nmStrError(nmecode), (nmecode>=0? nmecode: -nmecode), \
      ##__VA_ARGS__)

Log Interface Module NetMsgs (Un)Packing Error.

Parameters

hndVConn	Virtual connection handle.
nmecode	NetMsgs error code.
efmt	Error output format string literal.
...	Error variable arguments.

Definition at line 419 of file bsProxyModIF.h.

Referenced by bsModOpen().

#define BSMOD_LOG_SYSERROR	(	hndVConn,
		efmt,
		...
	)

Value:

LOGERROR("VConn=%d: %s(): %s(ecode=%d): %s(errno=%d): " efmt, \
          hndVConn, LOGFUNCNAME, \
          bsStrError(BS_ECODE_SYS), BS_ECODE_SYS, \
          strerror(errno), errno, ##__VA_ARGS__)

Log Interface Module System Error.

Parameters

hndVConn	Virtual connection handle.
efmt	Error output format string litteral.
...	Error variable arguments.

Definition at line 431 of file bsProxyModIF.h.

Referenced by bsModOpen().

#define BSMOD_LOG_WARN	(	hndVConn,
		ecode,
		wfmt,
		...
	)

Value:

LOGDIAG3("Warning: VConn=%d: %s(): %s(ecode=%d): " wfmt, \
      hndVConn, LOGFUNCNAME, \
      bsStrError(ecode), ((ecode)>=0? (ecode): -(ecode)), \
      ##__VA_ARGS__)

Log Interface Module Warning.

Parameters

hndVConn	Virtual connection handle.
ecode

Definition at line 391 of file bsProxyModIF.h.

#define BSMOD_RSRC	(	pRsrcTbl,
		hndVConn
	)

Value:

( BSMOD_IS_VCONN_HANDLE(hndVConn)? \
      ((pRsrcTbl)->m_vecIndex[hndVConn] != (byte_t)BSPROXY_VCONN_UNDEF? \
        ((pRsrcTbl)->m_vecRsrc[(pRsrcTbl)->m_vecIndex[hndVConn]]): NULL): \
      NULL \
  )

Get the resource given the handle.

Parameters

pRsrcTbl	Pointer to resource table.
hndVConn	Virtual connection handle.

Returns: On success, returns pointer to resource. Else returns NULL.

Definition at line 196 of file bsProxyModIF.h.

Referenced by bsModI2CReqRead(), bsModI2CReqScan(), bsModI2CReqTrans(), bsModI2CReqWrite(), bsModNullReqWrite(), bsModRequest(), bsModSerialReqRead(), bsModSerialReqTrans(), bsModSerialReqWrite(), and bsModTrace().

#define BSMOD_RSRC_INDEX	(	pRsrcTbl,
		hndVConn
	)

Value:

( BSMOD_IS_VCONN_HANDLE(hndVConn)? \
      ((pRsrcTbl)->m_vecIndex[hndVConn] != (byte_t)BSPROXY_VCONN_UNDEF? \
        (int)((pRsrcTbl)->m_vecIndex[hndVConn]): -1): \
      -1 \
  )

Get the resource index given the handle.

Parameters

pRsrcTbl	Pointer to resource table.
hndVConn	Virtual connection handle.

Returns: On success, returns ≥ 0 index. Else returns -1.

Definition at line 181 of file bsProxyModIF.h.

Referenced by ModCbRsrcRemove().

#define BSMOD_RSRC_INUSE_COUNT ( pRsrcTbl ) ((pRsrcTbl)->m_uInUseCount)

Get the resouce table current in-use count.

Parameters

pRsrcTbl Pointer to resource table.

Definition at line 208 of file bsProxyModIF.h.

Referenced by bsModOpen().

#define BSMOD_RSRC_IS_FREE	(	pRsrcTbl,
		hndVConn
	)

Value:

(BSMOD_IS_VCONN_HANDLE(hndVConn) && \

(pRsrcTbl)->m_vecIndex[hndVConn] == (byte_t)BSPROXY_VCONN_UNDEF)

BSMOD_IS_VCONN_HANDLE

#define BSMOD_IS_VCONN_HANDLE(hndVConn)

Test if the handle is in the valid module virtual connection range.

Definition: bsProxyModIF.h:149

BSPROXY_VCONN_UNDEF

#define BSPROXY_VCONN_UNDEF

undefined virtual connection handle

Definition: BotSense.h:139

Test if the resource table resource handle slot is free.

Parameters

pRsrcTbl	Pointer to resource table.
hndVConn	Virtual connection handle.

Definition at line 159 of file bsProxyModIF.h.

#define BSMOD_RSRC_IS_INUSE	(	pRsrcTbl,
		hndVConn
	)

Value:

(BSMOD_IS_VCONN_HANDLE(hndVConn) && \

(pRsrcTbl)->m_vecIndex[hndVConn] != (byte_t)BSPROXY_VCONN_UNDEF)

BSMOD_IS_VCONN_HANDLE

#define BSMOD_IS_VCONN_HANDLE(hndVConn)

Test if the handle is in the valid module virtual connection range.

Definition: bsProxyModIF.h:149

BSPROXY_VCONN_UNDEF

#define BSPROXY_VCONN_UNDEF

undefined virtual connection handle

Definition: BotSense.h:139

Test if the resource table resource handle slot is in-use.

Parameters

pRsrcTbl	Pointer to resource table.
hndVConn	Virtual connection handle.

Definition at line 169 of file bsProxyModIF.h.

Referenced by bsModClose(), and bsModOpen().

#define BSMOD_SEND_ERROR_RSP	(	pCb,
		hndVConn,
		uTid,
		ecode,
		efmt,
		...
	)

Value:

do \
  { \
    BSMOD_LOG_ERROR(hndVConn, ecode, efmt, ##__VA_ARGS__); \
    (pCb)->m_cbSendErrorRsp(hndVConn, uTid, ecode, efmt, ##__VA_ARGS__); \
  } while(0)

Log BotSense Error and Send Error Response.

Parameters

pCb	Pointer to server callbacks.
hndVConn	Virtual connection handle.
uTid	Request-Response transaction id.
ecode

Definition at line 447 of file bsProxyModIF.h.

Referenced by bsModI2CReqRead(), bsModI2CReqScan(), bsModI2CReqTrans(), bsModI2CReqWrite(), bsModNullReqWrite(), bsModRequest(), bsModSerialReqRead(), bsModSerialReqTrans(), and bsModSerialReqWrite().

#define BSMOD_SEND_NMERROR_RSP	(	pCb,
		hndVConn,
		uTid,
		nmecode,
		efmt,
		...
	)

Value:

do \
  { \
    BSMOD_LOG_NMERROR(hndVConn, nmecode, efmt, ##__VA_ARGS__); \
    (pCb)->m_cbSendErrorRsp(hndVConn, uTid, BS_ECODE_BAD_MSG, efmt, \
                          ##__VA_ARGS__); \
  } while(0)

Log NetMsgs (Un)Packing Error and Send Error Response.

Parameters

pCb	Pointer to server callbacks.
hndVConn	Virtual connection handle.
uTid	Request-Response transaction id.
nmecode	NetMsgs error code.
efmt	Error output format string literal.
...	Error variable arguments.

Definition at line 464 of file bsProxyModIF.h.

Referenced by bsModI2CReqRead(), bsModI2CReqScan(), bsModI2CReqTrans(), bsModI2CReqWrite(), bsModNullReqWrite(), bsModSerialReqRead(), bsModSerialReqTrans(), and bsModSerialReqWrite().

#define BSMOD_SEND_SYSERROR_RSP	(	pCb,
		hndVConn,
		uTid,
		efmt,
		...
	)

Value:

do \
  { \
    BSMOD_LOG_SYSERROR(hndVConn, efmt, ##__VA_ARGS__); \
    (pCb)->m_cbSendErrorRsp(hndVConn, uTid, BS_ECODE_SYS, \
        "%s(errno=%d): " efmt, \
        strerror(errno), errno, ##__VA_ARGS__); \
  } while(0)

Log System Error and Send Error Response.

Parameters

pCb	Pointer to server callbacks.
hndVConn	Virtual connection handle.
uTid	Request-Response transaction id.
efmt	Error output format string literal.
...	Error variable arguments.

Definition at line 481 of file bsProxyModIF.h.

Referenced by bsModI2CReqRead(), bsModI2CReqScan(), bsModI2CReqTrans(), bsModI2CReqWrite(), bsModNullReqWrite(), bsModSerialReqRead(), bsModSerialReqTrans(), and bsModSerialReqWrite().

#define BSMOD_SYM_INIT bsModInit

Required Module Symbols. See below for function prototypes.

module initialization function

Definition at line 80 of file bsProxyModIF.h.

#define BSMOD_SYM_INIT_S _S_EXP(BSMOD_SYM_INIT)

Required Module Symbols Strings.

init function string

Definition at line 103 of file bsProxyModIF.h.

Referenced by ModDllNewIF().

#define BSMOD_TRY_VCONN_HND_RANGE ( hndVConn )

Value:

do \
  { \
    if( !BSMOD_IS_VCONN_HANDLE(hndVConn) ) \
    { \
      BSMOD_LOG_ERROR(hndVConn, BS_ECODE_BAD_VCONN_HND, \
          "Module vconn handle out-of-range."); \
      return -BS_ECODE_BAD_VCONN_HND; \
    } \
  } while(0)

Check if handle is within the range of module handles.

If the check is false, an appropriate error is logged and the calling function is immediately exited by invoking a return with the appropriate < 0 error code.

Parameters

hndVConn Virtual connection handle.

Definition at line 499 of file bsProxyModIF.h.

Referenced by bsModClose(), and bsModOpen().

Typedef Documentation

typedef int( BsModCloseFunc_T) (BsVConnHnd_T hndVConn)

Close device controlled by module and disassociate handle.

The handle instance specific resources should be freed.

Parameters

hndVConn Virtual connection handle.

Returns: On success, BS_OK is returned.
On error, the appropriate < 0 negated BotSense Error Code is returned.

Definition at line 580 of file bsProxyModIF.h.

typedef void( BsModExitFunc_T) ()

Exit module.

Called once prior to module being unloaded.

Any module owned resources should be freed here. Any active handles associated opened devices should be closed.

Definition at line 540 of file bsProxyModIF.h.

typedef const BsModInfo_T*( BsModInfoFunc_T) ()

Query for the static module information.

Returns: Pointer to module static information.

Definition at line 620 of file bsProxyModIF.h.

typedef int( BsModInitFunc_T) (const char *sModUri, const BsModProxyCb_T *pCallbacks)

Initialize module.

Called once after module is loaded.

Global module initialization and resource allocation should be done here.

Parameters

sModUri	Expanded, canonical module path name.
pCallbacks	Pointer to a set of module -> bsProxy core callback functions.

Returns: On success, BS_OK is returned.
On error, the appropriate < 0 negated BotSense Error Code is returned.

Definition at line 528 of file bsProxyModIF.h.

typedef int( BsModOpenFunc_T) (BsVConnHnd_T hndVConn, bool_t bTrace, const char *sDevUri, byte_t argbuf[], size_t uArgLen)

Open device controlled by module and associate with handle.

Subsequent calls to the module use the given handle to associate the specific module-device instance.

The argument buffer contains packed message arguements specific to the device and module.

Parameters

hndVConn	Virtual connection handle.
bTrace	Do [not] enable message tracing on this handle.
sDevUri	Expanded, canonical device path name.
argbuf	Packed specific open configuration arguments submessage.
uArgLen	Length of packed argumets in buffer (number of bytes).

Returns: On success, returns a unique resource descriptor ≥ 0 which is typically an opened file descriptor or socket descriptor, but can be module defined.

On error, the appropriate < 0 negated BotSense Error Code is returned.

Definition at line 563 of file bsProxyModIF.h.

typedef int( BsModRequestFunc_T) (BsVConnHnd_T hndVConn, BsTid_T uTid, BsMsgId_T uMsgIdReq, byte_t bufReq[], size_t uReqLen)

Service client-specific request directed to this interface module.

Note: A module-specific request service must send a response.

Parameters

hndVConn	Virtual connection handle.
uTid	Request-Response transaction id.
uMsgIdReq	Request message id.
bufReq	Packed request message buffer.
uReqLen	Length of request in buffer (number of bytes).

Returns: On success, BS_OK is returned.
On error, the appropriate < 0 negated BotSense Error Code is returned.

Definition at line 596 of file bsProxyModIF.h.

typedef int( BsModTraceFunc_T) (BsVConnHnd_T hndVConn, bool_t bTrace)

Enable/disable message tracing on handle.

Parameters

hndVConn	Virtual connection handle.
bTrace	Do [not] enable message tracing on this handle.

Returns: On success, BS_OK is returned.
On error, the appropriate < 0 negated BotSense Error Code is returned.

Definition at line 611 of file bsProxyModIF.h.

Enumeration Type Documentation

enum BsModIterOver_T

What to iterate over.

Enumerator
BsModIterOverDevUri	iterator over device URI
BsModIterOverModUri	iterator over module URI
BsModIterOverVConn	iterator over virtual connections (no pattern)

Definition at line 213 of file bsProxyModIF.h.

 {
   BsModIterOverDevUri,      ///< iterator over device URI
   BsModIterOverModUri,      ///< iterator over module URI
   BsModIterOverVConn        ///< iterator over virtual connections (no pattern)
 } BsModIterOver_T;

Classes

Macros

Typedefs

Enumerations

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation