@@ -45,16 +45,17 @@ * retains it. This is so that the stream can be used as a key for a * dictionary, so context can be associated with a stream. Using a * stream in more than one thread at the same time is not thread-safe, * even if copy was called to create one "instance" for every thread! * - * \note If you want to subclass this, override lowlevelReadIntoBuffer:length:, - * lowlevelWriteBuffer:length: and lowlevelIsAtEndOfStream, but nothing - * else, as those are are the methods that do the actual work. OFStream - * uses those for all other methods and does all the caching and other - * stuff for you. If you override these methods without the lowlevel - * prefix, you will break caching and get broken results! + * \note If you want to subclass this, override + * \ref lowlevelReadIntoBuffer:length:, \ref lowlevelWriteBuffer:length: + * and \ref lowlevelIsAtEndOfStream, but nothing else, as those are are + * the methods that do the actual work. OFStream uses those for all other + * methods and does all the caching and other stuff for you. If you + * override these methods without the lowlevel prefix, you will + * break caching and get broken results! */ @interface OFStream: OFObject { char *cache; char *writeBuffer; @@ -79,29 +80,29 @@ /** * \brief 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 - * -readIntoBuffer:exactLength:. Note that a read can even return 0 bytes - + * \ref readIntoBuffer:exactLength:. 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. + * check \ref isAtEndOfStream. * * \param buffer The buffer into which the data is read * \param length The length of the data that should be read at most. * The buffer must be at least this big! * \return The number of bytes read */ - (size_t)readIntoBuffer: (void*)buffer - length: (size_t)size; + length: (size_t)length; /** * \brief Reads exactly the specified length bytes from the stream into a * buffer. * - * Unlike readIntoBuffer:length:, this method does not return when less than the - * specified length has been read - instead, it waits until it got exactly the - * specified length. + * Unlike \ref readIntoBuffer:length:, this method does not return when less + * than the specified length has been read - instead, it waits until it got + * exactly the specified length. * * \warning Only call this when you know that specified amount of data is * available! Otherwise you will get an exception! * * \param buffer The buffer into which the data is read @@ -115,13 +116,13 @@ * \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. + * \ref 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 \ref 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! @@ -142,11 +143,11 @@ /** * \brief Asyncronously reads exactly the specified length bytes from the * stream into a buffer. * - * Unlike asyncReadIntoBuffer:length:block, this method does not call the + * Unlike \ref 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, the stream has ended or an * exception occurred. * * \param buffer The buffer into which the data is read @@ -172,13 +173,13 @@ * \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. + * \ref 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 \ref 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! @@ -194,11 +195,11 @@ /** * \brief Asyncronously reads exactly the specified length bytes from the * stream into a buffer. * - * Unlike asyncReadIntoBuffer:length:block, this method does not invoke the + * Unlike \ref asyncReadIntoBuffer:length:block, this method does not invoke the * block when less than the specified length has been read - instead, it waits * until it got exactly the specified length, the stream has ended or an * exception occurred. * * \param buffer The buffer into which the data is read @@ -280,77 +281,77 @@ * encoded in big endian. * * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * - * \param nInt16s The number of uint16_ts to read * \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)nInt16s; + 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 nInt32s The number of uint32_ts to read * \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)nInt32s; + 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 nInt64s The number of uint64_ts to read * \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)nInt64s; + 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 nFloatss The number of floats to read * \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)nFloats; + 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 nDoubles The number of doubles to read * \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)nDoubles; + 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! @@ -405,87 +406,87 @@ * encoded in little endian. * * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * - * \param nInt16s The number of uint16_ts to read * \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)nInt16s; + 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 nInt32s The number of uint32_ts to read * \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)nInt32s; + 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 nInt64s The number of uint64_ts to read * \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)nInt64s; + 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 nFloats The number of floats to read * \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)nFloats; + 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 nDoubles The number of doubles to read * \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)nDoubles; + count: (size_t)count; /** * \brief Reads the specified number of items with an item size of 1 from the * stream and returns them in an OFDataArray. * * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * - * \param nItems The number of items to read - * \return An OFDataArray with at nItems items. + * \param size The number of items to read + * \return An OFDataArray with count items. */ - (OFDataArray*)readDataArrayWithSize: (size_t)size; /** * \brief Reads the specified number of items with the specified item size from @@ -493,15 +494,15 @@ * * \warning Only call this when you know that enough data is available! * Otherwise you will get an exception! * * \param itemSize The size of each item - * \param nItems The number of items to read - * \return An OFDataArray with at nItems items. + * \param count The number of items to read + * \return An OFDataArray with count items. */ - (OFDataArray*)readDataArrayWithItemSize: (size_t)itemSize - count: (size_t)nItems; + count: (size_t)count; /** * \brief Returns an OFDataArray with all the remaining data of the stream. * * \return An OFDataArray with an item size of 1 with all the data of the @@ -630,12 +631,12 @@ */ - (OFString*)tryReadLine; /** * \brief Tries to read a line from the stream with the specified encoding (see - * readLineWithEncoding:) and returns nil if no complete line has been - * received yet. + * \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 */ @@ -663,23 +664,23 @@ - (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 readTillDelimiter:) and returns nil if not enough data - * has been received yet. + * 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. */ - (OFString*)tryReadTillDelimiter: (OFString*)delimiter; /** * \brief Tries to read until the specified string or \\0 is found or the end - * of stream occurs (see readTIllDelimiterWithEncoding:) and returns nil - * if not enough data has been received yet. + * of stream occurs (see \ref readTillDelimiterWithEncoding:) 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. @@ -759,65 +760,65 @@ /** * \brief Writes the specified number of uint16_ts into the stream, encoded in * big endian. * - * \param nInt16 The number of uint16_ts to write * \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)nInt16s; + count: (size_t)count; /** * \brief Writes the specified number of uint32_ts into the stream, encoded in * big endian. * - * \param nInt32 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 + * \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)nInt32s; + count: (size_t)count; /** * \brief Writes the specified number of uint64_ts into the stream, encoded in * big endian. * - * \param nInt64 The number of uint64_ts to write * \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)nInt64s; + count: (size_t)count; /** * \brief Writes the specified number of floats into the stream, encoded in big * endian. * - * \param nFloats The number of floats to write * \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)nFloats; + count: (size_t)count; /** * \brief Writes the specified number of doubles into the stream, encoded in * big endian. * - * \param nDoubles The number of doubles to write * \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)nDoubles; + count: (size_t)count; /** * \brief Writes a uint16_t into the stream, encoded in little endian. * * \param int16 A uint16_t @@ -854,65 +855,65 @@ /** * \brief Writes the specified number of uint16_ts into the stream, encoded in * little endian. * - * \param nInt16 The number of uint16_ts to write * \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)nInt16s; + count: (size_t)count; /** * \brief Writes the specified number of uint32_ts into the stream, encoded in * little endian. * - * \param nInt32 The number of uint32_ts to write + * \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)nInt32s; + count: (size_t)count; /** * \brief Writes the specified number of uint64_ts into the stream, encoded in * little endian. * - * \param nInt64 The number of uint64_ts to write * \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)nInt64s; + count: (size_t)count; /** * \brief Writes the specified number of floats into the stream, encoded in * little endian. * - * \param nFloats The number of floats to write * \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)nFloats; + count: (size_t)count; /** * \brief Writes the specified number of doubles into the stream, encoded in * little endian. * - * \param nDoubles The number of doubles to write * \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)nDoubles; + count: (size_t)count; /** * \brief Writes from an OFDataArray into the stream. * * \param dataArray The OFDataArray to write into the stream