Message Structure Macros

Description

To send a message, you must first create a message structure macro.

There are two ways of creating message structure macros. You can choose to use predefined macros included in SwitchKit, or you can write you own macros. Either way, you must use a switch statement to go through the message.

Switch Statement with Predefined Macros

The received message structure includes information describing what kind of message it is. You handle this information with the SK_MSG_SWITCH macros. These macros mimic a switch statement and allow different branches of code to be executed, depending on the kind of message. Within the branch, a cast is performed for you automatically, allowing you to operate on a variable that has the correct type. The switch statement must end with SK_END_SWITCH.

Example for C with Predefined Macros

MsgStruct *msg

SK_MSG_SWITCH(msg)

{

CASE_ConnectAck(ca)

return processStatus(ca->Status);

CASE_ChannelReleased(cr)

{

CleanUpChan(cr->Span, cr->Channel);

break;

}

CASE_default

{

/*Unexpected msg!*/

break;

}

} SK_END_SWITCH

In the SK_MSG_SWITCH statement, "break" can be used normally, and the lack of a break statement causes execution to fall through to the next branch, just as it would in a normal switch statement. However, the default branch must be labeled with CASE_default, as in the above example. The other important syntax difference from a normal switch statement is the lack of colons after the case label. The macro inserts the colons for you.

In the body of the first two cases, the programmer has referenced structure elements, Status, Span, and Channel that are only accessed through a correctly-cast MsgStruct. For example, in the first case ca has been defined by the CASE_ConnectAck macro to be a pointer to a ConnectAck structure, and is initialized with msg.

You can find the definitions of the marcros in the included file API_Funcs.h. Those macros are defined in terms of more primitive operations, which you can use instead of an SK_MSG_SWITCH statement.

Switch Statement without Predefined Macros

These are the steps to translate the example to straight C code.

1. Copy the message structure.

2. Do the switch statement on the tag of the message.

3. For the first case, use TAG_ConnectAck for the tag of the acknowledgment to the connect message. There is no XL_ConnectAck structure because its acknowledgement is generic, so the message is cast to an XL_AcknowledgeMessage. It is then stored in the ca variable, which is used in the body of the case clause.

4. Use the next case for the XL_ChannelReleased message. This time, the message is cast to a structure that is put in cr.

5. CASE_default is not used for anything in this example.

Example for C without Predefined macros

SK_Message *sk_saved_msg = msg;

switch(sk_saved_msg -> getMsgTag())

{

case(TAG_ConnectAck):

{

XL_AcknowledgeMessage *ca =
(XL_AcknowledgeMessage *)sk_saved_msg;

return processStatus(ca->Status);

}

case(TAG_ChannelReleased):

{

XL_ChannelReleased *cr =

(XL_ChannelReleased *)sk_saved_msg;

cleanUpChan(cr->Span, cr->Channel);

break;

}

default:

break;

}