Mac Developer Library

Developer

CoreFoundation Framework Reference CFWriteStream Reference

Options
Deployment Target:

On This Page
Language:

CFWriteStream Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

CFWriteStream provides an interface for writing a byte stream either synchronously or asynchronously. You can create streams that write bytes to a block of memory, a file, or a generic socket. All streams need to be opened, using CFWriteStreamOpen, before writing.

Use CFReadStream for reading byte streams, and for the functions, such as CFStreamCreatePairWithSocketToHost, that create socket streams).

CFWriteStream is “toll-free bridged” with its Cocoa Foundation counterpart, NSOutputStream. 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 NSOutputStream * parameter, you can pass in a CFWriteStreamRef, and in a function where you see a CFWriteStreamRef parameter, you can pass in an NSOutputStream instance. Note, however, that you may have either a delegate or callbacks but not both. See Toll-Free Bridged Types for more information on toll-free bridging.

Functions

  • Creates a writable stream for a growable block of memory.

    Declaration

    Swift

    func CFWriteStreamCreateWithAllocatedBuffers(_ alloc: CFAllocator!, _ bufferAllocator: CFAllocator!) -> CFWriteStream!

    Objective-C

    CFWriteStreamRef CFWriteStreamCreateWithAllocatedBuffers ( CFAllocatorRef alloc, CFAllocatorRef bufferAllocator );

    Parameters

    alloc

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

    bufferAllocator

    The allocator to use to allocate memory for the stream’s memory buffers. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    Return Value

    A new write stream. Ownership follows the Create Rule.

    Discussion

    New buffers are allocated using bufferAllocator as bytes are written to the stream. At any point, you can recover the bytes thus far written by asking for the property kCFStreamPropertyDataWritten with CFWriteStreamCopyProperty.

    You must open the stream, using CFWriteStreamOpen, before writing to it.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Creates a writable stream for a fixed-size block of memory.

    Declaration

    Swift

    func CFWriteStreamCreateWithBuffer(_ alloc: CFAllocator!, _ buffer: UnsafeMutablePointer<UInt8>, _ bufferCapacity: CFIndex) -> CFWriteStream!

    Objective-C

    CFWriteStreamRef CFWriteStreamCreateWithBuffer ( CFAllocatorRef alloc, UInt8 *buffer, CFIndex bufferCapacity );

    Parameters

    alloc

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

    buffer

    The memory buffer into which to write data. This buffer must exist for the lifetime of the stream.

    bufferCapacity

    The size of buffer and the maximum number of bytes that can be written.

    Return Value

    A new write stream, or NULL on failure. Ownership follows the Create Rule.

    Discussion

    When buffer is filled after writing bufferCapacity bytes, the stream is exhausted and its status becomes kCFStreamStatusAtEnd.

    You must open the stream, using CFWriteStreamOpen, before writing to it.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Creates a writable stream for a file.

    Declaration

    Swift

    func CFWriteStreamCreateWithFile(_ alloc: CFAllocator!, _ fileURL: CFURL!) -> CFWriteStream!

    Objective-C

    CFWriteStreamRef CFWriteStreamCreateWithFile ( 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 which to write. The URL must use a file scheme.

    Return Value

    The new write stream, or NULL on failure. Ownership follows the Create Rule.

    Discussion

    The stream overwrites an existing file unless you set the kCFStreamPropertyAppendToFile to kCFBooleanTrue with CFWriteStreamSetProperty, in which case the stream appends data to the file.

    You must open the stream, using CFWriteStreamOpen, before writing to it.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Closes a writable stream.

    Declaration

    Swift

    func CFWriteStreamClose(_ stream: CFWriteStream!)

    Objective-C

    void CFWriteStreamClose ( CFWriteStreamRef 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

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Opens a stream for writing.

    Declaration

    Swift

    func CFWriteStreamOpen(_ stream: CFWriteStream!) -> Boolean

    Objective-C

    Boolean CFWriteStreamOpen ( CFWriteStreamRef 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 CFWriteStreamScheduleWithRunLoop and wait for the stream’s client (set with CFWriteStreamSetClient) to be notified or you can poll the stream using CFWriteStreamGetStatus, waiting for a status of kCFStreamStatusOpen or kCFStreamStatusError.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Writes data to a writable stream.

    Declaration

    Swift

    func CFWriteStreamWrite(_ stream: CFWriteStream!, _ buffer: UnsafePointer<UInt8>, _ bufferLength: CFIndex) -> CFIndex

    Objective-C

    CFIndex CFWriteStreamWrite ( CFWriteStreamRef stream, const UInt8 *buffer, CFIndex bufferLength );

    Parameters

    stream

    The stream to which to write.

    buffer

    The buffer holding the data to write.

    bufferLength

    The number of bytes from buffer to write.

    Return Value

    The number of bytes successfully written, 0 if the stream has been filled to capacity (for fixed-length streams), 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. If the stream is not full, this call blocks until at least one byte is written; it does not block until all the bytes in buffer is written. To avoid blocking, call this function only if CFWriteStreamCanAcceptBytes returns true or after the stream’s client (set with CFWriteStreamSetClient) is notified of a kCFStreamEventCanAcceptBytes event.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Schedules a stream into a run loop.

    Declaration

    Swift

    func CFWriteStreamScheduleWithRunLoop(_ stream: CFWriteStream!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

    void CFWriteStreamScheduleWithRunLoop ( CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    stream

    The stream to schedule.

    runLoop

    The run loop in which to schedule stream.

    runLoopMode

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Removes a stream from a particular run loop.

    Declaration

    Swift

    func CFWriteStreamUnscheduleFromRunLoop(_ stream: CFWriteStream!, _ runLoop: CFRunLoop!, _ runLoopMode: CFString!)

    Objective-C

    void CFWriteStreamUnscheduleFromRunLoop ( CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    stream

    The stream to remove.

    runLoop

    The run loop from which to remove stream.

    runLoopMode

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

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns whether a writable stream can accept new data without blocking.

    Declaration

    Swift

    func CFWriteStreamCanAcceptBytes(_ stream: CFWriteStream!) -> Boolean

    Objective-C

    Boolean CFWriteStreamCanAcceptBytes ( CFWriteStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    true if data can be written to stream without blocking, false otherwise. If stream cannot tell if data can be written without actually trying to write the data, this function returns true.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the value of a property for a stream.

    Declaration

    Swift

    func CFWriteStreamCopyProperty(_ stream: CFWriteStream!, _ propertyName: CFString!) -> AnyObject!

    Objective-C

    CFTypeRef CFWriteStreamCopyProperty ( CFWriteStreamRef 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 Stream Properties.

    Return Value

    The value of the property propertyName. Ownership follows the Create Rule.

    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. Use CFWriteStreamSetProperty to modify the value of a property, although some properties are read-only.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the error associated with a stream.

    Declaration

    Swift

    func CFWriteStreamCopyError(_ stream: CFWriteStream!) -> CFError!

    Objective-C

    CFErrorRef CFWriteStreamCopyError ( CFWriteStreamRef 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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the error status of a stream.

    Use CFWriteStreamCopyError instead.

    Declaration

    Swift

    func CFWriteStreamGetError(_ stream: CFWriteStream!) -> CFStreamError

    Objective-C

    CFStreamError CFWriteStreamGetError ( CFWriteStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

    The error status of stream returned in a CFStreamError structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Returns the current state of a stream.

    Declaration

    Swift

    func CFWriteStreamGetStatus(_ stream: CFWriteStream!) -> CFStreamStatus

    Objective-C

    CFStreamStatus CFWriteStreamGetStatus ( CFWriteStreamRef stream );

    Parameters

    stream

    The stream to examine.

    Return Value

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

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    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 CFWriteStreamSetClient(_ stream: CFWriteStream!, _ streamEvents: CFOptionFlags, _ clientCB: CFWriteStreamClientCallBack, _ clientContext: UnsafeMutablePointer<CFStreamClientContext>) -> Boolean

    Objective-C

    Boolean CFWriteStreamSetClient ( CFWriteStreamRef stream, CFOptionFlags streamEvents, CFWriteStreamClientCallBack 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 call 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, false otherwise.

    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 CFWriteStreamScheduleWithRunLoop 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 writing to memory) and don’t benefit from asynchronous notification.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

  • Sets the value of a property for a stream.

    Declaration

    Swift

    func CFWriteStreamSetProperty(_ stream: CFWriteStream!, _ propertyName: CFString!, _ propertyValue: AnyObject!) -> Boolean

    Objective-C

    Boolean CFWriteStreamSetProperty ( CFWriteStreamRef 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 Stream Properties.

    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, false otherwise.

    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 CFWriteStreamCopyProperty, although some properties are write-only.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.2 and later.

  • Returns the type identifier of all CFWriteStream objects.

    Declaration

    Swift

    func CFWriteStreamGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFWriteStreamGetTypeID ( void );

    Return Value

    The type identifier for the CFWriteStream opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.1 and later.

Callbacks

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

    Declaration

    Swift

    typealias CFWriteStreamClientCallBack = CFunctionPointer<((CFWriteStream!, CFStreamEventType, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CFWriteStreamClientCallBack) ( CFWriteStreamRef 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 Stream Events..

    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 CFWriteStreamSetClient.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A reference to a writable stream object.

    Declaration

    Swift

    typealias CFWriteStreamRef = CFWriteStream

    Objective-C

    typedef struct __CFWriteStream *CFWriteStreamRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.