EDStream


Inherits From:
NSObject
Declared In:
EDStream.h


Class Description

This class is meant to be used with sockets but it can work with all kinds of NSFileHandle. The main concept in EDStream is the conversion from raw data, chopped up into chunks of arbitrary size and delivered as NSData objects, into a stream of NSString objects representing meaningful units, lines for example. EDStream also contains functionality to simplify the implementation of common text-based internet protocols such as SMTP and NNTP.


Instance Variables

struct _EDSFlags flags;
NSFileHandle *fileHandle;
NSFileHandle *dumpHandle;
NSStringEncoding stringEncoding;
NSMutableData *recordBuffer;

flagsAll instance variables are private.
fileHandle
dumpHandle
stringEncoding
recordBuffer


Method Types

Creating streams
+ streamWithFileHandle:
+ streamConnectedToHost:port:
+ streamConnectedToHost:port:sendTimeout:receiveTimeout:
+ streamConnectedToHostWithName:port:
+ streamConnectedToHostWithName:port:sendTimeout:receiveTimeout:
- initWithFileHandle:
Managing the stream
- fileHandle
- close
Configuring the stream
- setStringEncoding:
- stringEncoding
- setLinebreakStyle:
- linebreakStyle
- setEnforcesCanonicalLinebreaks:
- enforcesCanonicalLinebreaks
- setEscapesLeadingDots:
- escapesLeadingDots
- setDumpFileHandle:
- dumpFileHandle
Reading/writing data
- availableData
- getRecordWithDelimiter:
- getRecordBuffer
- writeData:
Reading/writing strings
- availableString
- availableLine
- writeString:
- writeLine:
- writeFormat:


Class Methods

streamConnectedToHost:port:

+ (id)streamConnectedToHost:(NSHost *)host port:(unsigned short)port

Creates and returns a stream for an EDTCPSocket connected to port on host.


streamConnectedToHost:port:sendTimeout:receiveTimeout:

+ (id)streamConnectedToHost:(NSHost *)host port:(unsigned short)port sendTimeout:(NSTimeInterval)sendTimeout receiveTimeout:(NSTimeInterval)receiveTimeout

Creates and returns a stream for an EDTCPSocket connected to port on host. SendTimeout and receiveTimout are set on this socket.


streamConnectedToHostWithName:port:

+ (id)streamConnectedToHostWithName:(NSString *)hostname port:(unsigned short)port

Creates and returns a stream for an EDTCPSocket connected to port on the host with the name hostname.


streamConnectedToHostWithName:port:sendTimeout:receiveTimeout:

+ (id)streamConnectedToHostWithName:(NSString *)hostname port:(unsigned short)port sendTimeout:(NSTimeInterval)sendTimeout receiveTimeout:(NSTimeInterval)receiveTimeout

Creates and returns a stream for an EDTCPSocket connected to port on the host with the name hostname. SendTimeout and receiveTimout are set on this socket.


streamWithFileHandle:

+ (id)streamWithFileHandle:(NSFileHandle *)aFileHandle

Creates and returns a stream for aFileHandle.


Instance Methods

availableData

- (NSData *)availableData

Returns the data available through the stream. If the stream's file handle represents a file, it returns all data between the current file pointer and the end of the file. If it represents a communication channel, e.g. a socket, this method returns the contents of the communication buffer; blocking until some data is available if neccessary. (See availableData in NSFileHandle for further details.)

Note that if you used getRecordWithDelimiter: data might still be available in the record buffer; see getRecordBuffer for details. This method does not (by design) touch the record buffer. It is best not to mix availableData and getRecordWithDelimiter: calls.


availableLine

- (NSString *)availableLine

Reads and returns a string up to (and not including) the current linebreak sequence. If not enough data is available this method blocks until more data is received. Returns nil if no more data is available on the stream.


availableString

- (NSString *)availableString

Returns the data available through the stream converted into a string. If the stream's file handle represents a file, it returns all data between the current file pointer and the end of the file. If it represents a communication channel, e.g. a socket, this method returns the contents of the communication buffer; blocking until some data is available if neccessary. (See availableData in NSFileHandle for further details.)

Please read the description of setStringEncoding: before using this with multibyte character encodings.

You can mix availableString and availableLine without loosing data. However, availableString might block even if some data was available in the record buffer.


close

- (void)close

Closes the stream and its file handle; disallowing further communication. This does not automatically release the stream.


dumpFileHandle

- (NSFileHandle *)dumpFileHandle

Returns the "dump" file handle. All data read from or written to the real file handle is copied (written) to this file handle.


enforcesCanonicalLinebreaks

- (BOOL)enforcesCanonicalLinebreaks

Returns whether linebreak sequences are converted to canonical linebreak sequences when writing. See setEnforcesCanonicalLinebreaks: for details.


escapesLeadingDots

- (BOOL)escapesLeadingDots

Returns whether dots '.' at the beginning of a line are doubled. See setEscapesLeadingDots: for details.


fileHandle

- (NSFileHandle *)fileHandle

Returns the file handle the stream uses for reading and writing.


getRecordBuffer

- (NSData *)getRecordBuffer

Returns the contents of the record buffer and empties it. The record buffer contains all data that has been read from the stream but not requested through getRecordWithDelimiter: yet.


getRecordWithDelimiter:

- (NSData *)getRecordWithDelimiter:(NSData *)delimiter

Reads and returns data up to (and not including) delimiter. If not enough data is available this method blocks until more data is received. Returns nil if delimeter cannot be found in the remainder of the stream. In this case the remaining data is available through getRecordBuffer.


initWithFileHandle:

- (id)initWithFileHandle:(NSFileHandle *)aFileHandle

Initialises a newly allocated stream by setting its file handle to aFileHandle.


linebreakStyle

- (int)linebreakStyle

Returns the linebreak style used for communication. See setLinebreakStyle: for more details.


setDumpFileHandle:

- (void)setDumpFileHandle:(NSFileHandle *)aFileHandle

Sets aFileHandle as "dump" file handle. All data read from or written to the real file handle is copied (written) to this file handle.


setEnforcesCanonicalLinebreaks:

- (void)setEnforcesCanonicalLinebreaks:(BOOL)flag

If set to YES all linebreaks written to the stream, as strings or data objects, that are not canonical are automatically replaced by a canonical linebreak, i.e. CR+LF. Note that this only works if linebreakStyle is EDCanonicalLinebreakStyle and only affects data/strings written to the stream; no conversions take place while reading. The default is not to enforce canonical linebreaks.


setEscapesLeadingDots:

- (void)setEscapesLeadingDots:(BOOL)flag

If set to YES all dots '.' at the beginning of a line are doubled. This is required for protocols such as SMTP and NNTP when transmitting message bodies. The default is not to double leading dots.


setLinebreakStyle:

- (void)setLinebreakStyle:(int)aStyle

Sets the linebreak style used for communication. The following table lists all styles:

EDCanonicalLinebreakStyleCR+LF, most commonly used style
EDUnixLinebreakStyleLF only, common on UNIX and hence Mac OS X text files
EDMacintoshLinebreakStyleCR only, common for older Mac OS 9 text files

The linebreak style can be change during normal operation if required.


setStringEncoding:

- (void)setStringEncoding:(NSStringEncoding)encoding

Sets the string encoding used to convert to and from the data objects used on the network. The default is [NSString defaultCStringEncoding].

Note that for some string encodings sequences of bytes exist that cannot be transformed into a string. (An example is UTF-8 and a byte sequence ending with a byte that has bit 8 set.) EDStream uses the NSString's conversion methods and these nullify the entire sequence which means that an undefined number of characters around the "offending" one can be affected. This can also affect availableString if for some reason only part of a multibyte sequence becomes available. (Highly unlikely but possible.) An obvious workaround is to use availableLine when reading such character encodings.


stringEncoding

- (NSStringEncoding)stringEncoding

Returns the string encoding used to convert to and from the data objects used on the network.


writeData:

- (void)writeData:(NSData *)data

Synchronously writes data to the stream's file handle. (See writeData: in NSFileHandle for further details.) If enforcesCanonicalLinebreaks and/or escapesLeadingDots are set the appropriate conversions are carried out.


writeFormat:

- (void)writeFormat:(NSString *)format, ...

Creates a string from the printf style format and arguments, converts this into a data object with the current string encoding and writes it using writeData:.


writeLine:

- (void)writeLine:(NSString *)string

Converts string into a data object with the current string encoding and writes it using writeData: followed by a linebreak sequence determined by linebreakStyle.


writeString:

- (void)writeString:(NSString *)string

Converts string into a data object with the current string encoding and writes it using writeData:


Version 2.0 Copyright ©2002. All Rights Reserved.