You are here: SwitchKit® Development Environment Programmer’s Guide > 7 Message Functions > sk_rcvMessage()
Description
The sk_rcvMessage() function tries to receive a message from the switch. The buffer argument must be at least 256 bytes long. The buf argument gets filled in with the message, and the size argument is set to its size. The timeout argument specifies how long to wait for a message, in seconds. A value less than 0 means to wait indefinitely. A value of 0 specifies a polling behavior, returning immediately whether or not there is a message. A value greater than 0 will wait for a maximum of that many seconds, or until a message arrives. The actual accuracy of the timeout timer varies across machines.
Important! Setting your timeout argument to a value of zero (0) or smaller might cause a significant increase in CPU usage.
The sk_rcvMessage() function also looks for any tag data. If the received message is an acknowledgment to a previously sent message, then *dta is set to whatever tag was sent with the original message. If no tag was sent, or if the message was a switch-originated message instead of an acknowledgment, then *dta is assigned 0.
This message is also available as sk_rcvMessageOnConnection().
int sk_rcvMessage(char *aBuffer, int *aBufSize, double aTimeout, void **aDataPtr);
int sk_rcvMessageOnConnection(char *aBuffer, int *aBufSize, double aTimeout, void **aDataPtr, int *aConID);
The function parameters are shown in the next table.
|
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. |
|
aDataPtr |
This argument is not currently used. |
|
aConID |
aConID is a connection identifier specified at connection creation time and used to indicate which LLC an application wishes to communicate with. |
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 a message was received or the LLC received a poll message from the switch. |
|
SK_BAD_MESSAGE |
An improperly formatted message was received |
|
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. |