@@ -106,10 +106,63 @@
* The buffer must be exactly this big!
*/
- (void)readIntoBuffer: (void*)buffer
exactLength: (size_t)length;
+/**
+ * \brief Asyncronously reads at most size bytes from the stream into a
+ * buffer.
+ *
+ * On network streams, this might read less than the specified number of bytes.
+ * If you want to read exactly the specified number of bytes, use
+ * asyncReadIntoBuffer:exactLength:block:. Note that a read can even return 0
+ * bytes - this does not necessarily mean that the stream ended, so you still
+ * need to check isAtEndOfStream.
+ *
+ * \param buffer The buffer into which the data is read.
+ * The buffer must not be free'd before the async read completed!
+ * \param length The length of the data that should be read at most.
+ * The buffer must be at least this big!
+ * \param target The target on which the selector should be called when the
+ * data has been received. If the method returns YES, it will be
+ * called again with the same buffer and maximum length when more
+ * data has been received. If you want the next method in the
+ * queue to handle the data received next, you need to return NO
+ * from the method.
+ * \param selector The selector to call on the target. The signature must be
+ * BOOL (OFStream *stream, void *buffer, size_t size).
+ */
+- (void)asyncReadIntoBuffer: (void*)buffer
+ length: (size_t)length
+ target: (id)target
+ selector: (SEL)selector;
+
+/**
+ * \brief Asyncronously reads exactly the specified length bytes from the
+ * stream into a buffer.
+ *
+ * Unlike asyncReadIntoBuffer:length:block, this method does not call the
+ * method when less than the specified length has been read - instead, it waits
+ * until it got exactly the specified length or the stream has ended.
+ *
+ * \param buffer The buffer into which the data is read
+ * \param length The length of the data that should be read.
+ * The buffer must be exactly this big!
+ * \param target The target on which the selector should be called when the
+ * data has been received. If the method returns YES, it will be
+ * called again with the same buffer and exact length when more
+ * data has been received. If you want the next method in the
+ * queue to handle the data received next, you need to return NO
+ * from the method.
+ * \param selector The selector to call on the target. The signature must be
+ * BOOL (OFStream *stream, void *buffer, size_t size).
+ */
+ - (void)asyncReadIntoBuffer: (void*)buffer
+ exactLength: (size_t)length
+ target: (id)target
+ selector: (SEL)selector;
+
#ifdef OF_HAVE_BLOCKS
/**
* \brief Asyncronously reads at most size bytes from the stream into a
* buffer.
*
@@ -499,10 +552,42 @@
* \return The line that was read, autoreleased, or nil if the end of the
* stream has been reached.
*/
- (OFString*)readLineWithEncoding: (of_string_encoding_t)encoding;
+/**
+ * \brief Asyncronously reads with the specified encoding until a newline, \\0
+ * or end of stream occurs.
+ *
+ * \param target The target on which to call the selector when the data has
+ * been received. If the method returns YES, it will be called
+ * again when the next line has been received. If you want the
+ * next method in the queue to handle the next line, you need to
+ * return NO from the method
+ * \param selector The selector to call on the target. The signature must be
+ * BOOL (OFStream *stream, OFString *line).
+ */
+- (void)asyncReadLineWithTarget: (id)target
+ selector: (SEL)selector;
+
+/**
+ * \brief Asyncronously reads with the specified encoding until a newline, \\0
+ * or end of stream occurs.
+ *
+ * \param encoding The encoding used by the stream
+ * \param target The target on which to call the selector when the data has
+ * been received. If the method returns YES, it will be called
+ * again when the next line has been received. If you want the
+ * next method in the queue to handle the next line, you need to
+ * return NO from the method
+ * \param selector The selector to call on the target. The signature must be
+ * BOOL (OFStream *stream, OFString *line).
+ */
+- (void)asyncReadLineWithEncoding: (of_string_encoding_t)encoding
+ target: (id)target
+ selector: (SEL)selector;
+
#ifdef OF_HAVE_BLOCKS
/**
* \brief Asyncronously reads until a newline, \\0 or end of stream occurs.
*
* \param block The block to call when the data has been received.
@@ -919,11 +1004,10 @@
* \param length The length of the buffer
* \return The number of bytes read
*/
- (size_t)lowlevelReadIntoBuffer: (void*)buffer
length: (size_t)length;
-
/**
* \brief Performs a lowlevel write.
*
* \warning Do not call this directly!