int smdc_rx_data(struct smdc_data_parms *datap)
typedef struct smdc_data_parms {
tSMChannelId channel; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT done_length; /* out */
} SMDC_DATA_PARMS;
Attempt to read data from a channel whose input half has been configured for a data communications protocol. Less than the maximum will be read when either:
To permit maximum system throughput, this function refuses to read from a channel whose status has changed since it was last checked. This allows an application to avoid checking the status during bulk data transfer. The application only needs to check the status when a call to smdc_rx_data() returns with done_length equal to zero. This also ensures that status changes are reported at the point in the data at which they occurred, which may be important for some applications.
If an error is reported, the done_length field indicates the amount of data which was read before the error occurred.
Any amount of data (up to max_length) may be returned - even less than configured with the min_to_collect, parameter set with smdc_rx_control(), which only controls when the channel is declared ready. Once a channel is ready, it may remain so until all the data is read from it. This means that if the first read does not read all the data (i.e. the buffer supplied is too small), the next read will return immediately with more.
See also the document Prosody Data Communcations Protocols and Encodings for details of behaviour specific to individual protocols and encodings.
0 if call completed successfully, otherwise a standard error such as:
This function is part of the Prosody data communications API.