ObjFW
OFStream.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2024 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)
44 
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 
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 
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  OF_RESERVE_IVARS(OFStream, 4)
290 }
291 
295 @property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream;
300 @property (nonatomic) bool buffersWrites;
305 @property (readonly, nonatomic) bool hasDataInReadBuffer;
316 @property (nonatomic) bool canBlock;
324 @property OF_NULLABLE_PROPERTY (assign, nonatomic)
325  id <OFStreamDelegate> delegate;
345 - (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;
346 
366  - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;
367 
368 #ifdef OF_HAVE_SOCKETS
369 
389 - (void)asyncReadIntoBuffer: (void *)buffer length: (size_t)length;
390 
412 - (void)asyncReadIntoBuffer: (void *)buffer
413  length: (size_t)length
414  runLoopMode: (OFRunLoopMode)runLoopMode;
415 
432 - (void)asyncReadIntoBuffer: (void *)buffer exactLength: (size_t)length;
433 
451 - (void)asyncReadIntoBuffer: (void *)buffer
452  exactLength: (size_t)length
453  runLoopMode: (OFRunLoopMode)runLoopMode;
454 
455 # ifdef OF_HAVE_BLOCKS
456 
483 - (void)asyncReadIntoBuffer: (void *)buffer
484  length: (size_t)length
485  block: (OFStreamAsyncReadBlock)block
486  OF_DEPRECATED(ObjFW, 1, 2,
487  "Use -[asyncReadIntoBuffer:length:handler:] instead");
488 
515 - (void)asyncReadIntoBuffer: (void *)buffer
516  length: (size_t)length
517  handler: (OFStreamReadHandler)handler;
518 
547 - (void)asyncReadIntoBuffer: (void *)buffer
548  length: (size_t)length
549  runLoopMode: (OFRunLoopMode)runLoopMode
550  block: (OFStreamAsyncReadBlock)block
551  OF_DEPRECATED(ObjFW, 1, 2,
552  "Use -[asyncReadIntoBuffer:length:runLoopMode:handler:] instead");
553 
581 - (void)asyncReadIntoBuffer: (void *)buffer
582  length: (size_t)length
583  runLoopMode: (OFRunLoopMode)runLoopMode
584  handler: (OFStreamReadHandler)handler;
585 
609 - (void)asyncReadIntoBuffer: (void *)buffer
610  exactLength: (size_t)length
611  block: (OFStreamAsyncReadBlock)block
612  OF_DEPRECATED(ObjFW, 1, 2,
613  "Use -[asyncReadIntoBuffer:exactLength:handler:] instead");
614 
637 - (void)asyncReadIntoBuffer: (void *)buffer
638  exactLength: (size_t)length
639  handler: (OFStreamReadHandler)handler;
640 
666 - (void)asyncReadIntoBuffer: (void *)buffer
667  exactLength: (size_t)length
668  runLoopMode: (OFRunLoopMode)runLoopMode
669  block: (OFStreamAsyncReadBlock)block
670  OF_DEPRECATED(ObjFW, 1, 2,
671  "Use -[asyncReadIntoBuffer:exactLength:runLoopMode:handler: instead]");
672 
696 - (void)asyncReadIntoBuffer: (void *)buffer
697  exactLength: (size_t)length
698  runLoopMode: (OFRunLoopMode)runLoopMode
699  handler: (OFStreamReadHandler)handler;
700 # endif
701 #endif
702 
715 - (uint8_t)readInt8;
716 
729 - (uint16_t)readBigEndianInt16;
730 
743 - (uint32_t)readBigEndianInt32;
744 
757 - (uint64_t)readBigEndianInt64;
758 
771 - (float)readBigEndianFloat;
772 
785 - (double)readBigEndianDouble;
786 
799 - (uint16_t)readLittleEndianInt16;
800 
813 - (uint32_t)readLittleEndianInt32;
814 
827 - (uint64_t)readLittleEndianInt64;
828 
841 - (float)readLittleEndianFloat;
842 
855 - (double)readLittleEndianDouble;
856 
871 - (OFData *)readDataWithCount: (size_t)count;
872 
888 - (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;
889 
898 - (OFData *)readDataUntilEndOfStream;
899 
909 - (OFString *)readString;
910 
921 - (OFString *)readStringWithEncoding: (OFStringEncoding)encoding;
922 
943 - (OFString *)readStringWithLength: (size_t)length;
944 
966 - (OFString *)readStringWithLength: (size_t)length
967  encoding: (OFStringEncoding)encoding;
968 
979 - (nullable OFString *)readLine;
980 
993 - (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;
994 
995 #ifdef OF_HAVE_SOCKETS
996 
1003 - (void)asyncReadString;
1004 
1014 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding;
1015 
1026 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1027  runLoopMode: (OFRunLoopMode)runLoopMode;
1028 
1036 - (void)asyncReadLine;
1037 
1047 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding;
1048 
1059 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1060  runLoopMode: (OFRunLoopMode)runLoopMode;
1061 
1062 # ifdef OF_HAVE_BLOCKS
1063 
1076 - (void)asyncReadStringWithHandler: (OFStreamStringReadHandler)handler;
1077 
1092 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1093  handler: (OFStreamStringReadHandler)handler;
1094 
1110 - (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
1111  runLoopMode: (OFRunLoopMode)runLoopMode
1112  handler: (OFStreamStringReadHandler)handler;
1113 
1129 - (void)asyncReadLineWithBlock: (OFStreamAsyncReadLineBlock)block
1130  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncReadLineWithHandler:] instead");
1131 
1145 - (void)asyncReadLineWithHandler: (OFStreamStringReadHandler)handler;
1146 
1163 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1164  block: (OFStreamAsyncReadLineBlock)block
1165  OF_DEPRECATED(ObjFW, 1, 2,
1166  "Use -[asyncReadLineWithEncoding:handler:] instead");
1167 
1182 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1183  handler: (OFStreamStringReadHandler)handler;
1184 
1202 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1203  runLoopMode: (OFRunLoopMode)runLoopMode
1204  block: (OFStreamAsyncReadLineBlock)block
1205  OF_DEPRECATED(ObjFW, 1, 2,
1206  "Use -[asyncReadLineWithEncoding:runLoopMode:handler:] instead");
1207 
1223 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
1224  runLoopMode: (OFRunLoopMode)runLoopMode
1225  handler: (OFStreamStringReadHandler)handler;
1226 # endif
1227 #endif
1228 
1238 - (OFString *)tryReadString;
1239 
1250 - (OFString *)tryReadStringWithEncoding: (OFStringEncoding)encoding;
1251 
1263 - (nullable OFString *)tryReadLine;
1264 
1278 - (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;
1279 
1292 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;
1293 
1307 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
1308  encoding: (OFStringEncoding)encoding;
1309 
1323 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;
1324 
1339 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
1340  encoding: (OFStringEncoding)encoding;
1341 
1349 - (bool)flushWriteBuffer;
1350 
1366 - (void)writeBuffer: (const void *)buffer length: (size_t)length;
1367 
1368 #ifdef OF_HAVE_SOCKETS
1369 
1377 - (void)asyncWriteData: (OFData *)data;
1378 
1388 - (void)asyncWriteData: (OFData *)data
1389  runLoopMode: (OFRunLoopMode)runLoopMode;
1390 
1399 - (void)asyncWriteString: (OFString *)string;
1400 
1412 - (void)asyncWriteString: (OFString *)string
1413  encoding: (OFStringEncoding)encoding;
1414 
1427 - (void)asyncWriteString: (OFString *)string
1428  encoding: (OFStringEncoding)encoding
1429  runLoopMode: (OFRunLoopMode)runLoopMode;
1430 
1431 # ifdef OF_HAVE_BLOCKS
1432 
1445 - (void)asyncWriteData: (OFData *)data
1446  block: (OFStreamAsyncWriteDataBlock)block
1447  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteData:handler:] instead");
1448 
1460 - (void)asyncWriteData: (OFData *)data
1461  handler: (OFStreamDataWrittenHandler)handler;
1462 
1477 - (void)asyncWriteData: (OFData *)data
1478  runLoopMode: (OFRunLoopMode)runLoopMode
1479  block: (OFStreamAsyncWriteDataBlock)block
1480  OF_DEPRECATED(ObjFW, 1, 2,
1481  "Use -[asyncWriteData:runLoopMode:handler:] instead");
1482 
1495 - (void)asyncWriteData: (OFData *)data
1496  runLoopMode: (OFRunLoopMode)runLoopMode
1497  handler: (OFStreamDataWrittenHandler)handler;
1498 
1512 - (void)asyncWriteString: (OFString *)string
1513  block: (OFStreamAsyncWriteStringBlock)block
1514  OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteString:handler:] instead");
1515 
1527 - (void)asyncWriteString: (OFString *)string
1528  handler: (OFStreamStringWrittenHandler)handler;
1529 
1546 - (void)asyncWriteString: (OFString *)string
1547  encoding: (OFStringEncoding)encoding
1548  block: (OFStreamAsyncWriteStringBlock)block
1549  OF_DEPRECATED(ObjFW, 1, 2,
1550  "Use -[asyncWriteString:encoding:handler:] instead");
1551 
1566 - (void)asyncWriteString: (OFString *)string
1567  encoding: (OFStringEncoding)encoding
1568  handler: (OFStreamStringWrittenHandler)handler;
1569 
1587 - (void)asyncWriteString: (OFString *)string
1588  encoding: (OFStringEncoding)encoding
1589  runLoopMode: (OFRunLoopMode)runLoopMode
1590  block: (OFStreamAsyncWriteStringBlock)block
1591  OF_DEPRECATED(ObjFW, 1, 2,
1592  "Use -[asyncWriteString:encoding:runLoopMode:handler:] instead");
1593 
1609 - (void)asyncWriteString: (OFString *)string
1610  encoding: (OFStringEncoding)encoding
1611  runLoopMode: (OFRunLoopMode)runLoopMode
1612  handler: (OFStreamStringWrittenHandler)handler;
1613 # endif
1614 #endif
1615 
1625 - (void)writeInt8: (uint8_t)int8;
1626 
1636 - (void)writeBigEndianInt16: (uint16_t)int16;
1637 
1647 - (void)writeBigEndianInt32: (uint32_t)int32;
1648 
1658 - (void)writeBigEndianInt64: (uint64_t)int64;
1659 
1669 - (void)writeBigEndianFloat: (float)float_;
1670 
1680 - (void)writeBigEndianDouble: (double)double_;
1681 
1691 - (void)writeLittleEndianInt16: (uint16_t)int16;
1692 
1702 - (void)writeLittleEndianInt32: (uint32_t)int32;
1703 
1713 - (void)writeLittleEndianInt64: (uint64_t)int64;
1714 
1724 - (void)writeLittleEndianFloat: (float)float_;
1725 
1735 - (void)writeLittleEndianDouble: (double)double_;
1736 
1746 - (void)writeData: (OFData *)data;
1747 
1757 - (void)writeString: (OFString *)string;
1758 
1770 - (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;
1771 
1781 - (void)writeLine: (OFString *)string;
1782 
1794 - (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;
1795 
1810 - (void)writeFormat: (OFConstantString *)format, ...;
1811 
1827 - (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;
1828 
1829 #ifdef OF_HAVE_SOCKETS
1830 
1833 - (void)cancelAsyncRequests;
1834 #endif
1835 
1857 - (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;
1858 
1866 - (void)close;
1867 
1882 - (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;
1883 
1898 - (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;
1899 
1910 - (bool)lowlevelIsAtEndOfStream;
1911 
1923 - (bool)lowlevelHasDataInReadBuffer;
1924 @end
1925 
1926 OF_ASSUME_NONNULL_END
bool(^ OFStreamAsyncReadBlock)(size_t length, id exception)
A block which is called when data was read asynchronously from a stream.
Definition: OFStream.h:55
OFStringEncoding
The encoding of a string.
Definition: OFString.h:65
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:41
The root class for all other classes inside ObjFW.
Definition: OFObject.h:690
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
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
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
A base class for different types of streams.
Definition: OFStream.h:278
A class for handling strings.
Definition: OFString.h:142
OFData *(^ OFStreamAsyncWriteDataBlock)(size_t bytesWritten, id exception)
A block which is called when data was written asynchronously to a stream.
Definition: OFStream.h:115
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
bool(^ OFStreamAsyncReadLineBlock)(OFString *line, id exception)
A block which is called when a line was read asynchronously from a stream.
Definition: OFStream.h:98
A protocol for the creation of copies.
Definition: OFObject.h:1350
A class for storing arbitrary data in an array.
Definition: OFData.h:45
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