CFReadStream Reference

Overview

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. 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” for more information on toll-free bridging.

Functions by Task

Creating a Read Stream

• CFReadStreamCreateWithBytesNoCopy
• CFReadStreamCreateWithFile

Opening and Closing a Read Stream

• CFReadStreamClose
• CFReadStreamOpen

Reading from a Stream

• CFReadStreamRead

Scheduling a Read Stream

• CFReadStreamScheduleWithRunLoop
• CFReadStreamUnscheduleFromRunLoop

Examining Stream Properties

• CFReadStreamCopyProperty
• CFReadStreamGetBuffer
• CFReadStreamCopyError
• CFReadStreamGetError
• CFReadStreamGetStatus
• CFReadStreamHasBytesAvailable

Setting Stream Properties

• CFReadStreamSetClient
• CFReadStreamSetProperty

Getting the CFReadStream Type ID

• CFReadStreamGetTypeID

Functions

CFReadStreamClose

Closes a readable stream.

void CFReadStreamClose (
   CFReadStreamRef stream
);

CFReadStreamCopyError

Returns the error associated with a stream.

CFErrorRef CFReadStreamCopyError (
   CFReadStreamRef stream
);

CFReadStreamCopyProperty

Returns the value of a property for a stream.

CFTypeRef CFReadStreamCopyProperty (
   CFReadStreamRef stream,
   CFStringRef propertyName
);

CFReadStreamCreateWithBytesNoCopy

Creates a readable stream for a block of memory.

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

CFReadStreamCreateWithFile

Creates a readable stream for a file.

CFReadStreamRef CFReadStreamCreateWithFile (
   CFAllocatorRef alloc,
   CFURLRef fileURL
);

CFReadStreamGetBuffer

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

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

CFReadStreamGetError

Returns the error status of a stream. (Deprecated. Use CFReadStreamCopyError instead.)

CFStreamError CFReadStreamGetError (
   CFReadStreamRef stream
);

CFReadStreamGetStatus

Returns the current state of a stream.

CFStreamStatus CFReadStreamGetStatus (
   CFReadStreamRef stream
);

CFReadStreamGetTypeID

Returns the type identifier the CFReadStream opaque type.

CFTypeID CFReadStreamGetTypeID (
   void
);

CFReadStreamHasBytesAvailable

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

Boolean CFReadStreamHasBytesAvailable (
   CFReadStreamRef stream
);

CFReadStreamOpen

Opens a stream for reading.

Boolean CFReadStreamOpen (
   CFReadStreamRef stream
);

CFReadStreamRead

Reads data from a readable stream.

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

CFReadStreamScheduleWithRunLoop

Schedules a stream into a run loop.

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

CFReadStreamSetClient

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

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

CFReadStreamSetProperty

Sets the value of a property for a stream.

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

CFReadStreamUnscheduleFromRunLoop

Removes a read stream from a given run loop.

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

Callbacks

CFReadStreamClientCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFReadStreamRef stream,
   CFStreamEventType eventType,
   void *clientCallBackInfo
);

Data Types

CFReadStreamRef

A reference to a readable stream object.

typedef struct __CFReadStream *CFReadStreamRef;

CFStreamClientContext

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

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.