Mac Developer Library

Developer

CoreFoundation Framework Reference CFReadStream Reference

Options
Deployment Target:

On This Page
Language:

CFReadStream Reference

CFReadStream provides an interface for reading a byte stream either synchronously or asynchronously. You can create streams that read bytes from a block of memory, a file, or a generic socket. All streams need to be opened, using CFReadStreamOpen, before reading.

Use CFWriteStream for writing byte streams. The CFNetwork framework defines an additional type of stream for reading responses to HTTP requests.

CFReadStream is “toll-free bridged” with its Cocoa Foundation counterpart, NSInputStream in NSInputStream Class Reference. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSInputStream * parameter, you can pass in a CFReadStreamRef, and in a function where you see a CFReadStreamRef parameter, you can pass in an NSInputStream instance. Note, however, that you may have either a delegate or callbacks but not both. See Toll-Free Bridged Types in Core Foundation Design Concepts for more information on toll-free bridging.

Functions

  • Creates a readable stream for a block of memory.

    Declaration

    Swift

    func CFReadStreamCreateWithBytesNoCopy(_ alloc: CFAllocator!, _ bytes: UnsafePointer<UInt8>, _ length: CFIndex, _ bytesDeallocator: CFAllocator!) -> CFReadStream!

    Objective-C

    CFReadStreamRef CFReadStreamCreateWithBytesNoCopy ( CFAllocatorRef alloc, const UInt8 *bytes, CFIndex length, CFAllocatorRef bytesDeallocator );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    bytes

    The memory buffer to read. This memory must exist for the lifetime of the new stream.

    length

    The size of bytes.

    bytesDeallocator

    The allocator to use to deallocate bytes when the stream is deallocated. Pass kCFAllocatorNull to prevent the stream from deallocating bytes.

    Return Value

    The new read stream, or NULL on failure. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Discussion

    You must open the stream, using CFReadStreamOpen, before reading from it.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Creates a readable stream for a file.

    Declaration

    Swift

    func CFReadStreamCreateWithFile(_ alloc: CFAllocator!, _ fileURL: CFURL!) -> CFReadStream!

    Objective-C

    CFReadStreamRef CFReadStreamCreateWithFile ( CFAllocatorRef alloc, CFURLRef fileURL );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    fileURL

    The URL of the file to read. The URL must use the file scheme.

    Return Value

    The new readable stream object, or NULL on failure. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Discussion

    You must open the stream, using CFReadStreamOpen, before reading from it.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Closes a readable stream.

    Declaration

    Swift

    func CFReadStreamClose(_ stream: CFReadStream!)

    Objective-C

    void CFReadStreamClose ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to close.

    Discussion

    This function terminates the flow of bytes and releases any system resources required by the stream. The stream is removed from any run loops in which it was scheduled. Once closed, the stream cannot be reopened.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Opens a stream for reading.

    Declaration

    Swift

    func CFReadStreamOpen(_ stream: CFReadStream!) -> Boolean

    Objective-C

    Boolean CFReadStreamOpen ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to open.

    Return Value

    TRUE if stream was successfully opened, FALSE otherwise. If stream is not in the kCFStreamStatusNotOpen state, this function returns FALSE.

    Discussion

    Opening a stream causes it to reserve all the system resources it requires. If the stream can open in the background without blocking, this function always returns true. To learn when a background open operation completes, you can either schedule the stream into a run loop with CFReadStreamScheduleWithRunLoop and wait for the stream’s client (set with CFReadStreamSetClient) to be notified or you can poll the stream using CFReadStreamGetStatus, waiting for a status of kCFStreamStatusOpen or kCFStreamStatusError.

    You do not need to wait until a stream has finished opening in the background before calling the CFReadStreamRead function. The read operation will simply block until the open has completed.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Reads data from a readable stream.

    Declaration

    Swift

    func CFReadStreamRead(_ stream: CFReadStream!, _ buffer: UnsafeMutablePointer<UInt8>, _ bufferLength: CFIndex) -> CFIndex

    Objective-C

    CFIndex CFReadStreamRead ( CFReadStreamRef stream, UInt8 *buffer, CFIndex bufferLength );

    Parameters

    stream

    The stream from which to read.

    buffer

    The buffer into which to place the data.

    bufferLength

    The size of buffer and the maximum number of bytes to read.

    Return Value

    The number of bytes read; 0 if the stream has reached its end; or -1 if either the stream is not open or an error occurs.

    Discussion

    If stream is in the process of opening, this function waits until it has completed. This function blocks until at least one byte is available; it does not block until buffer is filled. To avoid blocking, call this function only if CFReadStreamHasBytesAvailable returns TRUE or after the stream’s client (set with CFReadStreamSetClient) is notified of a kCFStreamEventHasBytesAvailable event.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Schedules a stream into a run loop.

    Declaration

    Swift

    func CFReadStreamScheduleWithRunLoop(_ stream: CFReadStream!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

    void CFReadStreamScheduleWithRunLoop ( CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    stream

    The stream to schedule.

    runLoop

    The run loop with which to schedule stream.

    runLoopMode

    The run loop mode of runLoop in which to schedule stream.

    Discussion

    After scheduling stream with a run loop, its client (set with CFReadStreamSetClient) is notified when various events happen with the stream, such as when it finishes opening, when it has bytes available, and when an error occurs. A stream can be scheduled with multiple run loops and run loop modes. Use CFReadStreamUnscheduleFromRunLoop to later remove stream from the run loop.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Removes a read stream from a given run loop.

    Declaration

    Swift

    func CFReadStreamUnscheduleFromRunLoop(_ stream: CFReadStream!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

    void CFReadStreamUnscheduleFromRunLoop ( CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    stream

    The stream to unschedule.

    runLoop

    The run loop from which to remove stream.

    runLoopMode

    The run loop mode of runLoop from which to remove stream.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the value of a property for a stream.

    Declaration

    Swift

    func CFReadStreamCopyProperty(_ stream: CFReadStream!, _ propertyName: CFString!) -> AnyObject!

    Objective-C

    CFTypeRef CFReadStreamCopyProperty ( CFReadStreamRef stream, CFStringRef propertyName );

    Parameters

    stream

    The stream to examine.

    propertyName

    The name of the stream property to obtain. The available properties for standard Core Foundation streams are listed in CFStream Reference.

    Return Value

    The value of the property propertyName. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Discussion

    Each type of stream can define a set of properties that either describe or configure individual streams. A property can be any information about a stream, other than the actual data the stream handles. Examples include the headers from an HTTP transmission, the expected number of bytes, file permission information, and so on. Use CFReadStreamSetProperty to modify the value of a property, although some properties are read-only.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns a pointer to a stream’s internal buffer of unread data, if possible.

    Declaration

    Swift

    func CFReadStreamGetBuffer(_ stream: CFReadStream!, _ maxBytesToRead: CFIndex, _ numBytesRead: UnsafeMutablePointer<CFIndex>) -> UnsafePointer<UInt8>

    Objective-C

    const UInt8 * CFReadStreamGetBuffer ( CFReadStreamRef stream, CFIndex maxBytesToRead, CFIndex *numBytesRead );

    Parameters

    stream

    The stream to examine.

    maxBytesToRead

    The maximum number of bytes to read. If greater than 0, maxBytesToRead limits the number of bytes read; if 0 or less, all available bytes are read.

    numBytesRead

    On return, contains the length of returned buffer. If stream is not open or has encountered an error, numBytesRead is set to -1.

    Return Value

    A pointer to the internal buffer of unread data for stream, if possible; NULL otherwise. The buffer is good only until the next stream operation called on the stream. You should neither change the contents of the returned buffer nor attempt to deallocate the buffer; it is still owned by the stream. The bytes returned in the buffer are considered read from the stream.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the error associated with a stream.

    Declaration

    Swift

    func CFReadStreamCopyError(_ stream: CFReadStream!) -> CFError!

    Objective-C

    CFErrorRef CFReadStreamCopyError ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    A CFError object that describes the current problem with stream, or NULL if there is no error. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the error status of a stream.

    Use CFReadStreamCopyError instead.

    Declaration

    Swift

    func CFReadStreamGetError(_ stream: CFReadStream!) -> CFStreamError

    Objective-C

    CFStreamError CFReadStreamGetError ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    The error status of stream returned in a CFStreamError structure.

    The error field is 0 if no error has occurred. If the error field is not 0, the domain field contains a code that identifies the domain in which the value of the error field should be interpreted.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the current state of a stream.

    Declaration

    Swift

    func CFReadStreamGetStatus(_ stream: CFReadStream!) -> CFStreamStatus

    Objective-C

    CFStreamStatus CFReadStreamGetStatus ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    The current state of stream. See CFStreamStatus for the list of possible states.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns a Boolean value that indicates whether a readable stream has data that can be read without blocking.

    Declaration

    Swift

    func CFReadStreamHasBytesAvailable(_ stream: CFReadStream!) -> Boolean

    Objective-C

    Boolean CFReadStreamHasBytesAvailable ( CFReadStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    TRUE if data can be read from stream without blocking, otherwise FALSE. If stream cannot tell if data is available without actually trying to read the data, this function returns TRUE.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Assigns a client to a stream, which receives callbacks when certain events occur.

    Declaration

    Swift

    func CFReadStreamSetClient(_ stream: CFReadStream!, _ streamEvents: CFOptionFlags, _ clientCB: CFReadStreamClientCallBack, _ clientContext: UnsafeMutablePointer<CFStreamClientContext>) -> Boolean

    Objective-C

    Boolean CFReadStreamSetClient ( CFReadStreamRef stream, CFOptionFlags streamEvents, CFReadStreamClientCallBack clientCB, CFStreamClientContext *clientContext );

    Parameters

    stream

    The stream to modify.

    streamEvents

    The set of events for which the client should receive callbacks. The events are listed in CFStreamEventType. If you pass kCFStreamEventNone, the current client for stream is removed.

    clientCB

    The client callback function to be called when one of the events requested in streamEvents occurs. If NULL, the current client for stream is removed.

    clientContext

    A structure holding contextual information for the stream client. The function copies the information out of the structure, so the memory pointed to by clientContext does not need to persist beyond the function call. If NULL, the current client for stream is removed.

    Return Value

    TRUE if the stream supports asynchronous notification, otherwise FALSE.

    Discussion

    To avoid polling and blocking, you can register a client to hear about interesting events that occur on a stream. Only one client per stream is allowed; registering a new client replaces the previous one.

    Once you have set a client, you need to schedule the stream in a run loop using CFReadStreamScheduleWithRunLoop so that the client can receive the asynchronous notifications. You can schedule each stream in multiple run loops (for example, if you are using a thread pool). It is the caller's responsibility to ensure that at least one of the scheduled run loops is being run, otherwise the callback cannot be called.

    Although all Core Foundation streams currently support asynchronous notification, future stream types may not. If a stream does not support asynchronous notification, this function returns false. Typically, such streams never block for device I/O (for example, a stream reading memory) and don’t benefit from asynchronous notification.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Sets the value of a property for a stream.

    Declaration

    Swift

    func CFReadStreamSetProperty(_ stream: CFReadStream!, _ propertyName: CFString!, _ propertyValue: AnyObject!) -> Boolean

    Objective-C

    Boolean CFReadStreamSetProperty ( CFReadStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue );

    Parameters

    stream

    The stream to modify.

    propertyName

    The name of the property to set. The available properties for standard Core Foundation streams are listed in CFStream Reference.

    propertyValue

    The value to which to set the property propertyName for stream. The allowed data type of the value depends on the property being set.

    Return Value

    TRUE if stream recognizes and accepts the given property-value pair, otherwiseFALSE.

    Discussion

    Each type of stream can define a set of properties that either describe or configure individual streams. A property can be any interesting information about a stream. Examples include the headers from an HTTP transmission, the expected number of bytes, file permission information, and so on. Properties that can be set configure the behavior of the stream and may be modifiable only at particular times, such as before the stream has been opened. (In fact, you should assume that you can set properties only before opening the stream, unless otherwise noted.) To read the value of a property use CFReadStreamCopyProperty, although some properties are write-only.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.2 and later.

  • Returns the type identifier the CFReadStream opaque type.

    Declaration

    Swift

    func CFReadStreamGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFReadStreamGetTypeID ( void );

    Return Value

    The type identifier for the CFReadStream opaque type.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

Callbacks

  • Callback invoked when certain types of activity takes place on a readable stream.

    Declaration

    Objective-C

    typedef void (*CFReadStreamClientCallBack) ( CFReadStreamRef stream, CFStreamEventType eventType, void *clientCallBackInfo );

    Parameters

    stream

    The stream that experienced the event eventType.

    eventType

    The event that caused the callback to be called. The possible events are listed in CFStreamEventType.

    clientCallBackInfo

    The info member of the CFStreamClientContext structure that was used when setting the client for stream.

    Discussion

    This callback is called only for the events requested when setting the client with CFReadStreamSetClient.

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A reference to a readable stream object.

    Declaration

    Swift

    typealias CFReadStreamRef = CFReadStream

    Objective-C

    typedef struct __CFReadStream *CFReadStreamRef;

    Import Statement

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • A structure that contains program-defined data and callbacks with which you can configure a stream’s client behavior.

    Declaration

    Swift

    struct CFStreamClientContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafeMutablePointer<Void>) -> UnsafeMutablePointer<Void>)> var release: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

    struct CFStreamClientContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct CFStreamClientContext CFStreamClientContext;

    Fields

    version

    Version number of the structure. Must be 0.

    info

    An arbitrary pointer to program-defined data, which can be associated with the client. This pointer is passed to the callbacks defined in the context and to the client callback function CFReadStreamClientCallBack.

    retain

    A retain callback for your program-defined info pointer. Can be NULL.

    release

    A release callback for your program-defined info pointer. Can be NULL.

    copyDescription

    A copy description callback for your program-defined info pointer. Can be NULL.

    Availability

    Available in OS X v10.0 and later.