You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > InterAppMsg
Type
SwitchKit API message
Description
Use the SK_InterAppMsg message to send arbitrary information from one application to another. An acknowledgment is sent to the application that originally sent SK_InterAppMsg.
Important! You must call setDataSize before calling setData. If not, data will not be copied into the data field.
C developers must also copy the data manually. Otherwise, the data field will be truncated and the size set to 0 when the message is sent.
Sent by
Application
C Structure
typedef struct {
int Target;
union {
UBYTE UnAckedMsg;
UBYTE Type;
} union21 ;
unsigned short AckTimeout;
int Tag1;
int Tag2;
int Tag3;
int Tag4;
char AppGroupTarget[16];
unsigned short DataSize;
UBYTE Data[212];
} SK_InterAppMsg;
C Structure Response
typedef struct {
int Status;
UBYTE Byte1;
unsigned short Short1;
int Tag1;
int Tag2;
int Tag3;
int Tag4;
unsigned short DataSize;
UBYTE Data[228];
} SK_InterAppMsgAck;
C++ Class
class SKC_InterAppMsg : public SKC_ToolkitMessage {
public:
int getTarget() const;
void setTarget(int x);
UBYTE getUnAckedMsg() const;
void setUnAckedMsg(UBYTE x);
UBYTE getType() const;
void setType(UBYTE x);
unsigned short getAckTimeout() const;
void setAckTimeout(unsigned short x);
int getTag1() const;
void setTag1(int x);
int getTag2() const;
void setTag2(int x);
int getTag3() const;
void setTag3(int x);
int getTag4() const;
void setTag4(int x);
const char *getAppGroupTarget() const;
void setAppGroupTarget(const char *x);
unsigned short getDataSize() const;
void setDataSize(unsigned short x);
const UBYTE *getData() const;
UBYTE *getData();
void setData(UBYTE *x);
};
C++ Class Response
class SKC_InterAppMsgAck : public SKC_ToolkitAck {
public:
int getStatus() const;
void setStatus(int x);
UBYTE getByte1() const;
void setByte1(UBYTE x);
unsigned short getShort1() const;
void setShort1(unsigned short x);
int getTag1() const;
void setTag1(int x);
int getTag2() const;
void setTag2(int x);
int getTag3() const;
void setTag3(int x);
int getTag4() const;
void setTag4(int x);
unsigned short getDataSize() const;
void setDataSize(unsigned short x);
const UBYTE *getData() const;
UBYTE *getData();
void setData(UBYTE *x);
};
Argument Values
The following table shows the arguments that you can modify in InterAppMsg :
|
Argument |
Values and Description |
|---|---|
|
Target AppGroupTarget |
Write the name of the application that is to receive the message into the Target field. If you do not specify Target, AppGroupTarget must contain the text name of the application group that is to receive this message. If both Target and AppGroupTarget are specified, Target is used. |
|
AckTimeout |
Specifies the minimum time the LLC will wait for an acknowledgement to an InterAppMsg before it considers the InterAppMsg to have timed-out. This field only has meaning if the Type/UnAckedMsg field is set to SK_IAM_WITH_ACK. The actual time-out may be higher than the specified value because of the mechanism that LLC uses to keep track of outstanding requests. In any case, the time-out should occur within five seconds of the time-out value specified by the originator of the message. The default value for time-out, if not specified by the originator of the message, is 15 seconds. |
|
Tag 1 |
The Tag and Data fields are provided only for the convenience of the user. SwitchKit simply passes along these fields without any processing. You are responsible for assigning semantic meaning to these fields. The target application will receive a SK_InterAppMsg with all the fields filled in as they were filled in by the sending application. |
|
DataSize |
DataSize is used to specify how many bytes of data are in the Data array. The default amount of data that can be sent is 212 bytes. It can be increased up to 64KB. Refer to Send Messages Larger then Default. |
|
Type or UnAckedMsg |
Specifies the expected behavior for this message. If the sender of the message fails to set this field before sending the message, the default will be SK_IAM_WITH_NO_ACK. In cases where acknowledgement is not expected, the recipient cannot send an acknowledgement using the InterAppMsgAck. There are three values allowed for this field: SK_IAM_WITH_ACK - The sender of the InterAppMsg expects an acknowledgement from the recipient of the message. If the recipient fails to respond, LLC will generate an acknowledgement to the originator of the InterAppMsg with a status of SK_NO_ACK_FROM_SWITCH. If the recipient is not connected to the LLC, the LLC will generate an acknowledgement to the originator of the InterAppMsg with a status of SK_BAD_APP_NAME. In any case, the acknowledgement will come in the form of a message of type SK_InterAppMsgAck. See Acknowledgment. SK_IAM_BROADCAST - The sender of the InterAppMsg would like to send this message to all members of the AppGroupTarget specified in the InterAppMsg. There is no acknowledgement expected for this message. SK_IAM_WITH_NO_ACK - The sender of the InterAppMsg would like to send this message to its destination without expecting an acknowledgement. The fields, Type and UnAckedMsg, offer the same capability and therefore the field names are used interchangeably. Only one of the fields needs to be set. |
Send Messages Larger then Default
The following example shows how to send a message of 2000 bytes, if the structure SK_InterAppMsg is used.
char storage[2000];
SK_InterAppMsg *msg = (SK_InterAppMsg *)storage;
msg->Data[0] = ...
msg->Tags = ...
char buf[2000];
int sz=2000;
int stat = sk_packMessage((MsgStruct *)msg,buf,&sz);
if (stat != OK) {
return stat;
}
return sk_sendMessageWithHandler(buf,sz,tag,hf);
If the class SKC_InterAppMsg is being used, the following example will send a message of 2000 bytes.
SKC_InterAppMsg msg(2000);
msg.setData...
msg.setTags...
char buf[2000];
int sz=2000;
int stat = sk_packMessage(msg.getStructPtr(),buf,&sz);
if (stat != OK) {
return stat;
}
return sk_sendMessageWithHandler(buf,sz,tag,hf);
To acknowledge SK_InterAppMsg, the application must set the sequence number of the ACK to match the sequence number of the incoming message. For example:
int handleInterApp(SK_Event *evt, void *tag) {
MsgStruct *msg = evt->IncomingMsg;
SK_MSG_SWITCH(msg) {
CASE_InterAppMsg(iam) {
SK_InterAppMsgAck a;
sk_initMsg(&a,TAG_InterAppMsgAck);
sk_setSeqNum(&a,sk_getSeqNum(iam));
a.Status = 0x10;
sk_sendMsgStruct((MsgStruct *)&a, NULL, NULL);
break;
}
}SK_END_SWITCH;
return OK; //indicates that message was handled
}
If the C++ message classes are being used, the following example will send the ACK to an SKC_InterAppMsg.
int handleInterApp(SK_Event *evt, void *tag) {
SKC_Message *msg = evt->IncomingCMsg;
SKC_MSG_SWITCH(msg) {
CASEC_InterAppMsg(iam) {
SKC_InterAppMsg ack;
ack.setSeqNum(iam-getSeqNum())
ack.setStatus(0x10);
ack.setDataSize(0);
ack.send();
break;
}
}SKC_END_SWITCH;
return OK; //indicates that message was handled
}