@@ -1,7 +1,7 @@ /* - * Copyright (c) 2008-2021 Jonathan Schleifer + * Copyright (c) 2008-2022 Jonathan Schleifer * * All rights reserved. * * This file is part of ObjFW. It may be distributed under the terms of the * Q Public License 1.0, which can be found in the file LICENSE.QPL included in @@ -63,35 +63,33 @@ /** * @brief A block which is called when data was written asynchronously to a * stream. * - * @param data The data which was written to the stream * @param bytesWritten The number of bytes which have been written. This * matches the length of the specified data on the * asynchronous write if no exception was encountered. * @param exception An exception which occurred while writing or `nil` on * success * @return The data to repeat the write with or nil if it should not repeat */ -typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(OFData *_Nonnull data, - size_t bytesWritten, id _Nullable exception); +typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(size_t bytesWritten, + id _Nullable exception); /** * @brief A block which is called when a string was written asynchronously to a * stream. * - * @param string The string which was written to the stream * @param bytesWritten The number of bytes which have been written. This * matches the length of the specified data on the * asynchronous write if no exception was encountered. * @param exception An exception which occurred while writing or `nil` on * success * @return The string to repeat the write with or nil if it should not repeat */ typedef OFString *_Nullable (^OFStreamAsyncWriteStringBlock)( - OFString *_Nonnull string, size_t bytesWritten, id _Nullable exception); + size_t bytesWritten, id _Nullable exception); #endif /** * @protocol OFStreamDelegate OFStream.h ObjFW/OFStream.h * @@ -205,11 +203,11 @@ @property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream; /** * @brief Whether writes are buffered. */ -@property (nonatomic, nonatomic) bool buffersWrites; +@property (nonatomic) bool buffersWrites; /** * @brief Whether data is present in the internal read buffer. */ @property (readonly, nonatomic) bool hasDataInReadBuffer; @@ -526,83 +524,10 @@ * * @return A double from the stream in the native endianess */ - (double)readBigEndianDouble; -/** - * @brief Reads the specified number of uint16_ts from the stream which are - * encoded in big endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint16_ts - * @param count The number of uint16_ts to read - * @return The number of bytes read - */ -- (size_t)readBigEndianInt16sIntoBuffer: (uint16_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of uint32_ts from the stream which are - * encoded in big endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint32_ts - * @param count The number of uint32_ts to read - * @return The number of bytes read - */ -- (size_t)readBigEndianInt32sIntoBuffer: (uint32_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of uint64_ts from the stream which are - * encoded in big endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint64_ts - * @param count The number of uint64_ts to read - * @return The number of bytes read - */ -- (size_t)readBigEndianInt64sIntoBuffer: (uint64_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of floats from the stream which are encoded - * in big endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * floats - * @param count The number of floats to read - * @return The number of bytes read - */ -- (size_t)readBigEndianFloatsIntoBuffer: (float *)buffer count: (size_t)count; - -/** - * @brief Reads the specified number of doubles from the stream which are - * encoded in big endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * doubles - * @param count The number of doubles to read - * @return The number of bytes read - */ -- (size_t)readBigEndianDoublesIntoBuffer: (double *)buffer count: (size_t)count; - /** * @brief Reads a uint16_t from the stream which is encoded in little endian. * * @warning Only call this when you know that enough data is available! * Otherwise you will get an exception! @@ -649,85 +574,10 @@ * * @return A double from the stream in the native endianess */ - (double)readLittleEndianDouble; -/** - * @brief Reads the specified number of uint16_ts from the stream which are - * encoded in little endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint16_ts - * @param count The number of uint16_ts to read - * @return The number of bytes read - */ -- (size_t)readLittleEndianInt16sIntoBuffer: (uint16_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of uint32_ts from the stream which are - * encoded in little endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint32_ts - * @param count The number of uint32_ts to read - * @return The number of bytes read - */ -- (size_t)readLittleEndianInt32sIntoBuffer: (uint32_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of uint64_ts from the stream which are - * encoded in little endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * uint64_ts - * @param count The number of uint64_ts to read - * @return The number of bytes read - */ -- (size_t)readLittleEndianInt64sIntoBuffer: (uint64_t *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of floats from the stream which are - * encoded in little endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * floats - * @param count The number of floats to read - * @return The number of bytes read - */ -- (size_t)readLittleEndianFloatsIntoBuffer: (float *)buffer - count: (size_t)count; - -/** - * @brief Reads the specified number of doubles from the stream which are - * encoded in little endian. - * - * @warning Only call this when you know that enough data is available! - * Otherwise you will get an exception! - * - * @param buffer A buffer of sufficient size to store the specified number of - * doubles - * @param count The number of doubles to read - * @return The number of bytes read - */ -- (size_t)readLittleEndianDoublesIntoBuffer: (double *)buffer - count: (size_t)count; - /** * @brief Reads the specified number of items with an item size of 1 from the * stream and returns them as OFData. * * @warning Only call this when you know that enough data is available! @@ -965,22 +815,31 @@ - (nullable OFString *)tryReadTillDelimiter: (OFString *)delimiter encoding: (OFStringEncoding)encoding; /** * @brief Writes everything in the write buffer to the stream. + * + * @return Whether the write buffer was flushed entirely. On non-blocking + * sockets, this can return `false` if flushing the write buffer in its + * entirety would block. */ -- (void)flushWriteBuffer; +- (bool)flushWriteBuffer; /** * @brief Writes from a buffer into the stream. + * + * In non-blocking mode, if less than the specified length could be written, an + * @ref OFWriteFailedException is thrown with @ref OFWriteFailedException#errNo + * being set to `EWOULDBLOCK` or `EAGAIN` (you need to check for both, as they + * are not the same on some systems) and + * @ref OFWriteFailedException#bytesWritten being set to the number of bytes + * that were written, if any. * * @param buffer The buffer from which the data is written into the stream * @param length The length of the data that should be written - * @return The number of bytes written. This can only differ from the specified - * length in non-blocking mode. */ -- (size_t)writeBuffer: (const void *)buffer length: (size_t)length; +- (void)writeBuffer: (const void *)buffer length: (size_t)length; #ifdef OF_HAVE_SOCKETS /** * @brief Asynchronously writes data into the stream. * @@ -1129,265 +988,181 @@ #endif /** * @brief Writes a uint8_t into the stream. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param int8 A uint8_t */ - (void)writeInt8: (uint8_t)int8; /** * @brief Writes a uint16_t into the stream, encoded in big endian. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param int16 A uint16_t */ - (void)writeBigEndianInt16: (uint16_t)int16; /** * @brief Writes a uint32_t into the stream, encoded in big endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param int32 A uint32_t */ - (void)writeBigEndianInt32: (uint32_t)int32; /** * @brief Writes a uint64_t into the stream, encoded in big endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param int64 A uint64_t */ - (void)writeBigEndianInt64: (uint64_t)int64; /** * @brief Writes a float into the stream, encoded in big endian. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param float_ A float */ - (void)writeBigEndianFloat: (float)float_; /** * @brief Writes a double into the stream, encoded in big endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param double_ A double */ - (void)writeBigEndianDouble: (double)double_; -/** - * @brief Writes the specified number of uint16_ts into the stream, encoded in - * big endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of uint16_ts to write - * @return The number of bytes written to the stream - */ -- (size_t)writeBigEndianInt16s: (const uint16_t *)buffer count: (size_t)count; - -/** - * @brief Writes the specified number of uint32_ts into the stream, encoded in - * big endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of uint32_ts to write - * @return The number of bytes written to the stream - */ -- (size_t)writeBigEndianInt32s: (const uint32_t *)buffer count: (size_t)count; - -/** - * @brief Writes the specified number of uint64_ts into the stream, encoded in - * big endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of uint64_ts to write - * @return The number of bytes written to the stream - */ -- (size_t)writeBigEndianInt64s: (const uint64_t *)buffer count: (size_t)count; - -/** - * @brief Writes the specified number of floats into the stream, encoded in big - * endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of floats to write - * @return The number of bytes written to the stream - */ -- (size_t)writeBigEndianFloats: (const float *)buffer count: (size_t)count; - -/** - * @brief Writes the specified number of doubles into the stream, encoded in - * big endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of doubles to write - * @return The number of bytes written to the stream - */ -- (size_t)writeBigEndianDoubles: (const double *)buffer count: (size_t)count; - /** * @brief Writes a uint16_t into the stream, encoded in little endian. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param int16 A uint16_t */ - (void)writeLittleEndianInt16: (uint16_t)int16; /** * @brief Writes a uint32_t into the stream, encoded in little endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param int32 A uint32_t */ - (void)writeLittleEndianInt32: (uint32_t)int32; /** * @brief Writes a uint64_t into the stream, encoded in little endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param int64 A uint64_t */ - (void)writeLittleEndianInt64: (uint64_t)int64; /** * @brief Writes a float into the stream, encoded in little endian. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param float_ A float */ - (void)writeLittleEndianFloat: (float)float_; /** * @brief Writes a double into the stream, encoded in little endian. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param double_ A double */ - (void)writeLittleEndianDouble: (double)double_; -/** - * @brief Writes the specified number of uint16_ts into the stream, encoded in - * little endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of uint16_ts to write - * @return The number of bytes written to the stream - */ -- (size_t)writeLittleEndianInt16s: (const uint16_t *)buffer - count: (size_t)count; - -/** - * @brief Writes the specified number of uint32_ts into the stream, encoded in - * little endian. - * - * @param count The number of uint32_ts to write - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @return The number of bytes written to the stream - */ -- (size_t)writeLittleEndianInt32s: (const uint32_t *)buffer - count: (size_t)count; - -/** - * @brief Writes the specified number of uint64_ts into the stream, encoded in - * little endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of uint64_ts to write - * @return The number of bytes written to the stream - */ -- (size_t)writeLittleEndianInt64s: (const uint64_t *)buffer - count: (size_t)count; - -/** - * @brief Writes the specified number of floats into the stream, encoded in - * little endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of floats to write - * @return The number of bytes written to the stream - */ -- (size_t)writeLittleEndianFloats: (const float *)buffer count: (size_t)count; - -/** - * @brief Writes the specified number of doubles into the stream, encoded in - * little endian. - * - * @param buffer The buffer from which the data is written to the stream after - * it has been byte swapped if necessary - * @param count The number of doubles to write - * @return The number of bytes written to the stream - */ -- (size_t)writeLittleEndianDoubles: (const double *)buffer count: (size_t)count; - /** * @brief Writes OFData into the stream. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param data The OFData to write into the stream - * @return The number of bytes written */ -- (size_t)writeData: (OFData *)data; +- (void)writeData: (OFData *)data; /** * @brief Writes a string into the stream, without the trailing zero. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param string The string from which the data is written to the stream - * @return The number of bytes written */ -- (size_t)writeString: (OFString *)string; +- (void)writeString: (OFString *)string; /** * @brief Writes a string into the stream in the specified encoding, without * the trailing zero. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param string The string from which the data is written to the stream * @param encoding The encoding in which to write the string to the stream - * @return The number of bytes written */ -- (size_t)writeString: (OFString *)string encoding: (OFStringEncoding)encoding; +- (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding; /** * @brief Writes a string into the stream with a trailing newline. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param string The string from which the data is written to the stream - * @return The number of bytes written */ -- (size_t)writeLine: (OFString *)string; +- (void)writeLine: (OFString *)string; /** * @brief Writes a string into the stream in the specified encoding with a * trailing newline. * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * * @param string The string from which the data is written to the stream * @param encoding The encoding in which to write the string to the stream - * @return The number of bytes written + */ +- (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding; + +/** + * @brief Writes a formatted string into the stream. + * + * See printf for the format syntax. As an addition, `%@` is available as + * format specifier for objects, `%C` for `OFUnichar` and `%S` for + * `const OFUnichar *`. + * + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. + * + * @param format A string used as format */ -- (size_t)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding; +- (void)writeFormat: (OFConstantString *)format, ...; /** * @brief Writes a formatted string into the stream. * * See printf for the format syntax. As an addition, `%@` is available as * format specifier for objects, `%C` for `OFUnichar` and `%S` for * `const OFUnichar *`. * - * @param format A string used as format - * @return The number of bytes written - */ -- (size_t)writeFormat: (OFConstantString *)format, ...; - -/** - * @brief Writes a formatted string into the stream. - * - * See printf for the format syntax. As an addition, `%@` is available as - * format specifier for objects, `%C` for `OFUnichar` and `%S` for - * `const OFUnichar *`. + * In non-blocking mode, the behavior is the same as @ref writeBuffer:length:. * * @param format A string used as format * @param arguments The arguments used in the format string - * @return The number of bytes written */ -- (size_t)writeFormat: (OFConstantString *)format arguments: (va_list)arguments; +- (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments; #ifdef OF_HAVE_SOCKETS /** * @brief Cancels all pending asynchronous requests on the stream. */