msgqueue.h File Reference

The MsgQueue command group allows to exchange arbitrary data messages between multiple BRP hosts. More...

#include "../typedefs.h"

Go to the source code of this file.

Macros
#define	BRP_MsgQueue_ErrMsgqRecvTimeout   BRP_ERR_STATUS(0xA600, 0x01)
	Timeout: no message received within the specified time interval. More...
#define	BRP_MsgQueue_ErrMsgqNotackedTimeout   BRP_ERR_STATUS(0xA600, 0x02)
	Timeout: the message was not picked up within the specified time interval. More...
#define	BRP_MsgQueue_ErrMsgqCollision   BRP_ERR_STATUS(0xA600, 0x03)
	Collision: there is already a message in the queue - pick up this data first. More...
#define	BRP_MsgQueue_ErrMsgqBufoverflow   BRP_ERR_STATUS(0xA600, 0x04)
	Buffer Overflow: the message is too large and can not be processed. More...

Functions
brp_errcode	brp_MsgQueue_GetMsgSize (brp_protocol protocol, unsigned *BufferSize)
	Retrieve the maximum message size the reader supports. More...
brp_errcode	brp_MsgQueue_Receive (brp_protocol protocol, unsigned Timeout, brp_buf *RecvMsg, size_t *RecvMsg_len, brp_mempool *mempool)
	Wait for a message and return its content. More...
brp_errcode	brp_MsgQueue_Send (brp_protocol protocol, brp_buf SendMsg, size_t SendMsg_len, unsigned Timeout)
	Put a message into the Message Queue and wait a maximum time of Timeout ms until the message has been picked up. More...
brp_errcode	brp_MsgQueue_SendReceive (brp_protocol protocol, brp_buf SendMsg, size_t SendMsg_len, unsigned Timeout, brp_buf *RecvMsg, size_t *RecvMsg_len, brp_mempool *mempool)
	This command combines Send and Receive to a single command. More...

Detailed Description

The MsgQueue command group allows to exchange arbitrary data messages between multiple BRP hosts.

The message exchange is based on a queue that can be accessed by the different BRP hosts. Every host can put a message into the queue (Send command) or can retrieve a message from it (Receive command).

Only one single message can reside in the queue. If a host wants to put a message into a non-empty queue it can only overwrite the queue content if it originates from the host itself. Otherwise a MSGQ_COLLISION_ERR is returned in order to avoid data loss. In this case the message has to be picked up with the Receive command first, which clears the queue. Then a new message can be sent.

The maximum allowed size of a message can be retrieved with GetMsgSize command. A Send/SendReceive command that exceeds this size returns the status code MSGQ_BUFOVERFLOW_ERR.

There are 3 commands for the message handling:

1. Receive: Retrieve a message from the queue
2. Send: Put a message into the queue
3. SendReceive: Put a message into the queue and wait for reception of a new message (combines Send and Receive)

A basic data exchange with alternated sent messages (A => B => A => B => A => B ....) could be implemented like this:

` A: Receive B: Receive A: Wait until there is a message to be sent: SendReceive(Msg1) B: Receive returns with Msg1;Answer with Msg2: SendReceive(Msg2) A: SendReceive returns with Msg2; Answer with Msg3: SendReceive(Msg3) ... `

A larger data transfer from A to B consisting of multiples messages without B having to send a response every time could be implemented this way:

` A: Receive B: Receive A: Wait until there is a message to be sent: Send(Msg1) B: Receive returns Msg1; Receive next part: Receive A: Send returns after B picked up the data; Send next part: Send(Msg2) B: Receive returns Msg2; Receive next part: Receive ... `

Every Send call of A returns as soon as B has picked up the data, so A can directly proceed with the next Send.

Definition in file msgqueue.h.