agent.send(messageName, data)

Description

This method works in partnership with device.on() to allow messages and data to be sent from an imp-enabled device to its agent. For example, if the device calls:

agent.send("setspeed", data);

and the agent has already called:

device.on("setspeed", messageHandler);

then on receipt of the message setspeed from the device, the agent’s messageHandler() function will be called and be passed the contents of the variable data, which can be any serializable Squirrel table, array, safe string, integer, float or boolean. See Squirrel Data Serialization for Squirrel’s data serialization rules. The message handler function will always be called with exactly one parameter: the data passed to agent.send(). The data parameter in both messageHandler() and agent.send() is not optional. You must include such a parameter, even if you do not plan to use its argument in the handler.

The size of the message is limited: the agent will accept no request greater than 256KB in size — the maximum message size (message name plus payload) is slightly less than this. Low-memory devices such as the imp001 and imp002 are unlikely to hit that limit: they will succumb to an ‘Out of Memory’ error and restart long before the message being assembled for transmission reaches 256KB. This is much less likely to be an issue for the imp003, imp004m and imp005, which feature more RAM than earlier imps. However, it is always better to send many small messages than a few large ones.

Like all other methods that send data to the server, agent.send() returns a 0 on success or one of the following Send Error Codes:

Error Code Constant	Value	Description
SEND_ERROR_NOT_CONNECTED	1	There is no connection to the server
SEND_ERROR_TIMEOUT	2	The timeout expired before all the data was sent to the server
SEND_ERROR_DISCONNECTED	3	The connection was disconnected before all data was sent to the server
SEND_ERROR_WOULDBLOCK	4	The data to be sent would not fit in the send buffer

The values assigned to the constants may change in a future impOS™ release.

If the device is disconnected when agent.send() is called, it will automatically attempt to reconnect to the server but only when SUSPEND_ON_ERROR has been selected as the imp’s timeout policy. This is the default setting. If the policy has been set to RETURN_ON_ERROR, the current network interface will not be re-enabled until your code calls server.connect(). Messages posted by agent.send() between the disconnection and any subsequent re-connection will be lost, and the method will return the code SEND_ERROR_NOT_CONNECTED.

If you are using the RETURN_ON_ERROR policy and the server is connected, agent.send() will block for the duration specified in the timeout parameter of server.setsendtimeoutpolicy() if the imp’s transmit buffers are full when the call is made. The block occurs because the call continues to attempt to place the data to be sent into the transmit buffer. If the timeout expires, ie. the buffer has not yet emptied sufficiently to take the data, agent.send() will return SEND_ERROR_TIMEOUT and execution proceeds. A disconnection is registered, and further calls to agent.send() return immediately (no data is sent).

Under normal conditions and with server.setsendtimeoutpolicy()’s waitFor parameter set to WAIT_TIL_SENT, agent.send() will appear asynchronous: the call returns when the data enters the buffer and this occurs very quickly. However, it’s important to remember that agent.send() is not asynchronous, and will block until the data is written into the buffer or the timeout period elapses.

• For more information on agent-device and device-agent messaging, please see Effective Internet-agent-device Communication.

• For information on dealing with ‘no handler for device.send()’ errors, please see this troubleshooting note.

• For sample code that can be used to manage messaging between agent and device, please see the imp API Cookbook recipe Agent-Device Communications.