AppServices.subproj/CFStream.h

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