1/*
2 * Copyright (c) 2014 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/*	CFStreamAbstract.h
25	Copyright (c) 2000-2013, Apple Inc. All rights reserved.
26*/
27
28#if !defined(__COREFOUNDATION_CFSTREAMABSTRACT__)
29#define __COREFOUNDATION_CFSTREAMABSTRACT__ 1
30
31#include <CoreFoundation/CFStream.h>
32
33CF_EXTERN_C_BEGIN
34
35/*  During a stream's lifetime, the open callback will be called once, followed by any number of openCompleted calls (until openCompleted returns TRUE).  Then any number of read/canRead or write/canWrite calls, then a single close call.  copyProperty can be called at any time.  prepareAsynch will be called exactly once when the stream's client is first configured.
36
37    Expected semantics:
38    - open reserves any system resources that are needed.  The stream may start the process of opening, returning TRUE immediately and setting openComplete to FALSE.  When the open completes, _CFStreamSignalEvent should be called passing kCFStreamOpenCompletedEvent.  openComplete should be set to TRUE only if the open operation completed in its entirety.
39    - openCompleted will only be called after open has been called, but before any kCFStreamOpenCompletedEvent has been received.  Return TRUE, setting error.code to 0, if the open operation has completed.  Return TRUE, setting error to the correct error code and domain if the open operation completed, but failed.  Return FALSE if the open operation is still in-progress.  If your open ever fails to complete (i.e. sets openComplete to FALSE), you must be implement the openCompleted callback.
40    - read should read into the given buffer, returning the number of bytes successfully read.  read must block until at least one byte is available, but should not block until the entire buffer is filled; zero should only be returned if end-of-stream is encountered. atEOF should be set to true if the EOF is encountered, false otherwise.  error.code should be set to zero if no error occurs; otherwise, error should be set to the appropriate values.
41    - getBuffer is an optimization to return an internal buffer of bytes read from the stream, and may return NULL.  getBuffer itself may be NULL if the concrete implementation does not wish to provide an internal buffer.  If implemented, it should set numBytesRead to the number of bytes available in the internal buffer (but should not exceed maxBytesToRead) and return a pointer to the base of the bytes.
42    - canRead will only be called once openCompleted reports that the stream has been successfully opened (or the initial open call succeeded).  It should return whether there are bytes that can be read without blocking.
43    - write should write the bytes in the given buffer to the device, returning the number of bytes successfully written.  write must block until at least one byte is written.  error.code should be set to zero if no error occurs; otherwise, error should be set to the appropriate values.
44    - close should close the device, releasing any reserved system resources.  close cannot fail (it may be called to abort the stream), and may be called at any time after open has been called.  It will only be called once.
45    - copyProperty should return the value for the given property, or NULL if none exists.  Composite streams (streams built on top of other streams) should take care to call CFStreamCopyProperty on the base stream if they do not recognize the property given, to give the underlying stream a chance to respond.
46
47    In all cases, errors returned by reference will be initialized to NULL by the caller, and if they are set to non-NULL, will
48    be released by the caller
49*/
50
51typedef struct {
52    CFIndex version; /* == 2 */
53
54    void *(*create)(CFReadStreamRef stream, void *info);
55    void (*finalize)(CFReadStreamRef stream, void *info);
56    CFStringRef (*copyDescription)(CFReadStreamRef stream, void *info);
57
58    Boolean (*open)(CFReadStreamRef stream, CFErrorRef *error, Boolean *openComplete, void *info);
59    Boolean (*openCompleted)(CFReadStreamRef stream, CFErrorRef *error, void *info);
60    CFIndex (*read)(CFReadStreamRef stream, UInt8 *buffer, CFIndex bufferLength, CFErrorRef *error, Boolean *atEOF, void *info);
61    const UInt8 *(*getBuffer)(CFReadStreamRef stream, CFIndex maxBytesToRead, CFIndex *numBytesRead, CFErrorRef *error, Boolean *atEOF, void *info);
62    Boolean (*canRead)(CFReadStreamRef stream, CFErrorRef *error, void *info);
63    void (*close)(CFReadStreamRef stream, void *info);
64
65    CFTypeRef (*copyProperty)(CFReadStreamRef stream, CFStringRef propertyName, void *info);
66    Boolean (*setProperty)(CFReadStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue, void *info);
67
68    void (*requestEvents)(CFReadStreamRef stream, CFOptionFlags streamEvents, void *info);
69    void (*schedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
70    void (*unschedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
71} CFReadStreamCallBacks;
72
73typedef struct {
74    CFIndex version; /* == 2 */
75
76    void *(*create)(CFWriteStreamRef stream, void *info);
77    void (*finalize)(CFWriteStreamRef stream, void *info);
78    CFStringRef (*copyDescription)(CFWriteStreamRef stream, void *info);
79
80    Boolean (*open)(CFWriteStreamRef stream, CFErrorRef *error, Boolean *openComplete, void *info);
81    Boolean (*openCompleted)(CFWriteStreamRef stream, CFErrorRef *error, void *info);
82    CFIndex (*write)(CFWriteStreamRef stream, const UInt8 *buffer, CFIndex bufferLength, CFErrorRef *error, void *info);
83    Boolean (*canWrite)(CFWriteStreamRef stream, CFErrorRef *error, void *info);
84    void (*close)(CFWriteStreamRef stream, void *info);
85
86    CFTypeRef (*copyProperty)(CFWriteStreamRef stream, CFStringRef propertyName, void *info);
87    Boolean (*setProperty)(CFWriteStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue, void *info);
88
89    void (*requestEvents)(CFWriteStreamRef stream, CFOptionFlags streamEvents, void *info);
90    void (*schedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
91    void (*unschedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
92} CFWriteStreamCallBacks;
93
94// Primitive creation mechanisms.
95CF_EXPORT
96CFReadStreamRef CFReadStreamCreate(CFAllocatorRef alloc, const CFReadStreamCallBacks *callbacks, void *info);
97CF_EXPORT
98CFWriteStreamRef CFWriteStreamCreate(CFAllocatorRef alloc, const CFWriteStreamCallBacks *callbacks, void *info);
99
100/* All the functions below can only be called when you are sure the stream in question was created via
101   CFReadStreamCreate() or CFWriteStreamCreate(), above.  They are NOT safe for toll-free bridged objects,
102   so the caller must be sure the argument passed is not such an object. */
103
104// To be called by the concrete stream implementation (the callbacks) when an event occurs. error may be NULL if event != kCFStreamEventErrorOccurred
105// error should be a CFErrorRef if the callbacks are version 2 or later; otherwise it should be a (CFStreamError *).
106CF_EXPORT
107void CFReadStreamSignalEvent(CFReadStreamRef stream, CFStreamEventType event, const void *error);
108CF_EXPORT
109void CFWriteStreamSignalEvent(CFWriteStreamRef stream, CFStreamEventType event, const void *error);
110
111// These require that the stream allow the run loop to run once before delivering the event to its client.
112// See the comment above CFRead/WriteStreamSignalEvent for interpretation of the error argument.
113CF_EXPORT
114void _CFReadStreamSignalEventDelayed(CFReadStreamRef stream, CFStreamEventType event, const void *error);
115CF_EXPORT
116void _CFWriteStreamSignalEventDelayed(CFWriteStreamRef stream, CFStreamEventType event, const void *error);
117
118CF_EXPORT
119void _CFReadStreamClearEvent(CFReadStreamRef stream, CFStreamEventType event);
120// Write variant not currently needed
121//CF_EXPORT
122//void _CFWriteStreamClearEvent(CFWriteStreamRef stream, CFStreamEventType event);
123
124// Convenience for concrete implementations to extract the info pointer given the stream.
125CF_EXPORT
126void *CFReadStreamGetInfoPointer(CFReadStreamRef stream);
127CF_EXPORT
128void *CFWriteStreamGetInfoPointer(CFWriteStreamRef stream);
129
130// Returns the client info pointer currently set on the stream.  These should probably be made public one day.
131CF_EXPORT
132void *_CFReadStreamGetClient(CFReadStreamRef readStream);
133CF_EXPORT
134void *_CFWriteStreamGetClient(CFWriteStreamRef writeStream);
135
136// Returns an array of the runloops and modes on which the stream is currently scheduled
137// Note that these are unretained mutable arrays - use the copy variant instead.
138CF_EXPORT
139CFArrayRef _CFReadStreamGetRunLoopsAndModes(CFReadStreamRef readStream);
140CF_EXPORT
141CFArrayRef _CFWriteStreamGetRunLoopsAndModes(CFWriteStreamRef writeStream);
142
143// Returns an array of the runloops and modes on which the stream is currently scheduled
144CF_EXPORT
145CFArrayRef _CFReadStreamCopyRunLoopsAndModes(CFReadStreamRef readStream);
146CF_EXPORT
147CFArrayRef _CFWriteStreamCopyRunLoopsAndModes(CFWriteStreamRef writeStream);
148
149/* Deprecated versions; here for backwards compatibility. */
150typedef struct {
151    CFIndex version; /* == 1 */
152    void *(*create)(CFReadStreamRef stream, void *info);
153    void (*finalize)(CFReadStreamRef stream, void *info);
154    CFStringRef (*copyDescription)(CFReadStreamRef stream, void *info);
155    Boolean (*open)(CFReadStreamRef stream, CFStreamError *error, Boolean *openComplete, void *info);
156    Boolean (*openCompleted)(CFReadStreamRef stream, CFStreamError *error, void *info);
157    CFIndex (*read)(CFReadStreamRef stream, UInt8 *buffer, CFIndex bufferLength, CFStreamError *error, Boolean *atEOF, void *info);
158    const UInt8 *(*getBuffer)(CFReadStreamRef stream, CFIndex maxBytesToRead, CFIndex *numBytesRead, CFStreamError *error, Boolean *atEOF, void *info);
159    Boolean (*canRead)(CFReadStreamRef stream, void *info);
160    void (*close)(CFReadStreamRef stream, void *info);
161    CFTypeRef (*copyProperty)(CFReadStreamRef stream, CFStringRef propertyName, void *info);
162    Boolean (*setProperty)(CFReadStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue, void *info);
163    void (*requestEvents)(CFReadStreamRef stream, CFOptionFlags streamEvents, void *info);
164    void (*schedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
165    void (*unschedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
166} CFReadStreamCallBacksV1;
167
168typedef struct {
169    CFIndex version; /* == 1 */
170    void *(*create)(CFWriteStreamRef stream, void *info);
171    void (*finalize)(CFWriteStreamRef stream, void *info);
172    CFStringRef (*copyDescription)(CFWriteStreamRef stream, void *info);
173    Boolean (*open)(CFWriteStreamRef stream, CFStreamError *error, Boolean *openComplete, void *info);
174    Boolean (*openCompleted)(CFWriteStreamRef stream, CFStreamError *error, void *info);
175    CFIndex (*write)(CFWriteStreamRef stream, const UInt8 *buffer, CFIndex bufferLength, CFStreamError *error, void *info);
176    Boolean (*canWrite)(CFWriteStreamRef stream, void *info);
177    void (*close)(CFWriteStreamRef stream, void *info);
178    CFTypeRef (*copyProperty)(CFWriteStreamRef stream, CFStringRef propertyName, void *info);
179    Boolean (*setProperty)(CFWriteStreamRef stream, CFStringRef propertyName, CFTypeRef propertyValue, void *info);
180    void (*requestEvents)(CFWriteStreamRef stream, CFOptionFlags streamEvents, void *info);
181    void (*schedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
182    void (*unschedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
183} CFWriteStreamCallBacksV1;
184
185typedef struct {
186    CFIndex version; /* == 0 */
187    Boolean (*open)(CFReadStreamRef stream, CFStreamError *error, Boolean *openComplete, void *info);
188    Boolean (*openCompleted)(CFReadStreamRef stream, CFStreamError *error, void *info);
189    CFIndex (*read)(CFReadStreamRef stream, UInt8 *buffer, CFIndex bufferLength, CFStreamError *error, Boolean *atEOF, void *info);
190    const UInt8 *(*getBuffer)(CFReadStreamRef stream, CFIndex maxBytesToRead, CFIndex *numBytesRead, CFStreamError *error, Boolean *atEOF, void *info);
191    Boolean (*canRead)(CFReadStreamRef stream, void *info);
192    void (*close)(CFReadStreamRef stream, void *info);
193    CFTypeRef (*copyProperty)(CFReadStreamRef stream, CFStringRef propertyName, void *info);
194    void (*schedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
195    void (*unschedule)(CFReadStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
196} CFReadStreamCallBacksV0;
197
198typedef struct {
199    CFIndex version; /* == 0 */
200    Boolean (*open)(CFWriteStreamRef stream, CFStreamError *error, Boolean *openComplete, void *info);
201    Boolean (*openCompleted)(CFWriteStreamRef stream, CFStreamError *error, void *info);
202    CFIndex (*write)(CFWriteStreamRef stream, const UInt8 *buffer, CFIndex bufferLength, CFStreamError *error, void *info);
203    Boolean (*canWrite)(CFWriteStreamRef stream, void *info);
204    void (*close)(CFWriteStreamRef stream, void *info);
205    CFTypeRef (*copyProperty)(CFWriteStreamRef stream, CFStringRef propertyName, void *info);
206    void (*schedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
207    void (*unschedule)(CFWriteStreamRef stream, CFRunLoopRef runLoop, CFStringRef runLoopMode, void *info);
208} CFWriteStreamCallBacksV0;
209
210CF_EXTERN_C_END
211
212#endif /* ! __COREFOUNDATION_CFSTREAMABSTRACT__ */
213