/CFSockets/CFStreamPair.h

  1// CFSockets CFStreamPair.h
  2//
  3// Copyright © 2012, 2013, Roy Ratcliffe, Pioneering Software, United Kingdom
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the “Software”), to deal
  7// in the Software without restriction, including without limitation the rights
  8// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9// copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12//	The above copyright notice and this permission notice shall be included in
 13//	all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND, EITHER
 16// EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 17// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO
 18// EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
 19// OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 20// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 21// DEALINGS IN THE SOFTWARE.
 22//
 23//------------------------------------------------------------------------------
 24
 25#import <Foundation/Foundation.h>
 26
 27@class CFStreamPair;
 28
 29@protocol CFStreamPairDelegate<NSObject>
 30@optional
 31
 32- (void)streamPair:(CFStreamPair *)streamPair hasBytesAvailable:(NSUInteger)bytesAvailable;
 33
 34- (void)streamPair:(CFStreamPair *)streamPair handleRequestEvent:(NSStreamEvent)eventCode;
 35- (void)streamPair:(CFStreamPair *)streamPair handleResponseEvent:(NSStreamEvent)eventCode;
 36
 37@end
 38
 39/**
 40 * Adds request-response semantics to a socket by encapsulating it with
 41 * an input-output stream pair.
 42 *
 43 * For TCP connections, the request input stream corresponds to the
 44 * request; _receive_ the request bytes from the request input, _send_ the
 45 * response to the response output stream.
 46 */
 47@interface CFStreamPair : NSObject<NSStreamDelegate>
 48
 49@property(weak, NS_NONATOMIC_IOSONLY) id<CFStreamPairDelegate> delegate;
 50@property(strong, NS_NONATOMIC_IOSONLY) NSInputStream *requestStream;
 51@property(strong, NS_NONATOMIC_IOSONLY) NSOutputStream *responseStream;
 52
 53- (id)initWithRequestStream:(NSInputStream *)requestStream responseStream:(NSOutputStream *)responseStream;
 54- (id)initWithSocketNativeHandle:(NSSocketNativeHandle)socketNativeHandle;
 55
 56/**
 57 * Opens the request and response streams, scheduling them for service within
 58 * the current run loop. You cannot reopen the streams.
 59 *
 60 * This method assumes that you have not already delegated, scheduled
 61 * or opened the underlying request-response stream pair.
 62 */
 63- (void)open;
 64
 65/**
 66 * Reverses the opening. Closes the request and response streams, removes them
 67 * from the current run loop. This assumes that you send `-close` from the same
 68 * thread as you sent the original `-open`.
 69 */
 70- (void)close;
 71
 72/**
 73 * Destructively receives bytes from the request buffer.
 74 */
 75- (NSData *)receiveAvailableBytes;
 76
 77/**
 78 * Special convenience method for receiving lines of text from the
 79 * request stream based on a given string encoding.
 80 *
 81 * The result includes any line termination characters. There could be
 82 * more than one termination character at the end of the line since some line
 83 * termination sequences span multiple characters.
 84 *
 85 * @result Answers `nil` if the request buffer does not yet contain a complete
 86 * line. Try again later.
 87 */
 88- (NSString *)receiveLineUsingEncoding:(NSStringEncoding)encoding;
 89
 90- (void)sendBytes:(NSData *)outputBytes;
 91
 92//-------------------------------------------------------------------- Overrides
 93
 94- (void)hasBytesAvailable;
 95- (void)hasSpaceAvailable;
 96- (void)sendBytes;
 97- (void)handleRequestEvent:(NSStreamEvent)eventCode;
 98- (void)handleResponseEvent:(NSStreamEvent)eventCode;
 99
100@end