ObjFW
Loading...
Searching...
No Matches
OFStream.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008-2025 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
36OF_ASSUME_NONNULL_BEGIN
37
40@class OFStream;
41@class OFData;
42
43#if defined(OF_HAVE_SOCKETS) && defined(OF_HAVE_BLOCKS)
55typedef bool (^OFStreamAsyncReadBlock)(size_t length, id _Nullable exception)
56 OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamReadHandler instead");
57
69typedef bool (^OFStreamReadHandler)(OFStream *stream, void *buffer,
70 size_t length, id _Nullable exception);
71
83typedef bool (^OFStreamStringReadHandler)(OFStream *stream,
84 OFString *_Nullable string, id _Nullable exception);
85
98typedef bool (^OFStreamAsyncReadLineBlock)(OFString *_Nullable line,
99 id _Nullable exception)
100 OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringReadHandler instead");
101
115typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(size_t bytesWritten,
116 id _Nullable exception)
117 OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamDataWrittenHandler instead");
118
132typedef OFData *_Nullable (^OFStreamDataWrittenHandler)(OFStream *stream,
133 OFData *data, size_t bytesWritten, id _Nullable exception);
134
148typedef OFString *_Nullable (^OFStreamAsyncWriteStringBlock)(
149 size_t bytesWritten, id _Nullable exception)
150 OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringWrittenHandler instead");
151
166typedef 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@protected
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
1936OF_ASSUME_NONNULL_END
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
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
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
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
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
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
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
Generated by doxygen 1.12.0