- Inherits From:
- NSObject
- Declared In:
- EDStream.h
struct _EDSFlags flags;
NSFileHandle *fileHandle;
NSFileHandle *dumpHandle;
NSStringEncoding stringEncoding;
NSMutableData *recordBuffer;
flags All instance variables are private. fileHandle dumpHandle stringEncoding recordBuffer
Creating streamsManaging the stream
- + streamWithFileHandle:
- + streamConnectedToHost:port:
- + streamConnectedToHost:port:sendTimeout:receiveTimeout:
- + streamConnectedToHostWithName:port:
- + streamConnectedToHostWithName:port:sendTimeout:receiveTimeout:
- - initWithFileHandle:
Configuring the stream
- - fileHandle
- - close
Reading/writing data
- - setStringEncoding:
- - stringEncoding
- - setLinebreakStyle:
- - linebreakStyle
- - setEnforcesCanonicalLinebreaks:
- - enforcesCanonicalLinebreaks
- - setEscapesLeadingDots:
- - escapesLeadingDots
- - setDumpFileHandle:
- - dumpFileHandle
Reading/writing strings
- - availableData
- - getRecordWithDelimiter:
- - getRecordBuffer
- - writeData:
- - availableString
- - availableLine
- - writeString:
- - writeLine:
- - writeFormat:
+ (id)streamConnectedToHost:(NSHost *)host port:(unsigned short)port
Creates and returns a stream for an EDTCPSocket connected to port on host.
+ (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.
+ (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.
+ (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.
+ (id)streamWithFileHandle:(NSFileHandle *)aFileHandle
Creates and returns a stream for aFileHandle.
- (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.
- (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.
- (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.
- (void)close
Closes the stream and its file handle; disallowing further communication. This does not automatically release the stream.
- (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.
- (BOOL)enforcesCanonicalLinebreaks
Returns whether linebreak sequences are converted to canonical linebreak sequences when writing. See setEnforcesCanonicalLinebreaks: for details.
- (BOOL)escapesLeadingDots
Returns whether dots '.' at the beginning of a line are doubled. See setEscapesLeadingDots: for details.
- (NSFileHandle *)fileHandle
Returns the file handle the stream uses for reading and writing.
- (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.
- (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.
- (id)initWithFileHandle:(NSFileHandle *)aFileHandle
Initialises a newly allocated stream by setting its file handle to aFileHandle.
- (int)linebreakStyle
Returns the linebreak style used for communication. See setLinebreakStyle: for more details.
- (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.
- (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.
- (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.
- (void)setLinebreakStyle:(int)aStyle
Sets the linebreak style used for communication. The following table lists all styles:
EDCanonicalLinebreakStyle | CR+LF, most commonly used style |
EDUnixLinebreakStyle | LF only, common on UNIX and hence Mac OS X text files |
EDMacintoshLinebreakStyle | CR only, common for older Mac OS 9 text files |
The linebreak style can be change during normal operation if required.
- (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.
- (NSStringEncoding)stringEncoding
Returns the string encoding used to convert to and from the data objects used on the network.
- (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.
- (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:.
- (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.
- (void)writeString:(NSString *)string
Converts string into a data object with the current string encoding and writes it using writeData: