data$, count, done = ReceiveData(id, mode, ...)
data$, count, done = ReceiveData(id, #RECEIVEBYTES, maxbytes[, callback,
                                     userdata])
data$, count, done = ReceiveData(id, #RECEIVEALL[, untilterm, callback,
                                     userdata])
data$, count, done = ReceiveData(id, #RECEIVELINE[, callback, userdata])

The second argument specifies how much data you want to receive from the sender with this call. Currently, the following modes are supported:

#RECEIVEBYTES:

Receive all available data but not more than the specified number of bytes. If you use this mode, you need to pass the maximum number of bytes you wish to receive in the third argument. ReceiveData() will then never obtain more bytes than you specified. However, it can happen that less bytes are returned in case there is not enough data available from the sender. You can find out the number of bytes obtained by looking at the second return value.

#RECEIVEALL:

Receive all data currently available. If the optional argument untilterm is set to True, ReceiveData() will not return before the sender terminates the connection, thus allowing you to receive all data a sender has to offer using just a single call. If untilterm is set to False, ReceiveData() will only return the data that is currently available. It will not wait for additional data to arrive, but it will tell you if there is more data to be retrieved (in the third return value). The default setting for untilterm is True which means that ReceiveData() will read data until the sender terminates the connection.

#RECEIVELINE:

Receive a single line of text from the sender. This mode must only be used when working with non binary data. The carriage return and the newline characters will not be included in the returned string. They are read from the network buffer but they will not be returned by ReceiveData() if you use #RECEIVELINE.

ReceiveData() returns three values: The first return value is a string that contains the data that was received from the network or an empty string if you use a callback to handle the data or no data could be read. Please note that although the data read is returned as a string, it is not limited to text only. It can also contain binary data because Hollywood strings can handle control characters and the NULL character just fine. The second return value specifies how many bytes could be read from the network buffer. If this is 0, then there is currently no data available. The third return value is only useful if you use #RECEIVEALL transfer mode with untilterm set to False. In that case, the third return value tells you if more data is available in the network buffer. If there is more data to be read, then done is False, otherwise it will be True.

Starting with Hollywood 6.0 there is an optional callback parameter that allows you to pass a callback function that should receive the data read from the server. This can be useful if you need to stream large amounts of data that cannot be efficiently stored inside a Hollywood string. The callback function could simply write the data it receives to a file, for example. Note that if you specify a callback function, ReceiveData() will always return an empty string. The callback function you specify will be called with a single argument: A table that contains more information. Here is an overview of the table fields that will be initialized before ReceiveData() runs your callback function:

Action:

#RECEIVEDATA_PACKET

Data:

The data that has been received from the server. Note that this can contain binary data.

Count:

Contains the number of bytes in Data.

Total:

Contains the total number of bytes already received.

UserData:

Contains the value you passed in the userdata argument.

The callback function of type #RECEIVEDATA_PACKET should normally return False. If it returns True, ReceiveData() will abort its operations and return immediately.

Finally, there is another optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

id

identifier of the sender

mode

the desired transfer mode; see above for a list of currently supported transfer modes

...

further arguments depend on the specified transfer mode; see above

data$

the data that was read from the network buffer or an empty string if a callback is specified

count

number of bytes successfully transmitted

done

whether or not there is more data in the network buffer (only when #RECEIVEALL is used together with untilterm set to False)