This function retreives a line of text from the connection's incoming buffer. A line of text is a sequence of 8-bit characters terminated by an LF character.
rrid_t rascal_reads( rrid_t conn, char *buffer, unsigned int *buffer_size, int flags OPTIONAL );
Parameters.
connHandle of the connection that the data must be retreived from. If the handle does not correspond to a valid stream oriented connection, an error is reported. This function can not be used on datagram connections.
buffer, buffer_sizeLocation and dimension of the buffer that receives the a NUL-terminated C-string. On success, buffer_size is updated with the number of actually copied bytes, excluding the (trailing) NUL character. (That is, the maximum possible value of buffer_size on return is the initial value minus one.)
flagsA bit mask that modifies the behaviour of the function. By default (when zero is used for flags), the function does the following:
A combination of the following flags can be used to modify this behaviour:
Table F.2. rascal_reads flags
| Value | Meaning |
|---|---|
RRF_UNTRIMMED | Tells the function to include trailing CR and LF characters in the destination buffer. |
RRF_PEEK | Prevents the function from removing the data from the connection's incoming buffer; the data is copied to the specified destination and remains in the buffer. |
RRF_MEASURE | Prevents the function from extracting anything; instead, size is updated with the length of the buffer that would be enough to receive the whole string, without truncation. Other flags that modify the copied string (such as RRF_UNTRIMMED) are taken into consideration. |
Return value.
If everything goes well, the function returns REC_SUCCESS. If the connection's incoming buffer did not contain an LF character, the function returns REC_NO_DATA. Descriptions of other error messages can be retreived using rascal_get_errmsg.
Example.
char buffer[1024];
unsigned int size = sizeof(buffer);
while (rascal_isok(rascal_reads(rid, buffer, &size))) {
printf(">> %s\n", buffer);
size = sizeof(buffer);
}