The return value specifies the number of bytes which have been put into the sequence. A difference between nBytesToRead and the return value indicates that EOF has been reached. This means that the method blocks until the specified number of bytes are available or the EOF is reached.

C++ only : Note that for unbridged (e.g., in-process) calls, using the same sequence for repetive readBytes()-calls can bear a performance advantage. The callee can put the data directly into the sequence so that no buffer reallocation is necessary. But this holds only when

1. neither caller nor callee keep a second reference to the same sequence.
2. the sequence is pre-allocated with the requested number of bytes.
3. the same sequence is reused ( simply preallocationg a new sequence for every call bears no advantage ).
4. the call is not bridged (e.g., betweeen different compilers or different processes ).

This method is very similar to the readBytes method, except that it has different blocking behaviour. The method blocks as long as at least 1 byte is available or EOF has been reached. EOF has only been reached, when the method returns 0 and the corresponding byte sequence is empty. Otherwise, after the call, aData contains the available, but no more than nMaxBytesToRead, bytes.

It is up to the implementation whether this method is blocking the thread or not.

Note: This method offers no information on whether the EOF has been reached.

Users must close the stream explicitly when no further reading should be done. (There may exist ring references to chained objects that can only be released during this call. Thus not calling this method would result in a leak of memory or external resources.)