OFStream.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008-2026 Jonathan Schleifer <js@nil.im>
 *
 * All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3.0 only,
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * version 3.0 for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3.0 along with this program. If not, see
 * <https://www.gnu.org/licenses/>.
 */
 
#ifndef __STDC_LIMIT_MACROS
# define __STDC_LIMIT_MACROS
#endif
#ifndef __STDC_CONSTANT_MACROS
# define __STDC_CONSTANT_MACROS
#endif
 
#include <stdarg.h>
 
#import "OFObject.h"
#import "OFString.h"
#import "OFRunLoop.h"
#ifdef OF_HAVE_SOCKETS
# import "OFKernelEventObserver.h"
#endif
 
OF_ASSUME_NONNULL_BEGIN

 
@class OFStream;
@class OFData;
 
#if defined(OF_HAVE_SOCKETS) && defined(OF_HAVE_BLOCKS)
typedef bool (^OFStreamAsyncReadBlock)(size_t length, id _Nullable exception)
    OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamReadHandler instead");

typedef bool (^OFStreamReadHandler)(OFStream *stream, void *buffer,
    size_t length, id _Nullable exception);

typedef bool (^OFStreamStringReadHandler)(OFStream *stream,
    OFString *_Nullable string, id _Nullable exception);

typedef bool (^OFStreamAsyncReadLineBlock)(OFString *_Nullable line,
    id _Nullable exception)
    OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringReadHandler instead");

typedef OFData *_Nullable (^OFStreamAsyncWriteDataBlock)(size_t bytesWritten,
    id _Nullable exception)
    OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamDataWrittenHandler instead");

typedef OFData *_Nullable (^OFStreamDataWrittenHandler)(OFStream *stream,
    OFData *data, size_t bytesWritten, id _Nullable exception);

typedef OFString *_Nullable (^OFStreamAsyncWriteStringBlock)(
    size_t bytesWritten, id _Nullable exception)
    OF_DEPRECATED(ObjFW, 1, 2, "Use OFStreamStringWrittenHandler instead");

typedef OFString *_Nullable (^OFStreamStringWrittenHandler)(OFStream *stream,
    OFString *string, OFStringEncoding encoding, size_t bytesWritten,
    id _Nullable exception);
#endif

@protocol OFStreamDelegate <OFObject>
@optional
-      (bool)stream: (OFStream *)stream
  didReadIntoBuffer: (void *)buffer
         length: (size_t)length
      exception: (nullable id)exception;

-  (bool)stream: (OFStream *)stream
  didReadString: (nullable OFString *)string
      exception: (nullable id)exception;

- (bool)stream: (OFStream *)stream
   didReadLine: (nullable OFString *)line
     exception: (nullable id)exception;

- (nullable OFData *)stream: (OFStream *)stream
           didWriteData: (OFData *)data
           bytesWritten: (size_t)bytesWritten
          exception: (nullable id)exception;

- (nullable OFString *)stream: (OFStream *)stream
           didWriteString: (OFString *)string
             encoding: (OFStringEncoding)encoding
         bytesWritten: (size_t)bytesWritten
            exception: (nullable id)exception;
@end

@interface OFStream: OFObject <OFCopying>
{
    bool _canBlock;
    id _Nullable _delegate;
#ifndef OF_SEEKABLE_STREAM_M
@private
#endif
    char *_Nullable _readBuffer, *_Nullable _readBufferMemory;
    char *_Nullable _writeBuffer;
    size_t _readBufferLength, _writeBufferLength;
    bool _buffersWrites, _waitingForDelimiter;
@private
    uintptr_t _encoding;
    uintptr_t _allowsLossyEncoding;
    OF_RESERVE_IVARS(OFStream, 2)
}

@property (readonly, nonatomic, getter=isAtEndOfStream) bool atEndOfStream;

@property (nonatomic) bool buffersWrites;

@property (readonly, nonatomic) bool hasDataInReadBuffer;

@property (nonatomic) OFStringEncoding encoding;

@property (nonatomic) bool allowsLossyEncoding;

@property (nonatomic) bool canBlock;

@property OF_NULLABLE_PROPERTY (assign, nonatomic)
    id <OFStreamDelegate> delegate;

- (size_t)readIntoBuffer: (void *)buffer length: (size_t)length;

 - (void)readIntoBuffer: (void *)buffer exactLength: (size_t)length;
 
#ifdef OF_HAVE_SOCKETS
- (void)asyncReadIntoBuffer: (void *)buffer length: (size_t)length;

- (void)asyncReadIntoBuffer: (void *)buffer
             length: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode;

- (void)asyncReadIntoBuffer: (void *)buffer exactLength: (size_t)length;

- (void)asyncReadIntoBuffer: (void *)buffer
        exactLength: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode;
 
# ifdef OF_HAVE_BLOCKS
- (void)asyncReadIntoBuffer: (void *)buffer
             length: (size_t)length
              block: (OFStreamAsyncReadBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadIntoBuffer:length:handler:] instead");

- (void)asyncReadIntoBuffer: (void *)buffer
             length: (size_t)length
            handler: (OFStreamReadHandler)handler;

- (void)asyncReadIntoBuffer: (void *)buffer
             length: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode
              block: (OFStreamAsyncReadBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadIntoBuffer:length:runLoopMode:handler:] instead");

- (void)asyncReadIntoBuffer: (void *)buffer
             length: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode
            handler: (OFStreamReadHandler)handler;

- (void)asyncReadIntoBuffer: (void *)buffer
        exactLength: (size_t)length
              block: (OFStreamAsyncReadBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadIntoBuffer:exactLength:handler:] instead");

- (void)asyncReadIntoBuffer: (void *)buffer
        exactLength: (size_t)length
            handler: (OFStreamReadHandler)handler;

- (void)asyncReadIntoBuffer: (void *)buffer
        exactLength: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode
              block: (OFStreamAsyncReadBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadIntoBuffer:exactLength:runLoopMode:handler: instead]");

- (void)asyncReadIntoBuffer: (void *)buffer
        exactLength: (size_t)length
        runLoopMode: (OFRunLoopMode)runLoopMode
            handler: (OFStreamReadHandler)handler;
# endif
#endif

- (uint8_t)readInt8;

- (uint16_t)readBigEndianInt16;

- (uint32_t)readBigEndianInt32;

- (uint64_t)readBigEndianInt64;

- (float)readBigEndianFloat;

- (double)readBigEndianDouble;

- (uint16_t)readLittleEndianInt16;

- (uint32_t)readLittleEndianInt32;

- (uint64_t)readLittleEndianInt64;

- (float)readLittleEndianFloat;

- (double)readLittleEndianDouble;

- (OFData *)readDataWithCount: (size_t)count;

- (OFData *)readDataWithItemSize: (size_t)itemSize count: (size_t)count;

- (OFData *)readDataUntilEndOfStream;

- (OFString *)readString;

- (OFString *)readStringWithEncoding: (OFStringEncoding)encoding;

- (OFString *)readStringWithLength: (size_t)length;

- (OFString *)readStringWithLength: (size_t)length
              encoding: (OFStringEncoding)encoding;

- (nullable OFString *)readLine;

- (nullable OFString *)readLineWithEncoding: (OFStringEncoding)encoding;
 
#ifdef OF_HAVE_SOCKETS
- (void)asyncReadString;

- (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding;

- (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
            runLoopMode: (OFRunLoopMode)runLoopMode;

- (void)asyncReadLine;

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding;

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
              runLoopMode: (OFRunLoopMode)runLoopMode;
 
# ifdef OF_HAVE_BLOCKS
- (void)asyncReadStringWithHandler: (OFStreamStringReadHandler)handler;

- (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
                handler: (OFStreamStringReadHandler)handler;

- (void)asyncReadStringWithEncoding: (OFStringEncoding)encoding
            runLoopMode: (OFRunLoopMode)runLoopMode
                handler: (OFStreamStringReadHandler)handler;

- (void)asyncReadLineWithBlock: (OFStreamAsyncReadLineBlock)block
    OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncReadLineWithHandler:] instead");

- (void)asyncReadLineWithHandler: (OFStreamStringReadHandler)handler;

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
                block: (OFStreamAsyncReadLineBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadLineWithEncoding:handler:] instead");

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
              handler: (OFStreamStringReadHandler)handler;

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
              runLoopMode: (OFRunLoopMode)runLoopMode
                block: (OFStreamAsyncReadLineBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncReadLineWithEncoding:runLoopMode:handler:] instead");

- (void)asyncReadLineWithEncoding: (OFStringEncoding)encoding
              runLoopMode: (OFRunLoopMode)runLoopMode
              handler: (OFStreamStringReadHandler)handler;
# endif
#endif

- (OFString *)tryReadString;

- (OFString *)tryReadStringWithEncoding: (OFStringEncoding)encoding;

- (nullable OFString *)tryReadLine;

- (nullable OFString *)tryReadLineWithEncoding: (OFStringEncoding)encoding;

- (nullable OFString *)readUntilDelimiter: (OFString *)delimiter;

- (nullable OFString *)readUntilDelimiter: (OFString *)delimiter
                 encoding: (OFStringEncoding)encoding;

- (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter;

- (nullable OFString *)tryReadUntilDelimiter: (OFString *)delimiter
                    encoding: (OFStringEncoding)encoding;

- (bool)flushWriteBuffer;

- (void)writeBuffer: (const void *)buffer length: (size_t)length;
 
#ifdef OF_HAVE_SOCKETS
- (void)asyncWriteData: (OFData *)data;

- (void)asyncWriteData: (OFData *)data
       runLoopMode: (OFRunLoopMode)runLoopMode;

- (void)asyncWriteString: (OFString *)string;

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding;

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding
         runLoopMode: (OFRunLoopMode)runLoopMode;
 
# ifdef OF_HAVE_BLOCKS
- (void)asyncWriteData: (OFData *)data
         block: (OFStreamAsyncWriteDataBlock)block
    OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteData:handler:] instead");

- (void)asyncWriteData: (OFData *)data
           handler: (OFStreamDataWrittenHandler)handler;

- (void)asyncWriteData: (OFData *)data
       runLoopMode: (OFRunLoopMode)runLoopMode
         block: (OFStreamAsyncWriteDataBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncWriteData:runLoopMode:handler:] instead");

- (void)asyncWriteData: (OFData *)data
       runLoopMode: (OFRunLoopMode)runLoopMode
           handler: (OFStreamDataWrittenHandler)handler;

- (void)asyncWriteString: (OFString *)string
           block: (OFStreamAsyncWriteStringBlock)block
    OF_DEPRECATED(ObjFW, 1, 2, "Use -[asyncWriteString:handler:] instead");

- (void)asyncWriteString: (OFString *)string
         handler: (OFStreamStringWrittenHandler)handler;

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding
           block: (OFStreamAsyncWriteStringBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncWriteString:encoding:handler:] instead");

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding
         handler: (OFStreamStringWrittenHandler)handler;

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding
         runLoopMode: (OFRunLoopMode)runLoopMode
           block: (OFStreamAsyncWriteStringBlock)block
    OF_DEPRECATED(ObjFW, 1, 2,
    "Use -[asyncWriteString:encoding:runLoopMode:handler:] instead");

- (void)asyncWriteString: (OFString *)string
        encoding: (OFStringEncoding)encoding
         runLoopMode: (OFRunLoopMode)runLoopMode
         handler: (OFStreamStringWrittenHandler)handler;
# endif
#endif

- (void)writeInt8: (uint8_t)int8;

- (void)writeBigEndianInt16: (uint16_t)int16;

- (void)writeBigEndianInt32: (uint32_t)int32;

- (void)writeBigEndianInt64: (uint64_t)int64;

- (void)writeBigEndianFloat: (float)float_;

- (void)writeBigEndianDouble: (double)double_;

- (void)writeLittleEndianInt16: (uint16_t)int16;

- (void)writeLittleEndianInt32: (uint32_t)int32;

- (void)writeLittleEndianInt64: (uint64_t)int64;

- (void)writeLittleEndianFloat: (float)float_;

- (void)writeLittleEndianDouble: (double)double_;

- (void)writeData: (OFData *)data;

- (void)writeString: (OFString *)string;

- (void)writeString: (OFString *)string encoding: (OFStringEncoding)encoding;

- (void)writeLine: (OFString *)string;

- (void)writeLine: (OFString *)string encoding: (OFStringEncoding)encoding;

- (void)writeFormat: (OFConstantString *)format, ...;

- (void)writeFormat: (OFConstantString *)format arguments: (va_list)arguments;
 
#ifdef OF_HAVE_SOCKETS
- (void)cancelAsyncRequests;
#endif

- (void)unreadFromBuffer: (const void *)buffer length: (size_t)length;

- (void)close;

- (size_t)lowlevelReadIntoBuffer: (void *)buffer length: (size_t)length;

- (size_t)lowlevelWriteBuffer: (const void *)buffer length: (size_t)length;

- (bool)lowlevelIsAtEndOfStream;

- (bool)lowlevelHasDataInReadBuffer;
@end
 
OF_ASSUME_NONNULL_END