Message Macros for C Programmers

Description

The following macros are provided to assist in setting up the message. Some macros have a threadsafe version which is indicated by the skts prefix. Macros do not have return values; they evaluate. The listed parameters are to show expected types.

sk_initMsg

This macro initializes the structure by zeroing the sequence number and size, and by setting the tag. This macro must be called on every message structure.

Syntax

void sk_initMsg(MsgStruct *m, int tag);

Threadsafe Syntax

void skts_initMsg(MsgStruct *m, int tag);

Proper Initialization

If the application should fail to call sk_initMsg() before sending the message, the following text will appear on the console and in the application's maintenance log:

"**Error:Aug 12 2003 09:30:30: Received message with unknown engine type205 - is the sender of this message incorrectly using a pre-3.0 version of SwitchKit? This version of SwitchKit will not work with any pre-3.0versions."

This message incorrectly identifies the source of the problem but indicates that the message was not properly initialized.

sk_setMsgSize

This macro sets the size of the message. In general, this macro should not be called. For all fixed-size messages, and almost all variably-sized messages, SwitchKit computes the size of the message automatically. If you don't set the size, and SwitchKit cannot compute it, you get this error code returned: SK_NO_MSG_SIZE. In this case, the size should be set to the length field that would appear in the EXS message, as described by the API Reference. (Note that the actual value set in the MsgStruct.Size field will not necessarily be this exact value.)

Syntax

void sk_setMsgSize(MsgStruct *m, aBufSize);

Threadsafe Syntax

XBYTE skts_setMsgSize(MsgStruct *m);

sk_getMsgSize

This macro retrieves the size of the message that was previously set via sk_setMsgSize. This function will not cause SwitchKit to recompute the size of the message and therefore should only be called if you are calling sk_setMsgSize(). See sk_setMsgSize() for more details.

Syntax

XBYTE sk_getMsgSize(MsgStruct *m);

Threadsafe Syntax

XBYTE skts_getMsgSize(MsgStruct *m);

sk_setRange

This macro sets the range of spans and channels for a ChanRangeMsgStruct message. The macro is equivalent to:

crmsg.StartSpan = startSpan;

crmsg.StartChan = startChan;

crmsg.EndSpan = endSpan;

crmsg.EndChan = endChan;

Syntax

void sk_setRange (ChanRangeMsgStruct* crMsg, int startSpan, int startChan, int endSpan, int endChan);

Threadsafe Syntax

void skts_setRange (ChanRangeMsgStruct* crMsg, int startSpan, int startChan, int endSpan, int endChan);

sk_getMsgType

This macro evaluates the following cases:

• SK_TYPE_INBOUND: for messages arriving from the switch.

• SK_TYPE_OUTBOUND: for messages destined for the switch.

• SK_TYPE_TOOLKIT: for SwitchKit-specific messages, for example Add LLCNode.

• SK_TYPE_ADMIN: for SwitchKit administrative messages, for example AssociateChannelGroup.

• SK_TYPE_DUMMY: for SwitchManager-specific messages, for example PPLTool, AllInService.

Syntax

int sk_getMsgType(MsgStruct *m);

Threadsafe Syntax

int skts_getMsgType(MsgStruct *m);

isInboundMsg

This macro evaluates TRUE if m points to an inbound message.

Syntax

bool isInboundMsg(MsgStruct *m);

isOutboundMsg

This macro evaluates TRUE if m points to an outbound message.

Syntax

bool isOutboundMsg(MsgStruct *m);

isToolkit

This macro evaluates TRUE if m points to a toolkit message.

Syntax

bool isToolkit(MsgStruct *m);

sk_getXLTag

This macro evaluates to the UBYTE message tag as received by the LLC from the switch.

Syntax

UBYTE sk_getXLTag(MsgStruct *m);

Threadsafe Syntax

UBYTE skts_getXLTag(MsgStruct *m);

sk_getMsgTag

This macro evaluates to the SK tag and will be offset by 10000 if m points to an acknowledgement.

Syntax

int sk_getMsgTag(MsgStruct *m);

Threadsafe Syntax

int skts_getMsgTag(MsgStruct *m);

sk_getSeqNum

This macro evaluates to the sequence number for the message m is pointing to.

Syntax

XBYTE sk_getSegNum(MsgStruct *m);

Threadsafe Syntax

XBYTE skts_getSegNum(MsgStruct *m);

sk_setSeqNum

This macro is a convienience macro that sets the sequence number of m to seqNum.

Syntax

void sk_setSeqNum(MsgStruct *m, XBYTE seqNum);

Threadsafe Syntax

void skts_setSeqNum(MsgStruct *m, XBYTE seqNum);

sk_is_positive_ack

This macro evaluates to TRUE if ack is an inbound message and
ack->Status == 0x10.

Syntax

bool sk_is_positive_ack(MsgStruct *m);