ObjFW  Diff

#import "OFObject.h"
#import "OFString.h"
#ifdef OF_HAVE_SOCKETS
# import "OFKernelEventObserver.h"
#endif

OF_ASSUME_NONNULL_BEGIN

/*! @file */

@class OFStream;
@class OFDataArray;
@class OFException;

#if defined(OF_HAVE_SOCKETS) && defined(OF_HAVE_BLOCKS)
/*!
 * @brief A block which is called when data was read from the stream.
 *
 * @param stream The stream on which data was read
 * @param buffer A buffer with the data that has been read
 * @param length The length of the data that has been read
 * @param exception An exception which occurred while reading or nil on success
 * @return A bool whether the same block should be used for the next read
 */
typedef bool (^of_stream_async_read_block_t)(OFStream *stream, void *buffer,
    size_t length, __nullable OFException *exception);

/*!
 * @brief A block which is called when a line was read from the stream.
 *
 * @param stream The stream on which a line was read
 * @param line The line which has been read or nil when the end of stream
 *	       occurred
 * @param exception An exception which occurred while reading or nil on success
 * @return A bool whether the same block should be used for the next read
 */
typedef bool (^of_stream_async_read_line_block_t)(OFStream *stream,
    __nullable OFString *line, __nullable OFException *exception);
#endif

/*!
 * @class OFStream OFStream.h ObjFW/OFStream.h
 *
 * @brief A base class for different types of streams.
 *

 *		 data has been received. If you want the next method in the
 *		 queue to handle the data received next, you need to return
 *		 false from the method.
 * @param selector The selector to call on the target. The signature must be
 *		   `bool (OFStream *stream, void *buffer, size_t size,
 *		   OFException *exception)`.
 */
- (void)asyncReadIntoBuffer: (void*)buffer
		exactLength: (size_t)length
		     target: (id)target
		   selector: (SEL)selector;

# ifdef OF_HAVE_BLOCKS
/*!
 * @brief Asyncronously reads *at most* ref size bytes from the stream into a
 *	  buffer.
 *
 * On network streams, this might read less than the specified number of bytes.

/*!
 * @brief Reads until a newline, \\0 or end of stream occurs.
 *
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readLine;

/*!
 * @brief Reads with the specified encoding until a newline, \\0 or end of
 *	  stream occurs.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readLineWithEncoding: (of_string_encoding_t)encoding;

#ifdef OF_HAVE_SOCKETS
/*!
 * @brief Asyncronously reads until a newline, \\0, end of stream or an
 *	  exception occurs.
 *
 * @note The stream must implement @ref fileDescriptorForReading and return a

/*!
 * @brief Tries to read a line from the stream (see readLine) and returns nil if
 *	  no complete line has been received yet.
 *
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (nullable OFString*)tryReadLine;

/*!
 * @brief Tries to read a line from the stream with the specified encoding (see
 *	  @ref readLineWithEncoding:) and returns nil if no complete line has
 *	  been received yet.
 *
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the line is not
 *	   complete yet
 */
- (nullable OFString*)tryReadLineWithEncoding: (of_string_encoding_t)encoding;

/*!
 * @brief Reads until the specified string or \\0 is found or the end of stream
 *	  occurs.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Reads until the specified string or \\0 is found or the end of stream
 *	  occurs.
 *
 * @param delimiter The delimiter
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)readTillDelimiter: (OFString*)delimiter
			       encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Tries to reads until the specified string or \\0 is found or the end
 *	  of stream (see @ref readTillDelimiter:) and returns nil if not enough
 *	  data has been received yet.
 *
 * @param delimiter The delimiter
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)tryReadTillDelimiter: (OFString*)delimiter;

/*!
 * @brief Tries to read until the specified string or \\0 is found or the end
 *	  of stream occurs (see @ref readTillDelimiter:encoding:) and
 *	  returns nil if not enough data has been received yet.
 *
 * @param delimiter The delimiter
 * @param encoding The encoding used by the stream
 * @return The line that was read, autoreleased, or nil if the end of the
 *	   stream has been reached.
 */
- (nullable OFString*)tryReadTillDelimiter: (OFString*)delimiter
				  encoding: (of_string_encoding_t)encoding;

/*!
 * @brief Returns a boolen whether writes are buffered.
 *
 * @return A boolean whether writes are buffered
 */
- (bool)isWriteBuffered;

 * Override this method with your actual end of stream checking implementation
 * when subclassing!
 *
 * @return Whether the lowlevel is at the end of the stream
 */
- (bool)lowlevelIsAtEndOfStream;
@end

OF_ASSUME_NONNULL_END