ObjFW
OFStream.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2026 Jonathan Schleifer <js@nil.im>
3  *
4  * All rights reserved.
5  *
6  * This program is free software: you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License version 3.0 only,
8  * as published by the Free Software Foundation.
9  *
10  * This program is distributed in the hope that it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
13  * version 3.0 for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * version 3.0 along with this program. If not, see
17  * <https://www.gnu.org/licenses/>.
18  */
19 
20 #ifndef __STDC_LIMIT_MACROS
21 # define __STDC_LIMIT_MACROS
22 #endif
23 #ifndef __STDC_CONSTANT_MACROS
24 # define __STDC_CONSTANT_MACROS
25 #endif
26 
27 #include <stdarg.h>
28 
29 #import "OFObject.h"
30 #import "OFString.h"
31 #import "OFRunLoop.h"
32 #ifdef OF_HAVE_SOCKETS
33 # import "OFKernelEventObserver.h"
34 #endif
35 
36 OF_ASSUME_NONNULL_BEGIN
37 
40 @class OFStream;
41 @class OFData;
42 
43 #if defined(OF_HAVE_SOCKETS) && defined(OF_HAVE_BLOCKS)
55 typedef bool (^OFStreamAsyncReadBlock)(size_t length, id _Nullable exception)
56  OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamReadHandler instead");
57 
69 typedef bool (^OFStreamReadHandler)(OFStream *stream, void *buffer,
70  size_t length, id _Nullable exception);
71 
83 typedef bool (^OFStreamStringReadHandler)(OFStream *stream,
84  OFString *_Nullable string, id _Nullable exception);
85 
98 typedef bool (^OFStreamAsyncReadLineBlock)(OFString *_Nullable line,
99  id _Nullable exception)
100  OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringReadHandler instead");
101 
115 typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(size_t bytesWritten,
116  id _Nullable exception)
117  OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamDataWrittenHandler instead");
118 
132 typedef OFData *_Nullable (^OFStreamDataWrittenHandler)(OFStream *stream,
133  OFData *data, size_t bytesWritten, id _Nullable exception);
134 
148 typedef OFString *_Nullable (^OFStreamAsyncWriteStringBlock)(
149  size_t bytesWritten, id _Nullable exception)
150  OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringWrittenHandler instead");
151 
166 typedef OFString *_Nullable (^OFStreamStringWrittenHandler)(OFStream *stream,
167  OFString *string, OFStringEncoding encoding, size_t bytesWritten,
168  id _Nullable exception);
169 #endif
170 
176 @protocol OFStreamDelegate <OFObject>
177 @optional
188 - (bool)stream: (OFStream *)stream
189  didReadIntoBuffer: (void *)buffer
190  length: (size_t)length
191  exception: (nullable id)exception;
192 
203 - (bool)stream: (OFStream *)stream
204  didReadString: (nullable OFString *)string
205  exception: (nullable id)exception;
206 
217 - (bool)stream: (OFStream *)stream
218  didReadLine: (nullable OFString *)line
219  exception: (nullable id)exception;
220 
233 - (nullable OFData *)stream: (OFStream *)stream
234  didWriteData: (OFData *)data
235  bytesWritten: (size_t)bytesWritten
236  exception: (nullable id)exception;
237 
251 - (nullable OFString *)stream: (OFStream *)stream
252  didWriteString: (OFString *)string
253  encoding: (OFStringEncoding)encoding
254  bytesWritten: (size_t)bytesWritten
255  exception: (nullable id)exception;
256 @end
257 
278 @interface OFStream: OFObject <OFCopying>
279 {
280  bool _canBlock;
281  id _Nullable _delegate;
282 #ifndef OF_SEEKABLE_STREAM_M
283 @private
284 #endif
285  char *_Nullable _readBuffer, *_Nullable _readBufferMemory;
286  char *_Nullable _writeBuffer;
287  size_t _readBufferLength, _writeBufferLength;
288  bool _buffersWrites, _waitingForDelimiter;
289 @private
290  uintptr_t _encoding;
291  uintptr_t _allowsLossyEncoding;
292  OF_RESERVE_IVARS(OFStream, 2)
293 }
294 
298 @property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream;
299 
303 @property (nonatomic) bool buffersWrites;
304 
308 @property (readonly, nonatomic) bool hasDataInReadBuffer;
309 
316 @property (nonatomic) OFStringEncoding encoding;
317 
326 @property (nonatomic) bool allowsLossyEncoding;
327 
337 @property (nonatomic) bool canBlock;
338 
345 @property OF_NULLABLE_PROPERTY (assign, nonatomic)
346  id <OFStreamDelegate> delegate;
347 
366 - (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;
367 
387  - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;
388 
389 #ifdef OF_HAVE_SOCKETS
410 - (void)asyncReadIntoBuffer: (void *)buffer length: (size_t)length;
411 
433 - (void)asyncReadIntoBuffer: (void *)buffer
434  length: (size_t)length
435  runLoopMode: (OFRunLoopMode)runLoopMode;
436 
453 - (void)asyncReadIntoBuffer: (void *)buffer exactLength: (size_t)length;
454 
472 - (void)asyncReadIntoBuffer: (void *)buffer
473  exactLength: (size_t)length
474  runLoopMode: (OFRunLoopMode)runLoopMode;
475 
476 # ifdef OF_HAVE_BLOCKS
504 - (void)asyncReadIntoBuffer: (void *)buffer
505  length: (size_t)length
506  block: (OFStreamAsyncReadBlock)block
507  OF_DEPRECATED(ObjFW, 1, 2,
508  "Use -[asyncReadIntoBuffer:length:handler:] instead");
509 
536 - (void)asyncReadIntoBuffer: (void *)buffer
537  length: (size_t)length
538  handler: (OFStreamReadHandler)handler;
539 
568 - (void)asyncReadIntoBuffer: (void *)buffer
569  length: (size_t)length
570  runLoopMode: (OFRunLoopMode)runLoopMode
571  block: (OFStreamAsyncReadBlock)block
572  OF_DEPRECATED(ObjFW, 1, 2,
573  "Use -[asyncReadIntoBuffer:length:runLoopMode:handler:] instead");
574 
602 - (void)asyncReadIntoBuffer: (void *)buffer
603  length: (size_t)length
604  runLoopMode: (OFRunLoopMode)runLoopMode
605  handler: (OFStreamReadHandler)handler;
606 
630 - (void)asyncReadIntoBuffer: (void *)buffer
631  exactLength: (size_t)length
632  block: (OFStreamAsyncReadBlock)block
633  OF_DEPRECATED(ObjFW, 1, 2,
634  "Use -[asyncReadIntoBuffer:exactLength:handler:] instead");
635 
658 - (void)asyncReadIntoBuffer: (void *)buffer
659  exactLength: (size_t)length
660  handler: (OFStreamReadHandler)handler;
661 
687 - (void)asyncReadIntoBuffer: (void *)buffer
688  exactLength: (size_t)length
689  runLoopMode: (OFRunLoopMode)runLoopMode
690  block: (OFStreamAsyncReadBlock)block
691  OF_DEPRECATED(ObjFW, 1, 2,
692  "Use -[asyncReadIntoBuffer:exactLength:runLoopMode:handler: instead]");
693 
717 - (void)asyncReadIntoBuffer: (void *)buffer
718  exactLength: (size_t)length
719  runLoopMode: (OFRunLoopMode)runLoopMode
720  handler: (OFStreamReadHandler)handler;
721 # endif
722 #endif
723 
736 - (uint8_t)readInt8;
737 
750 - (uint16_t)readBigEndianInt16;
751 
764 - (uint32_t)readBigEndianInt32;
765 
778 - (uint64_t)readBigEndianInt64;
779 
792 - (float)readBigEndianFloat;
793 
806 - (double)readBigEndianDouble;
807 
820 - (uint16_t)readLittleEndianInt16;
821 
834 - (uint32_t)readLittleEndianInt32;
835 
848 - (uint64_t)readLittleEndianInt64;
849 
862 - (float)readLittleEndianFloat;
863 
876 - (double)readLittleEndianDouble;
877 
892 - (OFData *)readDataWithCount: (size_t)count;
893 
909 - (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;
910 
919 - (OFData *)readDataUntilEndOfStream;
920 
930 - (OFString *)readString;
931 
942 - (OFString *)readStringWithEncoding: (OFStringEncoding)encoding;
943 
964 - (OFString *)readStringWithLength: (size_t)length;
965 
987 - (OFString *)readStringWithLength: (size_t)length
988  encoding: (OFStringEncoding)encoding;
989 
1000 - (nullable OFString *)readLine;
1001 
1014 - (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;
1015 
1016 #ifdef OF_HAVE_SOCKETS
1024 - (void)asyncReadString;
1025 
1035 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding;
1036 
1047 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1048  runLoopMode: (OFRunLoopMode)runLoopMode;
1049 
1057 - (void)asyncReadLine;
1058 
1068 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding;
1069 
1080 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1081  runLoopMode: (OFRunLoopMode)runLoopMode;
1082 
1083 # ifdef OF_HAVE_BLOCKS
1097 - (void)asyncReadStringWithHandler: (OFStreamStringReadHandler)handler;
1098 
1113 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1114  handler: (OFStreamStringReadHandler)handler;
1115 
1131 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1132  runLoopMode: (OFRunLoopMode)runLoopMode
1133  handler: (OFStreamStringReadHandler)handler;
1134 
1150 - (void)asyncReadLineWithBlock: (OFStreamAsyncReadLineBlock)block
1151  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncReadLineWithHandler:] instead");
1152 
1166 - (void)asyncReadLineWithHandler: (OFStreamStringReadHandler)handler;
1167 
1184 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1185  block: (OFStreamAsyncReadLineBlock)block
1186  OF_DEPRECATED(ObjFW, 1, 2,
1187  "Use -[asyncReadLineWithEncoding:handler:] instead");
1188 
1203 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1204  handler: (OFStreamStringReadHandler)handler;
1205 
1223 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1224  runLoopMode: (OFRunLoopMode)runLoopMode
1225  block: (OFStreamAsyncReadLineBlock)block
1226  OF_DEPRECATED(ObjFW, 1, 2,
1227  "Use -[asyncReadLineWithEncoding:runLoopMode:handler:] instead");
1228 
1244 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1245  runLoopMode: (OFRunLoopMode)runLoopMode
1246  handler: (OFStreamStringReadHandler)handler;
1247 # endif
1248 #endif
1249 
1259 - (OFString *)tryReadString;
1260 
1271 - (OFString *)tryReadStringWithEncoding: (OFStringEncoding)encoding;
1272 
1284 - (nullable OFString *)tryReadLine;
1285 
1299 - (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;
1300 
1313 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;
1314 
1328 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
1329  encoding: (OFStringEncoding)encoding;
1330 
1344 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;
1345 
1360 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
1361  encoding: (OFStringEncoding)encoding;
1362 
1370 - (bool)flushWriteBuffer;
1371 
1387 - (void)writeBuffer: (const void *)buffer length: (size_t)length;
1388 
1389 #ifdef OF_HAVE_SOCKETS
1398 - (void)asyncWriteData: (OFData *)data;
1399 
1409 - (void)asyncWriteData: (OFData *)data
1410  runLoopMode: (OFRunLoopMode)runLoopMode;
1411 
1420 - (void)asyncWriteString: (OFString *)string;
1421 
1433 - (void)asyncWriteString: (OFString *)string
1434  encoding: (OFStringEncoding)encoding;
1435 
1448 - (void)asyncWriteString: (OFString *)string
1449  encoding: (OFStringEncoding)encoding
1450  runLoopMode: (OFRunLoopMode)runLoopMode;
1451 
1452 # ifdef OF_HAVE_BLOCKS
1466 - (void)asyncWriteData: (OFData *)data
1467  block: (OFStreamAsyncWriteDataBlock)block
1468  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteData:handler:] instead");
1469 
1481 - (void)asyncWriteData: (OFData *)data
1482  handler: (OFStreamDataWrittenHandler)handler;
1483 
1498 - (void)asyncWriteData: (OFData *)data
1499  runLoopMode: (OFRunLoopMode)runLoopMode
1500  block: (OFStreamAsyncWriteDataBlock)block
1501  OF_DEPRECATED(ObjFW, 1, 2,
1502  "Use -[asyncWriteData:runLoopMode:handler:] instead");
1503 
1516 - (void)asyncWriteData: (OFData *)data
1517  runLoopMode: (OFRunLoopMode)runLoopMode
1518  handler: (OFStreamDataWrittenHandler)handler;
1519 
1533 - (void)asyncWriteString: (OFString *)string
1534  block: (OFStreamAsyncWriteStringBlock)block
1535  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteString:handler:] instead");
1536 
1548 - (void)asyncWriteString: (OFString *)string
1549  handler: (OFStreamStringWrittenHandler)handler;
1550 
1567 - (void)asyncWriteString: (OFString *)string
1568  encoding: (OFStringEncoding)encoding
1569  block: (OFStreamAsyncWriteStringBlock)block
1570  OF_DEPRECATED(ObjFW, 1, 2,
1571  "Use -[asyncWriteString:encoding:handler:] instead");
1572 
1587 - (void)asyncWriteString: (OFString *)string
1588  encoding: (OFStringEncoding)encoding
1589  handler: (OFStreamStringWrittenHandler)handler;
1590 
1608 - (void)asyncWriteString: (OFString *)string
1609  encoding: (OFStringEncoding)encoding
1610  runLoopMode: (OFRunLoopMode)runLoopMode
1611  block: (OFStreamAsyncWriteStringBlock)block
1612  OF_DEPRECATED(ObjFW, 1, 2,
1613  "Use -[asyncWriteString:encoding:runLoopMode:handler:] instead");
1614 
1630 - (void)asyncWriteString: (OFString *)string
1631  encoding: (OFStringEncoding)encoding
1632  runLoopMode: (OFRunLoopMode)runLoopMode
1633  handler: (OFStreamStringWrittenHandler)handler;
1634 # endif
1635 #endif
1636 
1646 - (void)writeInt8: (uint8_t)int8;
1647 
1657 - (void)writeBigEndianInt16: (uint16_t)int16;
1658 
1668 - (void)writeBigEndianInt32: (uint32_t)int32;
1669 
1679 - (void)writeBigEndianInt64: (uint64_t)int64;
1680 
1690 - (void)writeBigEndianFloat: (float)float_;
1691 
1701 - (void)writeBigEndianDouble: (double)double_;
1702 
1712 - (void)writeLittleEndianInt16: (uint16_t)int16;
1713 
1723 - (void)writeLittleEndianInt32: (uint32_t)int32;
1724 
1734 - (void)writeLittleEndianInt64: (uint64_t)int64;
1735 
1745 - (void)writeLittleEndianFloat: (float)float_;
1746 
1756 - (void)writeLittleEndianDouble: (double)double_;
1757 
1767 - (void)writeData: (OFData *)data;
1768 
1778 - (void)writeString: (OFString *)string;
1779 
1791 - (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;
1792 
1802 - (void)writeLine: (OFString *)string;
1803 
1815 - (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;
1816 
1831 - (void)writeFormat: (OFConstantString *)format, ...;
1832 
1848 - (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;
1849 
1850 #ifdef OF_HAVE_SOCKETS
1854 - (void)cancelAsyncRequests;
1855 #endif
1856 
1878 - (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;
1879 
1887 - (void)close;
1888 
1903 - (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;
1904 
1919 - (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;
1920 
1931 - (bool)lowlevelIsAtEndOfStream;
1932 
1944 - (bool)lowlevelHasDataInReadBuffer;
1945 @end
1946 
1947 OF_ASSUME_NONNULL_END
OFStreamDataWrittenHandler
OFData *(^ OFStreamDataWrittenHandler)(OFStream *stream, OFData *data, size_t bytesWritten, id exception)
A handler which is called when data was written asynchronously to a stream.
Definition: OFStream.h:132
OFStreamReadHandler
bool(^ OFStreamReadHandler)(OFStream *stream, void *buffer, size_t length, id exception)
A handler which is called when data was read asynchronously from a stream.
Definition: OFStream.h:69
OFStreamAsyncReadBlock
bool(^ OFStreamAsyncReadBlock)(size_t length, id exception)
A block which is called when data was read asynchronously from a stream.
Definition: OFStream.h:55
OFStreamAsyncWriteStringBlock
OFString *(^ OFStreamAsyncWriteStringBlock)(size_t bytesWritten, id exception)
A block which is called when a string was written asynchronously to a stream.
Definition: OFStream.h:148
OFStreamAsyncReadLineBlock
bool(^ OFStreamAsyncReadLineBlock)(OFString *line, id exception)
A block which is called when a line was read asynchronously from a stream.
Definition: OFStream.h:98
OFStreamStringReadHandler
bool(^ OFStreamStringReadHandler)(OFStream *stream, OFString *string, id exception)
A block which is called when a string was read asynchronously from a stream.
Definition: OFStream.h:83
OFStreamAsyncWriteDataBlock
OFData *(^ OFStreamAsyncWriteDataBlock)(size_t bytesWritten, id exception)
A block which is called when data was written asynchronously to a stream.
Definition: OFStream.h:115
OFStreamStringWrittenHandler
OFString *(^ OFStreamStringWrittenHandler)(OFStream *stream, OFString *string, OFStringEncoding encoding, size_t bytesWritten, id exception)
A handler which is called when a string was written asynchronously to a stream.
Definition: OFStream.h:166
OFStringEncoding
OFStringEncoding
The encoding of a string.
Definition: OFString.h:65
OFConstantString
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:42
OFData
A class for storing arbitrary data in an array.
Definition: OFData.h:46
OFObject
The root class for all other classes inside ObjFW.
Definition: OFObject.h:956
OFStream
A base class for different types of streams.
Definition: OFStream.h:280
OFString
A class for handling strings.
Definition: OFString.h:143
OFCopying-p
A protocol for the creation of copies.
Definition: OFObject.h:1618
OFStreamDelegate-p
Definition: OFStream.h:176
Generated by doxygen 1.9.1