MsgDescr_t Struct Reference
[Messaging System]

Describes a message, including who should receive it and data needed to handle acknowledgments. More...

#include <message.h>

Collaboration diagram for MsgDescr_t:

[legend]

Data Fields
union {
struct {
Bool   bcast: 1
	Indicates that the message may be broadcast to clients.
Bool   buffLifeUnmanaged: 1
	Indicates the message buffer will not be destroyed by the messaging system until BufferFree() is called outside of the system.
Bool   doNotAddId: 1
	True when the message format does not need a message ID number added.
Bool   inflight: 1
	True while this struct has valid data and is being used to send and track acknowledgments to a message.
Bool   mcast: 1
	Indicates that the message may be multicast to clients.
Bool   noResend: 1
	When true, the message will not be resent.
}
Uint8   flags
	Bit flags that indicate the message's state and affect how the message is handled.
};
AcknowledgeMsg	ackFunc
	The function called to react to acknowledgment of recipt of the message.
ApproveSendMsg	approveFunc
	Approves a message to be sent to each recipient, or NULL to always approve sending the message.
NetBuffer *	buffer
	Warning: Changed to always be persistent, but will be freed after the last (re)send potentially before the message is freed.
void *	data
	A pointer to arbitrary data for use by the message's handling functions.
Uint16	destMap [((((32)%(sizeof(Uint16)*8)) > 0)?((int)(32)/(sizeof(Uint16)*8)+1):((int)(32)/(sizeof(Uint16)*8)))]
	A bitmap of which clients the message is destined for who have not yet acknowledged the message.
FailMsg	failFunc
	The function called to react to a recipient that failed to acknowledge the message.
Uint16	interval
	The time in milliseconds between sends.
Uint16	msgId
	The identifier for the message.
Uint32	nextSend
	The common game time when the message will be resent if not all recpients have acknowledged the message.
Sint8	triesLeft
	The number of attempts remaining before giving up on this message.

---

Detailed Description

Describes a message, including who should receive it and data needed to handle acknowledgments.

Author:

Jeff Jackowski

Definition at line 351 of file message.h.

---

Field Documentation

union { ... }

AcknowledgeMsg MsgDescr_t::ackFunc

The function called to react to acknowledgment of recipt of the message.

May be NULL if there is no action upon acknowledgment.

Definition at line 364 of file message.h.

Referenced by AppendPlayerData(), SendDisconnectMessage(), SendScoreUpdate(), SendSpawnRequest(), and ServiceGameConfig().

ApproveSendMsg MsgDescr_t::approveFunc

Approves a message to be sent to each recipient, or NULL to always approve sending the message.

Definition at line 374 of file message.h.

Referenced by AppendPlayerData(), Send(), SendDisconnectMessage(), SendScoreUpdate(), SendSpawnRequest(), and ServiceGameConfig().

Bool MsgDescr_t::bcast

Indicates that the message may be broadcast to clients.

Note:

Only valid for servers.

Definition at line 455 of file message.h.

Referenced by AddToConfigList(), Send(), SendDisconnectMessage(), SendScoreUpdate(), SendSpawnRequest(), and ServiceGameConfig().

NetBuffer* MsgDescr_t::buffer

Warning:

Changed to always be persistent, but will be freed after the last (re)send potentially before the message is freed.

A buffer given to this descriptor to write out a message. The lifespan of the message is one transmission unless either one of the flags buffLifeMsg or buffLifeUnmanaged is set. If the buffer should be dropped while the message is still in-flight, then call BufferFree() with this pointer and clear buffLifeMsg. To regain a persistent buffer, set buffLifeMsg in the constrFunc function.

The length of the buffer should be set by constrFunc or be set before the call to AddMessage(). A negative value is interpreted as an error and will cause the message to be canceled.

Definition at line 390 of file message.h.

Referenced by AddMessage(), AppendPlayerData(), MessageFree(), MsgFailDropConnection(), Send(), SendDisconnectMessage(), SendScoreUpdate(), SendSpawnRequest(), and ServiceGameConfig().

Bool MsgDescr_t::buffLifeUnmanaged

Indicates the message buffer will not be destroyed by the messaging system until BufferFree() is called outside of the system.

Definition at line 473 of file message.h.

Referenced by MessageFree(), Send(), and ServiceGameConfig().

void* MsgDescr_t::data

A pointer to arbitrary data for use by the message's handling functions.

Bug:

If the message is canceled, any dynamically allocated data referenced here will not be deallocated.

Definition at line 396 of file message.h.

Uint16 MsgDescr_t::destMap[((((32)%(sizeof(Uint16)*8)) > 0)?((int)(32)/(sizeof(Uint16)*8)+1):((int)(32)/(sizeof(Uint16)*8)))]

A bitmap of which clients the message is destined for who have not yet acknowledged the message.

All elements of the array are set to zero in MessageNew(). Using this provides greater flexibility than storing a single address and uses less memory than an INetAddr struct. Use DESTMAPLEN as the array's size.

Warning:

The data type is configurable, so do not assume its size.

Note:

On the client, the least significant bit of the first array element is used to denote the destination is the server. It must be cleared to indicate the server has acknowledged the message, and it must be set either by the constrFunc or before AddMessage() is called.

Definition at line 410 of file message.h.

Referenced by AddMessage(), AddToConfigList(), AppendPlayerData(), MessageNew(), Send(), SendDisconnectMessage(), SendSpawnRequest(), and ServiceGameConfig().

Bool MsgDescr_t::doNotAddId

True when the message format does not need a message ID number added.

Normally messages will need an ID. They will be added when this flag is cleared.

Definition at line 479 of file message.h.

Referenced by AddMessage().

FailMsg MsgDescr_t::failFunc

The function called to react to a recipient that failed to acknowledge the message.

May be NULL if there is no action upon failure.

Definition at line 369 of file message.h.

Referenced by AppendPlayerData(), Send(), SendDisconnectMessage(), SendScoreUpdate(), SendSpawnRequest(), and ServiceGameConfig().

Uint8 MsgDescr_t::flags

Bit flags that indicate the message's state and affect how the message is handled.

The value is set to zero by MessageNew().

Definition at line 443 of file message.h.

Referenced by MessageNew().

Bool MsgDescr_t::inflight

True while this struct has valid data and is being used to send and track acknowledgments to a message.

Deprecated:

Definition at line 450 of file message.h.

Referenced by Send().

Uint16 MsgDescr_t::interval

The time in milliseconds between sends.

A default value is set by MessageNew() and it is doubled after nextSend is updated. The value may be changed before calling AddMessage() and by the message's constrFunc.

Definition at line 429 of file message.h.

Referenced by MessageNew(), Send(), and SendScoreUpdate().

Bool MsgDescr_t::mcast

Indicates that the message may be multicast to clients.

Warning:

This is not yet implemented.

Note:

Only valid for servers.

Definition at line 461 of file message.h.

Referenced by AddToConfigList().

Uint16 MsgDescr_t::msgId

The identifier for the message.

This identifier is sent with all copies of this message, including re-transmissions. The value is set by AddMessage().

Definition at line 423 of file message.h.

Referenced by AddMessage(), MsgFailDisconnect(), Send(), and ServiceMessages().

Uint32 MsgDescr_t::nextSend

The common game time when the message will be resent if not all recpients have acknowledged the message.

This value is used to sort messages in the inflightTime priority queue and is set at the end of the internal function Send().

Definition at line 417 of file message.h.

Referenced by Send(), and ServiceMessages().

Bool MsgDescr_t::noResend

When true, the message will not be resent.

This still allows the message to be acknowledged. The message will be canceled once its triesLeft count has dropped to zero, or the next retry after all destinations have acknowledged

Definition at line 468 of file message.h.

Referenced by Send().

Sint8 MsgDescr_t::triesLeft

The number of attempts remaining before giving up on this message.

When value reaches zero, the message remains in the system for one more interval to allow incomming acknowledgements more time. After the interval, notifictaion of any non-acknowledging destinations will be made through calling failFunc just before canceling the message.

Definition at line 437 of file message.h.

Referenced by AddMessage(), MessageNew(), Send(), and SendDisconnectMessage().

---

The documentation for this struct was generated from the following file:

• message.h

---