You are here: SwitchKit® Development Environment Programmer’s Guide > 7 Message Functions > sk_rcvAndDispatch()
Description
The sk_rcvAndDispatch() is a replacement for sk_rcvMessage() that knows about handler functions. If you are using handler functions anywhere in your code, always call sk_rcvAndDispatch(), or the messages will not be dispatched correctly. When a message arrives, sk_rcvAndDispatch() determines whether there is any handler function associated with that message. If so, it calls the handler with the appropriate arguments.
sk_rcvAndDispatch() calls the handler function with any tag received and, if this message is an acknowledgment, it also passes in a pointer to the original MsgStruct that triggered this acknowledgment. Notice that all messages passed to the handler function are already unpacked. sk_rcvAndDispatch() returns whatever integer the handler function returns. Because the main sk_rcvAndDispatch() loop checks the return values, it is important that all of the handler functions return a valid integer. Any integer may be returned. Since many SwitchKit #defines use negative integers for many error codes, for example SK_LOST_LLC is -3, you should restrict yourself to returning non-negative integers only.
If there is no associated handler function, rcvAndDispatch returns SK_NOT_HANDLED, and its buffer and size are indicated, just as though sk_rcvMessage() had been called. The application module can then unpack and handle the undispatched message.
This message is also available as sk_rcvAndDispatchOnConnection() and skts_rcvAndDispatch().
int sk_rcvAndDispatch(char *aBuffer, int *aBufSize, double aTimeout, void **aTag);
int sk_rcvAndDispatchOnConnection(char *aBuffer, int *aBufSize, double aTimeout, void **aTag, int *aConIDPtr);
The function parameters are shown in the table below.
|
Argument |
Description |
|---|---|
|
aBuffer |
Pointer to a packed message. |
|
aBufSize |
Size of the packed message. |
|
aTimeout |
The maximum time the function should wait for a message before returning. The timeout value is a floating point number allow the application to specify a fractional portion to the timeout. For example, a timeout value of 1.5 seconds would be interpreted as a one and one-half second timeout. If no message arrives which is destined for the application in the specified time, the function should return SK_NO_MESSAGE. |
|
aTag |
The application-defined pointer that is only valid if the function returns SK_NOT_HANDLED. The value was set in either the original message send operation if the message is an acknowledgement or was set when the handler was defined if the message is switch-initiated. |
|
aConIDPtr |
This is used to identify from which LLC connection the message was received. |
Possible return values for this function:
|
SK_LOST_LLC |
This return value indicates that your application lost contact with the LLC. |
|
SK_NO_MESSAGE |
No message was received. The time-out expired before any messages (other then Poll messages) were received by the LLC. |
|
SK_BAD_MESSAGE |
An improperly formatted message was received. |
|
SK_NOT_HANDLED |
Message was not handled by handler function, no results available. |
|
SK_MSG_TOO_BIG |
This value is returned because the buffer for a message was too small, or because the message was larger than the limit (64 KB). The size integer value that you pass in is an input/output variable that indicates the size of the message that it unpacked, regardless of what you passed it. |
|
SK_INVALID_LINK |
A message was directed to a node that LLC was no longer connected to. This could happen when a connection to a node is unexpectedly severed. |
|
SK_FRAMING_FAILURE |
Message being sent to a node has a mismatched length between the actual length and the calculated length Reformat the message and send again. |
|
SK_SOCKET_WRITE_FAILURE |
LLC encountered an issue writing a message to a socket. This could be the result of a full socket (the distant end not reading from the socket appropriately) or a severed connection. |
|
SK_NODE_NOT_FOUND |
A message was directed to a node that LLC is not connected to. This could happen when an application specifies a node ID that has not been added to this configuration. |
Example
Code sample demonstrating the use of sk_rcvAndDispatch().
#define MSG_SIZE=1024
main(int argc, char *argv[])
{
char buf[MSG_SIZE];
int sz, ret;
void *dta;
char * AppName;
SKC_Message * msg;
...
/*Initialize connection to LLC with name*/
sk_initializeConnection(TANDEM_APP);
...
while (1) {
sz = MSG_SIZE;
/*Initialize maximum size of message to receive*/
if (debug > 5)
printf("\nWaiting for an Inseize at %s for 600 secs...\n", argv[1]);
/* Wait up to 600 seconds for a message. If a message is received that has handler function(s), rcvAndDispatch will automatically call the handler function(s) and return the result of the last handler function called. If there are no handler functions, then SK_NOT_HANDLED is returned, and we just print some info about the message.*/
ret = sk_rcvAndDispatch(buf, &sz, 600, &dta);
....
} /* (ret == SK_NOT_HANDLED) */
...
} /* while (1) */
} /* main */