CFStream.h

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