CFStream.h

   1 /*
   2  * Copyright (c) 2010 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFStream.h
  25         Copyright (c) 2000-2009, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFSTREAM__)
  29 #define __COREFOUNDATION_CFSTREAM__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFString.h>
  33 #include <CoreFoundation/CFDictionary.h>
  34 #include <CoreFoundation/CFURL.h>
  35 #include <CoreFoundation/CFRunLoop.h>
  36 #include <CoreFoundation/CFSocket.h>
  37 #include <CoreFoundation/CFError.h>
  38
  39 CF_EXTERN_C_BEGIN
  40
  41 enum {
  42     kCFStreamStatusNotOpen = 0,
  43     kCFStreamStatusOpening,  /* open is in-progress */
  44     kCFStreamStatusOpen,
  45     kCFStreamStatusReading,
  46     kCFStreamStatusWriting,
  47     kCFStreamStatusAtEnd,    /* no further bytes can be read/written */
  48     kCFStreamStatusClosed,
  49     kCFStreamStatusError
  50 };
  51 typedef CFIndex CFStreamStatus;
  52
  53 enum {
  54     kCFStreamEventNone = 0,
  55     kCFStreamEventOpenCompleted = 1,
  56     kCFStreamEventHasBytesAvailable = 2,
  57     kCFStreamEventCanAcceptBytes = 4,
  58     kCFStreamEventErrorOccurred = 8,
  59     kCFStreamEventEndEncountered = 16
  60 };
  61 typedef CFOptionFlags CFStreamEventType;
  62
  63 typedef struct {
  64     CFIndex version;
  65     void *info;
  66     void *(*retain)(void *info);
  67     void (*release)(void *info);
  68     CFStringRef (*copyDescription)(void *info);
  69 } CFStreamClientContext;
  70
  71 typedef struct __CFReadStream * CFReadStreamRef;
  72 typedef struct __CFWriteStream * CFWriteStreamRef;
  73
  74 typedef void (*CFReadStreamClientCallBack)(CFReadStreamRef stream, CFStreamEventType type, void *clientCallBackInfo);
  75 typedef void (*CFWriteStreamClientCallBack)(CFWriteStreamRef stream, CFStreamEventType type, void *clientCallBackInfo);
  76
  77 CF_EXPORT
  78 CFTypeID CFReadStreamGetTypeID(void);
  79 CF_EXPORT
  80 CFTypeID CFWriteStreamGetTypeID(void);
  81
  82 /* Memory streams */
  83
  84 /* Value will be a CFData containing all bytes thusfar written; used to recover the data written to a memory write stream. */
  85 CF_EXPORT
  86 const CFStringRef kCFStreamPropertyDataWritten;
  87
  88 /* Pass kCFAllocatorNull for bytesDeallocator to prevent CFReadStream from deallocating bytes; otherwise, CFReadStream will deallocate bytes when the stream is destroyed */
  89 CF_EXPORT
  90 CFReadStreamRef CFReadStreamCreateWithBytesNoCopy(CFAllocatorRef alloc, const UInt8 *bytes, CFIndex length, CFAllocatorRef bytesDeallocator);
  91
  92 /* The stream writes into the buffer given; when bufferCapacity is exhausted, the stream is exhausted (status becomes kCFStreamStatusAtEnd) */
  93 CF_EXPORT
  94 CFWriteStreamRef CFWriteStreamCreateWithBuffer(CFAllocatorRef alloc, UInt8 *buffer, CFIndex bufferCapacity);
  95
  96 /* New buffers are allocated from bufferAllocator as bytes are written to the stream.  At any point, you can recover the bytes thusfar written by asking for the property kCFStreamPropertyDataWritten, above */
  97 CF_EXPORT
  98 CFWriteStreamRef CFWriteStreamCreateWithAllocatedBuffers(CFAllocatorRef alloc, CFAllocatorRef bufferAllocator);
  99
 100 /* File streams */
 101 CF_EXPORT
 102 CFReadStreamRef CFReadStreamCreateWithFile(CFAllocatorRef alloc, CFURLRef fileURL);
 103 CF_EXPORT
 104 CFWriteStreamRef CFWriteStreamCreateWithFile(CFAllocatorRef alloc, CFURLRef fileURL);
 105 CF_EXPORT
 106 void CFStreamCreateBoundPair(CFAllocatorRef alloc, CFReadStreamRef *readStream, CFWriteStreamRef *writeStream, CFIndex transferBufferSize);
 107
 108 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 109 /* Property for file write streams; value should be a CFBoolean.  Set to TRUE to append to a file, rather than to replace its contents */
 110 CF_EXPORT
 111 const CFStringRef kCFStreamPropertyAppendToFile;
 112 #endif
 113
 114 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 115
 116 CF_EXPORT const CFStringRef kCFStreamPropertyFileCurrentOffset AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;   // Value is a CFNumber
 117
 118 #endif
 119
 120 /* Socket stream properties */
 121
 122 /* Value will be a CFData containing the native handle */
 123 CF_EXPORT
 124 const CFStringRef kCFStreamPropertySocketNativeHandle;
 125
 126 /* Value will be a CFString, or NULL if unknown */
 127 CF_EXPORT
 128 const CFStringRef kCFStreamPropertySocketRemoteHostName;
 129
 130 /* Value will be a CFNumber, or NULL if unknown */
 131 CF_EXPORT
 132 const CFStringRef kCFStreamPropertySocketRemotePortNumber;
 133
 134 /* Socket streams; the returned streams are paired such that they use the same socket; pass NULL if you want only the read stream or the write stream */
 135 CF_EXPORT
 136 void CFStreamCreatePairWithSocket(CFAllocatorRef alloc, CFSocketNativeHandle sock, CFReadStreamRef *readStream, CFWriteStreamRef *writeStream);
 137 CF_EXPORT
 138 void CFStreamCreatePairWithSocketToHost(CFAllocatorRef alloc, CFStringRef host, UInt32 port, CFReadStreamRef *readStream, CFWriteStreamRef *writeStream);
 139 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 140 CF_EXPORT
 141 void CFStreamCreatePairWithPeerSocketSignature(CFAllocatorRef alloc, const CFSocketSignature *signature, CFReadStreamRef *readStream, CFWriteStreamRef *writeStream);
 142 #endif
 143
 144
 145 /* Returns the current state of the stream */
 146 CF_EXPORT
 147 CFStreamStatus CFReadStreamGetStatus(CFReadStreamRef stream);
 148 CF_EXPORT
 149 CFStreamStatus CFWriteStreamGetStatus(CFWriteStreamRef stream);
 150
 151 /* Returns NULL if no error has occurred; otherwise returns the error. */
 152 CF_EXPORT
 153 CFErrorRef CFReadStreamCopyError(CFReadStreamRef stream) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
 154 CF_EXPORT
 155 CFErrorRef CFWriteStreamCopyError(CFWriteStreamRef stream) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
 156
 157 /* Returns success/failure.  Opening a stream causes it to reserve all the system
 158    resources it requires.  If the stream can open non-blocking, this will always
 159    return TRUE; listen to the run loop source to find out when the open completes
 160    and whether it was successful, or poll using CFRead/WriteStreamGetStatus(), waiting
 161    for a status of kCFStreamStatusOpen or kCFStreamStatusError.  */
 162 CF_EXPORT
 163 Boolean CFReadStreamOpen(CFReadStreamRef stream);
 164 CF_EXPORT
 165 Boolean CFWriteStreamOpen(CFWriteStreamRef stream);
 166
 167 /* Terminates the flow of bytes; releases any system resources required by the
 168    stream.  The stream may not fail to close.  You may call CFStreamClose() to
 169    effectively abort a stream. */
 170 CF_EXPORT
 171 void CFReadStreamClose(CFReadStreamRef stream);
 172 CF_EXPORT
 173 void CFWriteStreamClose(CFWriteStreamRef stream);
 174
 175 /* Whether there is data currently available for reading; returns TRUE if it's
 176    impossible to tell without trying */
 177 CF_EXPORT
 178 Boolean CFReadStreamHasBytesAvailable(CFReadStreamRef stream);
 179
 180 /* Returns the number of bytes read, or -1 if an error occurs preventing any
 181    bytes from being read, or 0 if the stream's end was encountered.
 182    It is an error to try and read from a stream that hasn't been opened first.
 183    This call will block until at least one byte is available; it will NOT block
 184    until the entire buffer can be filled.  To avoid blocking, either poll using
 185    CFReadStreamHasBytesAvailable() or use the run loop and listen for the
 186    kCFStreamCanRead event for notification of data available. */
 187 CF_EXPORT
 188 CFIndex CFReadStreamRead(CFReadStreamRef stream, UInt8 *buffer, CFIndex bufferLength);
 189
 190 /* Returns a pointer to an internal buffer if possible (setting *numBytesRead
 191    to the length of the returned buffer), otherwise returns NULL; guaranteed
 192    to return in O(1).  Bytes returned in the buffer are considered read from
 193    the stream; if maxBytesToRead is greater than 0, not more than maxBytesToRead
 194    will be returned.  If maxBytesToRead is less than or equal to zero, as many bytes
 195    as are readily available will be returned.  The returned buffer is good only
 196    until the next stream operation called on the stream.  Caller should neither
 197    change the contents of the returned buffer nor attempt to deallocate the buffer;
 198    it is still owned by the stream. */
 199 CF_EXPORT
 200 const UInt8 *CFReadStreamGetBuffer(CFReadStreamRef stream, CFIndex maxBytesToRead, CFIndex *numBytesRead);
 201
 202 /* Whether the stream can currently be written to without blocking;
 203    returns TRUE if it's impossible to tell without trying */
 204 CF_EXPORT
 205 Boolean CFWriteStreamCanAcceptBytes(CFWriteStreamRef stream);
 206
 207 /* Returns the number of bytes successfully written, -1 if an error has
 208    occurred, or 0 if the stream has been filled to capacity (for fixed-length
 209    streams).  If the stream is not full, this call will block until at least
 210    one byte is written.  To avoid blocking, either poll via CFWriteStreamCanAcceptBytes
 211    or use the run loop and listen for the kCFStreamCanWrite event. */
 212 CF_EXPORT
 213 CFIndex CFWriteStreamWrite(CFWriteStreamRef stream, const UInt8 *buffer, CFIndex bufferLength);
 214
 215 /* Particular streams can name properties and assign meanings to them; you
 216    access these properties through the following calls.  A property is any interesting
 217    information about the stream other than the data being transmitted itself.
 218    Examples include the headers from an HTTP transmission, or the expected
 219    number of bytes, or permission information, etc.  Properties that can be set
 220    configure the behavior of the stream, and may only be settable at particular times
 221    (like before the stream has been opened).  See the documentation for particular
 222    properties to determine their get- and set-ability. */
 223 CF_EXPORT
 224 CFTypeRef CFReadStreamCopyProperty(CFReadStreamRef stream, CFStringRef propertyName);
 225 CF_EXPORT
 226 CFTypeRef CFWriteStreamCopyProperty(CFWriteStreamRef stream, CFStringRef propertyName);
 227
 228 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 229 /* Returns TRUE if the stream recognizes and accepts the given property-value pair;
 230    FALSE otherwise. */
 231 CF_EXPORT
 232 Boolean CFReadStreamSetProperty(CFReadStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue);
 233 CF_EXPORT
 234 Boolean CFWriteStreamSetProperty(CFWriteStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue);
 235 #endif
 236
 237 /* Asynchronous processing - If you wish to neither poll nor block, you may register
 238    a client to hear about interesting events that occur on a stream.  Only one client
 239    per stream is allowed; registering a new client replaces the previous one.
 240
 241    Once you have set a client, you need to schedule a run loop on which that client
 242    can be notified.  You may schedule multiple run loops (for instance, if you are
 243    using a thread pool).  The client callback will be triggered via one of the scheduled
 244    run loops; It is the caller's responsibility to ensure that at least one of the
 245    scheduled run loops is being run.
 246
 247    NOTE: Unlike other CoreFoundation APIs, pasing a NULL clientContext here will remove
 248    the client.  If you do not care about the client context (i.e. your only concern
 249    is that your callback be called), you should pass in a valid context where every
 250    entry is 0 or NULL.
 251
 252 */
 253
 254 CF_EXPORT
 255 Boolean CFReadStreamSetClient(CFReadStreamRef stream, CFOptionFlags streamEvents, CFReadStreamClientCallBack clientCB, CFStreamClientContext *clientContext);
 256 CF_EXPORT
 257 Boolean CFWriteStreamSetClient(CFWriteStreamRef stream, CFOptionFlags streamEvents, CFWriteStreamClientCallBack clientCB, CFStreamClientContext *clientContext);
 258
 259 CF_EXPORT
 260 void CFReadStreamScheduleWithRunLoop(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode);
 261 CF_EXPORT
 262 void CFWriteStreamScheduleWithRunLoop(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode);
 263
 264 CF_EXPORT
 265 void CFReadStreamUnscheduleFromRunLoop(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode);
 266 CF_EXPORT
 267 void CFWriteStreamUnscheduleFromRunLoop(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode);
 268
 269
 270 /* The following API is deprecated starting in 10.5; please use CFRead/WriteStreamCopyError(), above, instead */
 271 enum {
 272     kCFStreamErrorDomainCustom = -1,      /* custom to the kind of stream in question */
 273     kCFStreamErrorDomainPOSIX = 1,        /* POSIX errno; interpret using <sys/errno.h> */
 274     kCFStreamErrorDomainMacOSStatus      /* OSStatus type from Carbon APIs; interpret using <MacTypes.h> */
 275 };
 276 typedef CFIndex CFStreamErrorDomain;
 277
 278 typedef struct {
 279     CFIndex domain;
 280     SInt32 error;
 281 } CFStreamError;
 282 CF_EXPORT
 283 CFStreamError CFReadStreamGetError(CFReadStreamRef stream);
 284 CF_EXPORT
 285 CFStreamError CFWriteStreamGetError(CFWriteStreamRef stream);
 286
 287
 288 CF_EXTERN_C_END
 289
 290 #endif /* ! __COREFOUNDATION_CFSTREAM__ */