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)
53 typedef bool (^OFStreamAsyncReadBlock)(size_t length, id _Nullable exception);
54 
65 typedef bool (^OFStreamAsyncReadLineBlock)(OFString *_Nullable line,
66  id _Nullable exception);
67 
79 typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(size_t bytesWritten,
80  id _Nullable exception);
81 
94  size_t bytesWritten, id _Nullable exception);
95 #endif
96 
103 @optional
114 - (bool)stream: (OFStream *)stream
115  didReadIntoBuffer: (void *)buffer
116  length: (size_t)length
117  exception: (nullable id)exception;
118 
129 - (bool)stream: (OFStream *)stream
130  didReadLine: (nullable OFString *)line
131  exception: (nullable id)exception;
132 
145 - (nullable OFData *)stream: (OFStream *)stream
146  didWriteData: (OFData *)data
147  bytesWritten: (size_t)bytesWritten
148  exception: (nullable id)exception;
149 
163 - (nullable OFString *)stream: (OFStream *)stream
164  didWriteString: (OFString *)string
165  encoding: (OFStringEncoding)encoding
166  bytesWritten: (size_t)bytesWritten
167  exception: (nullable id)exception;
168 @end
169 
191 {
192  bool _canBlock;
193  id _Nullable _delegate;
194 #ifndef OF_SEEKABLE_STREAM_M
195 @private
196 #endif
197  char *_Nullable _readBuffer, *_Nullable _readBufferMemory;
198  char *_Nullable _writeBuffer;
199  size_t _readBufferLength, _writeBufferLength;
200  bool _buffersWrites, _waitingForDelimiter;
201  OF_RESERVE_IVARS(OFStream, 4)
202 }
203 
207 @property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream;
208 
212 @property (nonatomic) bool buffersWrites;
213 
217 @property (readonly, nonatomic) bool hasDataInReadBuffer;
218 
228 @property (nonatomic) bool canBlock;
229 
236 @property OF_NULLABLE_PROPERTY (assign, nonatomic)
237  id <OFStreamDelegate> delegate;
238 
257 - (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;
258 
278  - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;
279 
280 #ifdef OF_HAVE_SOCKETS
301 - (void)asyncReadIntoBuffer: (void *)buffer length: (size_t)length;
302 
324 - (void)asyncReadIntoBuffer: (void *)buffer
325  length: (size_t)length
326  runLoopMode: (OFRunLoopMode)runLoopMode;
327 
344 - (void)asyncReadIntoBuffer: (void *)buffer exactLength: (size_t)length;
345 
363 - (void)asyncReadIntoBuffer: (void *)buffer
364  exactLength: (size_t)length
365  runLoopMode: (OFRunLoopMode)runLoopMode;
366 
367 # ifdef OF_HAVE_BLOCKS
393 - (void)asyncReadIntoBuffer: (void *)buffer
394  length: (size_t)length
395  block: (OFStreamAsyncReadBlock)block;
396 
423 - (void)asyncReadIntoBuffer: (void *)buffer
424  length: (size_t)length
425  runLoopMode: (OFRunLoopMode)runLoopMode
426  block: (OFStreamAsyncReadBlock)block;
427 
449 - (void)asyncReadIntoBuffer: (void *)buffer
450  exactLength: (size_t)length
451  block: (OFStreamAsyncReadBlock)block;
452 
475 - (void)asyncReadIntoBuffer: (void *)buffer
476  exactLength: (size_t)length
477  runLoopMode: (OFRunLoopMode)runLoopMode
478  block: (OFStreamAsyncReadBlock)block;
479 # endif
480 #endif
481 
494 - (uint8_t)readInt8;
495 
508 - (uint16_t)readBigEndianInt16;
509 
522 - (uint32_t)readBigEndianInt32;
523 
536 - (uint64_t)readBigEndianInt64;
537 
550 - (float)readBigEndianFloat;
551 
564 - (double)readBigEndianDouble;
565 
578 - (uint16_t)readLittleEndianInt16;
579 
592 - (uint32_t)readLittleEndianInt32;
593 
606 - (uint64_t)readLittleEndianInt64;
607 
620 - (float)readLittleEndianFloat;
621 
634 - (double)readLittleEndianDouble;
635 
650 - (OFData *)readDataWithCount: (size_t)count;
651 
667 - (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;
668 
677 - (OFData *)readDataUntilEndOfStream;
678 
699 - (OFString *)readStringWithLength: (size_t)length;
700 
722 - (OFString *)readStringWithLength: (size_t)length
723  encoding: (OFStringEncoding)encoding;
724 
735 - (nullable OFString *)readLine;
736 
749 - (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;
750 
751 #ifdef OF_HAVE_SOCKETS
759 - (void)asyncReadLine;
760 
770 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding;
771 
782 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
783  runLoopMode: (OFRunLoopMode)runLoopMode;
784 
785 # ifdef OF_HAVE_BLOCKS
799 - (void)asyncReadLineWithBlock: (OFStreamAsyncReadLineBlock)block;
800 
815 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
816  block: (OFStreamAsyncReadLineBlock)block;
817 
833 - (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
834  runLoopMode: (OFRunLoopMode)runLoopMode
835  block: (OFStreamAsyncReadLineBlock)block;
836 # endif
837 #endif
838 
850 - (nullable OFString *)tryReadLine;
851 
865 - (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;
866 
879 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;
880 
894 - (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
895  encoding: (OFStringEncoding)encoding;
896 
910 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;
911 
926 - (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
927  encoding: (OFStringEncoding)encoding;
928 
936 - (bool)flushWriteBuffer;
937 
953 - (void)writeBuffer: (const void *)buffer length: (size_t)length;
954 
955 #ifdef OF_HAVE_SOCKETS
964 - (void)asyncWriteData: (OFData *)data;
965 
975 - (void)asyncWriteData: (OFData *)data
976  runLoopMode: (OFRunLoopMode)runLoopMode;
977 
986 - (void)asyncWriteString: (OFString *)string;
987 
999 - (void)asyncWriteString: (OFString *)string
1000  encoding: (OFStringEncoding)encoding;
1001 
1014 - (void)asyncWriteString: (OFString *)string
1015  encoding: (OFStringEncoding)encoding
1016  runLoopMode: (OFRunLoopMode)runLoopMode;
1017 
1018 # ifdef OF_HAVE_BLOCKS
1030 - (void)asyncWriteData: (OFData *)data
1031  block: (OFStreamAsyncWriteDataBlock)block;
1032 
1045 - (void)asyncWriteData: (OFData *)data
1046  runLoopMode: (OFRunLoopMode)runLoopMode
1047  block: (OFStreamAsyncWriteDataBlock)block;
1048 
1060 - (void)asyncWriteString: (OFString *)string
1061  block: (OFStreamAsyncWriteStringBlock)block;
1062 
1077 - (void)asyncWriteString: (OFString *)string
1078  encoding: (OFStringEncoding)encoding
1079  block: (OFStreamAsyncWriteStringBlock)block;
1080 
1096 - (void)asyncWriteString: (OFString *)string
1097  encoding: (OFStringEncoding)encoding
1098  runLoopMode: (OFRunLoopMode)runLoopMode
1099  block: (OFStreamAsyncWriteStringBlock)block;
1100 # endif
1101 #endif
1102 
1112 - (void)writeInt8: (uint8_t)int8;
1113 
1123 - (void)writeBigEndianInt16: (uint16_t)int16;
1124 
1134 - (void)writeBigEndianInt32: (uint32_t)int32;
1135 
1145 - (void)writeBigEndianInt64: (uint64_t)int64;
1146 
1156 - (void)writeBigEndianFloat: (float)float_;
1157 
1167 - (void)writeBigEndianDouble: (double)double_;
1168 
1178 - (void)writeLittleEndianInt16: (uint16_t)int16;
1179 
1189 - (void)writeLittleEndianInt32: (uint32_t)int32;
1190 
1200 - (void)writeLittleEndianInt64: (uint64_t)int64;
1201 
1211 - (void)writeLittleEndianFloat: (float)float_;
1212 
1222 - (void)writeLittleEndianDouble: (double)double_;
1223 
1233 - (void)writeData: (OFData *)data;
1234 
1244 - (void)writeString: (OFString *)string;
1245 
1257 - (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;
1258 
1268 - (void)writeLine: (OFString *)string;
1269 
1281 - (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;
1282 
1297 - (void)writeFormat: (OFConstantString *)format, ...;
1298 
1314 - (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;
1315 
1316 #ifdef OF_HAVE_SOCKETS
1320 - (void)cancelAsyncRequests;
1321 #endif
1322 
1344 - (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;
1345 
1353 - (void)close;
1354 
1369 - (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;
1370 
1385 - (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;
1386 
1397 - (bool)lowlevelIsAtEndOfStream;
1398 
1410 - (bool)lowlevelHasDataInReadBuffer;
1411 @end
1412 
1413 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:53
OFString *(^ OFStreamAsyncWriteStringBlock)(size_t bytesWritten, id exception)
A block which is called when a string was written asynchronously to a stream.
Definition: OFStream.h:93
bool(^ OFStreamAsyncReadLineBlock)(OFString *line, id exception)
A block which is called when a line was read asynchronously from a stream.
Definition: OFStream.h:65
OFData *(^ OFStreamAsyncWriteDataBlock)(size_t bytesWritten, id exception)
A block which is called when data was written asynchronously to a stream.
Definition: OFStream.h:79
OFStringEncoding
The encoding of a string.
Definition: OFString.h:65
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:42
A class for storing arbitrary data in an array.
Definition: OFData.h:46
The root class for all other classes inside ObjFW.
Definition: OFObject.h:692
A base class for different types of streams.
Definition: OFStream.h:192
A class for handling strings.
Definition: OFString.h:139
A protocol for the creation of copies.
Definition: OFObject.h:1350
Definition: OFStream.h:102