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  OF_RESERVE_IVARS(OFStream, 3)
292 }
293 
297 @property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream;
298 
302 @property (nonatomic) bool buffersWrites;
303 
307 @property (readonly, nonatomic) bool hasDataInReadBuffer;
308 
315 @property (nonatomic) OFStringEncoding encoding;
316 
326 @property (nonatomic) bool canBlock;
327 
334 @property OF_NULLABLE_PROPERTY (assign, nonatomic)
335  id <OFStreamDelegate> delegate;
336 
355 - (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;
356 
376  - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;
377 
378 #ifdef OF_HAVE_SOCKETS
399 - (void)asyncReadIntoBuffer: (void *)buffer length: (size_t)length;
400 
422 - (void)asyncReadIntoBuffer: (void *)buffer
423  length: (size_t)length
424  runLoopMode: (OFRunLoopMode)runLoopMode;
425 
442 - (void)asyncReadIntoBuffer: (void *)buffer exactLength: (size_t)length;
443 
461 - (void)asyncReadIntoBuffer: (void *)buffer
462  exactLength: (size_t)length
463  runLoopMode: (OFRunLoopMode)runLoopMode;
464 
465 # ifdef OF_HAVE_BLOCKS
493 - (void)asyncReadIntoBuffer: (void *)buffer
494  length: (size_t)length
495  block: (OFStreamAsyncReadBlock)block
496  OF_DEPRECATED(ObjFW, 1, 2,
497  "Use -[asyncReadIntoBuffer:length:handler:] instead");
498 
525 - (void)asyncReadIntoBuffer: (void *)buffer
526  length: (size_t)length
527  handler: (OFStreamReadHandler)handler;
528 
557 - (void)asyncReadIntoBuffer: (void *)buffer
558  length: (size_t)length
559  runLoopMode: (OFRunLoopMode)runLoopMode
560  block: (OFStreamAsyncReadBlock)block
561  OF_DEPRECATED(ObjFW, 1, 2,
562  "Use -[asyncReadIntoBuffer:length:runLoopMode:handler:] instead");
563 
591 - (void)asyncReadIntoBuffer: (void *)buffer
592  length: (size_t)length
593  runLoopMode: (OFRunLoopMode)runLoopMode
594  handler: (OFStreamReadHandler)handler;
595 
619 - (void)asyncReadIntoBuffer: (void *)buffer
620  exactLength: (size_t)length
621  block: (OFStreamAsyncReadBlock)block
622  OF_DEPRECATED(ObjFW, 1, 2,
623  "Use -[asyncReadIntoBuffer:exactLength:handler:] instead");
624 
647 - (void)asyncReadIntoBuffer: (void *)buffer
648  exactLength: (size_t)length
649  handler: (OFStreamReadHandler)handler;
650 
676 - (void)asyncReadIntoBuffer: (void *)buffer
677  exactLength: (size_t)length
678  runLoopMode: (OFRunLoopMode)runLoopMode
679  block: (OFStreamAsyncReadBlock)block
680  OF_DEPRECATED(ObjFW, 1, 2,
681  "Use -[asyncReadIntoBuffer:exactLength:runLoopMode:handler: instead]");
682 
706 - (void)asyncReadIntoBuffer: (void *)buffer
707  exactLength: (size_t)length
708  runLoopMode: (OFRunLoopMode)runLoopMode
709  handler: (OFStreamReadHandler)handler;
710 # endif
711 #endif
712 
725 - (uint8_t)readInt8;
726 
739 - (uint16_t)readBigEndianInt16;
740 
753 - (uint32_t)readBigEndianInt32;
754 
767 - (uint64_t)readBigEndianInt64;
768 
781 - (float)readBigEndianFloat;
782 
795 - (double)readBigEndianDouble;
796 
809 - (uint16_t)readLittleEndianInt16;
810 
823 - (uint32_t)readLittleEndianInt32;
824 
837 - (uint64_t)readLittleEndianInt64;
838 
851 - (float)readLittleEndianFloat;
852 
865 - (double)readLittleEndianDouble;
866 
881 - (OFData *)readDataWithCount: (size_t)count;
882 
898 - (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;
899 
908 - (OFData *)readDataUntilEndOfStream;
909 
919 - (OFString *)readString;
920 
931 - (OFString *)readStringWithEncoding: (OFStringEncoding)encoding;
932 
953 - (OFString *)readStringWithLength: (size_t)length;
954 
976 - (OFString *)readStringWithLength: (size_t)length
977  encoding: (OFStringEncoding)encoding;
978 
989 - (nullable OFString *)readLine;
990 
1003 - (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;
1004 
1005 #ifdef OF_HAVE_SOCKETS
1013 - (void)asyncReadString;
1014 
1024 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding;
1025 
1036 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1037  runLoopMode: (OFRunLoopMode)runLoopMode;
1038 
1046 - (void)asyncReadLine;
1047 
1057 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding;
1058 
1069 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1070  runLoopMode: (OFRunLoopMode)runLoopMode;
1071 
1072 # ifdef OF_HAVE_BLOCKS
1086 - (void)asyncReadStringWithHandler: (OFStreamStringReadHandler)handler;
1087 
1102 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1103  handler: (OFStreamStringReadHandler)handler;
1104 
1120 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1121  runLoopMode: (OFRunLoopMode)runLoopMode
1122  handler: (OFStreamStringReadHandler)handler;
1123 
1139 - (void)asyncReadLineWithBlock: (OFStreamAsyncReadLineBlock)block
1140  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncReadLineWithHandler:] instead");
1141 
1155 - (void)asyncReadLineWithHandler: (OFStreamStringReadHandler)handler;
1156 
1173 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1174  block: (OFStreamAsyncReadLineBlock)block
1175  OF_DEPRECATED(ObjFW, 1, 2,
1176  "Use -[asyncReadLineWithEncoding:handler:] instead");
1177 
1192 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1193  handler: (OFStreamStringReadHandler)handler;
1194 
1212 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1213  runLoopMode: (OFRunLoopMode)runLoopMode
1214  block: (OFStreamAsyncReadLineBlock)block
1215  OF_DEPRECATED(ObjFW, 1, 2,
1216  "Use -[asyncReadLineWithEncoding:runLoopMode:handler:] instead");
1217 
1233 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1234  runLoopMode: (OFRunLoopMode)runLoopMode
1235  handler: (OFStreamStringReadHandler)handler;
1236 # endif
1237 #endif
1238 
1248 - (OFString *)tryReadString;
1249 
1260 - (OFString *)tryReadStringWithEncoding: (OFStringEncoding)encoding;
1261 
1273 - (nullable OFString *)tryReadLine;
1274 
1288 - (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;
1289 
1302 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;
1303 
1317 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
1318  encoding: (OFStringEncoding)encoding;
1319 
1333 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;
1334 
1349 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
1350  encoding: (OFStringEncoding)encoding;
1351 
1359 - (bool)flushWriteBuffer;
1360 
1376 - (void)writeBuffer: (const void *)buffer length: (size_t)length;
1377 
1378 #ifdef OF_HAVE_SOCKETS
1387 - (void)asyncWriteData: (OFData *)data;
1388 
1398 - (void)asyncWriteData: (OFData *)data
1399  runLoopMode: (OFRunLoopMode)runLoopMode;
1400 
1409 - (void)asyncWriteString: (OFString *)string;
1410 
1422 - (void)asyncWriteString: (OFString *)string
1423  encoding: (OFStringEncoding)encoding;
1424 
1437 - (void)asyncWriteString: (OFString *)string
1438  encoding: (OFStringEncoding)encoding
1439  runLoopMode: (OFRunLoopMode)runLoopMode;
1440 
1441 # ifdef OF_HAVE_BLOCKS
1455 - (void)asyncWriteData: (OFData *)data
1456  block: (OFStreamAsyncWriteDataBlock)block
1457  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteData:handler:] instead");
1458 
1470 - (void)asyncWriteData: (OFData *)data
1471  handler: (OFStreamDataWrittenHandler)handler;
1472 
1487 - (void)asyncWriteData: (OFData *)data
1488  runLoopMode: (OFRunLoopMode)runLoopMode
1489  block: (OFStreamAsyncWriteDataBlock)block
1490  OF_DEPRECATED(ObjFW, 1, 2,
1491  "Use -[asyncWriteData:runLoopMode:handler:] instead");
1492 
1505 - (void)asyncWriteData: (OFData *)data
1506  runLoopMode: (OFRunLoopMode)runLoopMode
1507  handler: (OFStreamDataWrittenHandler)handler;
1508 
1522 - (void)asyncWriteString: (OFString *)string
1523  block: (OFStreamAsyncWriteStringBlock)block
1524  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteString:handler:] instead");
1525 
1537 - (void)asyncWriteString: (OFString *)string
1538  handler: (OFStreamStringWrittenHandler)handler;
1539 
1556 - (void)asyncWriteString: (OFString *)string
1557  encoding: (OFStringEncoding)encoding
1558  block: (OFStreamAsyncWriteStringBlock)block
1559  OF_DEPRECATED(ObjFW, 1, 2,
1560  "Use -[asyncWriteString:encoding:handler:] instead");
1561 
1576 - (void)asyncWriteString: (OFString *)string
1577  encoding: (OFStringEncoding)encoding
1578  handler: (OFStreamStringWrittenHandler)handler;
1579 
1597 - (void)asyncWriteString: (OFString *)string
1598  encoding: (OFStringEncoding)encoding
1599  runLoopMode: (OFRunLoopMode)runLoopMode
1600  block: (OFStreamAsyncWriteStringBlock)block
1601  OF_DEPRECATED(ObjFW, 1, 2,
1602  "Use -[asyncWriteString:encoding:runLoopMode:handler:] instead");
1603 
1619 - (void)asyncWriteString: (OFString *)string
1620  encoding: (OFStringEncoding)encoding
1621  runLoopMode: (OFRunLoopMode)runLoopMode
1622  handler: (OFStreamStringWrittenHandler)handler;
1623 # endif
1624 #endif
1625 
1635 - (void)writeInt8: (uint8_t)int8;
1636 
1646 - (void)writeBigEndianInt16: (uint16_t)int16;
1647 
1657 - (void)writeBigEndianInt32: (uint32_t)int32;
1658 
1668 - (void)writeBigEndianInt64: (uint64_t)int64;
1669 
1679 - (void)writeBigEndianFloat: (float)float_;
1680 
1690 - (void)writeBigEndianDouble: (double)double_;
1691 
1701 - (void)writeLittleEndianInt16: (uint16_t)int16;
1702 
1712 - (void)writeLittleEndianInt32: (uint32_t)int32;
1713 
1723 - (void)writeLittleEndianInt64: (uint64_t)int64;
1724 
1734 - (void)writeLittleEndianFloat: (float)float_;
1735 
1745 - (void)writeLittleEndianDouble: (double)double_;
1746 
1756 - (void)writeData: (OFData *)data;
1757 
1767 - (void)writeString: (OFString *)string;
1768 
1780 - (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;
1781 
1791 - (void)writeLine: (OFString *)string;
1792 
1804 - (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;
1805 
1820 - (void)writeFormat: (OFConstantString *)format, ...;
1821 
1837 - (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;
1838 
1839 #ifdef OF_HAVE_SOCKETS
1843 - (void)cancelAsyncRequests;
1844 #endif
1845 
1867 - (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;
1868 
1876 - (void)close;
1877 
1892 - (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;
1893 
1908 - (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;
1909 
1920 - (bool)lowlevelIsAtEndOfStream;
1921 
1933 - (bool)lowlevelHasDataInReadBuffer;
1934 @end
1935 
1936 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:922
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:1584
OFStreamDelegate-p
Definition: OFStream.h:176
Generated by doxygen 1.9.1