/* * Copyright (c) 2005 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ #if !defined(__CFNETWORK_CFCONNECTION__) #define __CFNETWORK_CFCONNECTION__ 1 #include #include "CFNetworkInternal.h" #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /* * _CFNetConnectionRef * * Discussion: * This is the type of a reference to a net connection. A * CFNetConnection maintains a pair of streams on which a queue of * requests are serviced. A given net connection request represents * a request and response pair. */ typedef struct __CFNetConnection* _CFNetConnectionRef; /* * _CFNetConnectionState * * Discussion: * Indicators of state for individual requests and responses on a * CFNetConnection. */ enum _CFNetConnectionState { /* * Request or response is not in the queue */ kNotQueued = 0, /* * Request or response is in the queue */ kQueued = 1, /* * Request is in the process of sending */ kTransmittingRequest = 2, /* * Request has been sent but the response hasn't started to arrive */ kWaitingForResponse = 3, /* * Response is in the process of being received */ kReceivingResponse = 4, /* * Request has been transmitted and the response has been received. * The request is now complete. */ kFinished = 5, /* * Request has been cancelled and removed from the queue. */ kCancelled = 6, /* * Something has happened with the connection such that the given * queued request has now been dropped from the queue. The user * should now requeue the request on a new net connection. */ kOrphaned = 7 }; typedef enum _CFNetConnectionState _CFNetConnectionState; typedef CALLBACK_API_C( const void *, _CFNetConnectionCreateCallBack )(CFAllocatorRef alloc, const void *info); typedef CALLBACK_API_C( void , _CFNetConnectionFinalizeCallBack )(CFAllocatorRef alloc, const void *info); typedef CALLBACK_API_C( CFStreamError , _CFNetConnectionCreateStreamsCallBack )(CFAllocatorRef allocator, const void *info, CFWriteStreamRef *requestStream, CFReadStreamRef *responseStream); typedef CALLBACK_API_C( void , _CFNetConnectionStateChangedCallBack )(void *request, int newState, CFStreamError *err, _CFNetConnectionRef connection, const void *info); typedef CALLBACK_API_C( void , _CFNetConnectionTransmitRequest )(void *request, _CFNetConnectionRef connection, const void *info); typedef CALLBACK_API_C( void , _CFNetConnectionReceiveResponse )(void *request, _CFNetConnectionRef connection, const void *info); typedef CALLBACK_API_C( void , _CFNetConnectionResponseStreamCallBack )(void *request, CFReadStreamRef stream, CFStreamEventType eventType, _CFNetConnectionRef conn, const void *info); typedef CALLBACK_API_C( void , _CFNetConnectionRequestStreamCallBack )(void *request, CFWriteStreamRef stream, CFStreamEventType eventType, _CFNetConnectionRef conn, const void *info); typedef CALLBACK_API_C( CFArrayRef , _CFNetConnectionRunLoopArrayCallBack )(void *request, _CFNetConnectionRef conn, const void *info); struct _CFNetConnectionCallBacks { CFIndex version; _CFNetConnectionCreateCallBack create; _CFNetConnectionFinalizeCallBack finalize; _CFNetConnectionCreateStreamsCallBack createConnectionStreams; _CFNetConnectionStateChangedCallBack requestStateChanged; _CFNetConnectionTransmitRequest transmitRequest; _CFNetConnectionReceiveResponse receiveResponse; _CFNetConnectionResponseStreamCallBack responseStreamCallBack; _CFNetConnectionRequestStreamCallBack requestStreamCallBack; _CFNetConnectionRunLoopArrayCallBack runLoopAndModesArrayForRequest; }; typedef struct _CFNetConnectionCallBacks _CFNetConnectionCallBacks; /* Net connection*/ /* * _CFNetConnectionGetTypeID() * */ extern CFTypeID _CFNetConnectionGetTypeID(void) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* * _CFNetConnectionGetInfoPointer() * */ extern const void * _CFNetConnectionGetInfoPointer(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Create and return a new connection object*/ /* * _CFNetConnectionCreate() * Note - in 10.3, this function did not take the isThreadSafe argument; that was added for 10.4 * */ extern _CFNetConnectionRef _CFNetConnectionCreate( CFAllocatorRef alloc, const void * info, const _CFNetConnectionCallBacks * callBacks, Boolean isThreadSafe) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* Enqueues req on conn's transmission queue. If this is the first such request, this will cause the connection to open streams to the server*/ /* * _CFNetConnectionEnqueue() * */ extern Boolean _CFNetConnectionEnqueue( _CFNetConnectionRef conn, void * req) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Cancel an enqueued request; this will cause the connection to in all ways "forget" the request. Returns FALSE if the request is currently mid-transmission, in which case the connection cannot safely remove the request.*/ /* * _CFNetConnectionDequeue() * */ extern Boolean _CFNetConnectionDequeue( _CFNetConnectionRef conn, void * req) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* * _CFNetConnectionGetCurrentRequest() * * Discussion: * Returns the head queued request or NULL if there is nothing * queued. * * Mac OS X threading: * Not thread safe * * Parameters: * * conn: * The connection to query for the head request. * * Result: * Returns a pointer to the head request if there is one, otherwise * it returns NULL. * */ extern void * _CFNetConnectionGetCurrentRequest(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Replaces oldReq with newReq in the connection's queue.*/ /* * _CFNetConnectionReplaceRequest() * */ extern void _CFNetConnectionReplaceRequest( _CFNetConnectionRef conn, void * oldReq, void * newReq) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Returns the response streams*/ /* * _CFNetConnectionGetResponseStream() * */ extern CFReadStreamRef _CFNetConnectionGetResponseStream(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Returns the request streams*/ /* * _CFNetConnectionGetRequestStream() * */ extern CFWriteStreamRef _CFNetConnectionGetRequestStream(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Informs the connection that the given request considers its response complete, and the connection should break its connection to the request and advance to the next response*/ /* * _CFNetConnectionResponseIsComplete() * */ extern void _CFNetConnectionResponseIsComplete( _CFNetConnectionRef conn, void * req) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Informs the connection that the given request considers its request complete (i.e. fully transmitted), and the connection should advance to the next request to be transmitted*/ /* * _CFNetConnectionRequestIsComplete() * */ extern void _CFNetConnectionRequestIsComplete( _CFNetConnectionRef conn, void * req) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Error out the connection with the given error. All queued requests will be orphaned.*/ /* * _CFNetConnectionErrorOccurred() * */ extern void _CFNetConnectionErrorOccurred( _CFNetConnectionRef conn, CFStreamError * err) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Announces that the persistent connection has been lost; all responses after the current one must be orphaned*/ /* * _CFNetConnectionLost() * */ extern void _CFNetConnectionLost(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Set whether requests will be transmitted without waiting for previous responses*/ /* * _CFNetConnectionSetShouldPipeline() * */ extern void _CFNetConnectionSetShouldPipeline( _CFNetConnectionRef conn, Boolean shouldPipeline) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; extern CFAbsoluteTime _CFNetConnectionGetLastAccessTime(_CFNetConnectionRef arg); extern int _CFNetConnectionGetQueueDepth(_CFNetConnectionRef conn); /* * _CFNetConnectionSetAllowsNewRequests() * */ extern void _CFNetConnectionSetAllowsNewRequests( _CFNetConnectionRef conn, Boolean allowRequests) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* * _CFNetConnectionWillEnqueueRequests() * */ extern Boolean _CFNetConnectionWillEnqueueRequests(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Gets the connection's current opinion about the request's state. If advanceConnection is TRUE, calling this will cause the connection to attempt to further the state of its queue, and may cause calls back in to the request. If the connection knows nothing about the request, it will return kOrphaned, and the calling request should forget any tie to this connection*/ /* * _CFNetConnectionGetState() * */ extern int _CFNetConnectionGetState( _CFNetConnectionRef conn, Boolean advanceConnection, void * req) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Informs the connection that the given request has been scheduled and asks the connection to take any appropriate action*/ /* * _CFNetConnectionSchedule() * */ extern void _CFNetConnectionSchedule( _CFNetConnectionRef conn, void * req, CFRunLoopRef rl, CFStringRef mode) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Informs the connection that the given request has been unscheduled, and asks the connection to take any appropriate action*/ /* * _CFNetConnectionUnschedule() * */ extern void _CFNetConnectionUnschedule( _CFNetConnectionRef conn, void * req, CFRunLoopRef rl, CFStringRef mode) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* Informs the connection that the given request has been unscheduled, and asks the connection to take any appropriate action*/ /* * _CFNetConnectionIsEmpty() * */ extern Boolean _CFNetConnectionIsEmpty(_CFNetConnectionRef conn) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; // Currently not used, so hand dead-stripping for now. //extern Boolean //_CFNetConnectionIsPipelining(_CFNetConnectionRef arg); typedef struct __CFNetConnectionCache * CFNetConnectionCacheRef; typedef struct __CFNetConnectionCacheKey* _CFNetConnectionCacheKey; // // Net connection cache // CFNetConnectionCacheRef createConnectionCache(); #if defined(__WIN32__) void releaseConnectionCache(CFNetConnectionCacheRef cache); #endif /* defined(__WIN32__) */ void lockConnectionCache(CFNetConnectionCacheRef cache); void unlockConnectionCache(CFNetConnectionCacheRef cache); extern _CFNetConnectionRef findOrCreateNetConnection(CFNetConnectionCacheRef connectionCache, CFAllocatorRef allocator, const _CFNetConnectionCallBacks *callbacks, const void *info, _CFNetConnectionCacheKey key, Boolean persistent, CFDictionaryRef connectionProperties); // This routine ties the two objects (connection cache & connection) extern void removeFromConnectionCache(CFNetConnectionCacheRef cache, _CFNetConnectionRef conn, _CFNetConnectionCacheKey key); // These two callbacks are shared across protocols const void *connCacheKeyRetain(CFAllocatorRef allocator, const void *value); void connCacheKeyRelease(CFAllocatorRef allocator, const void *value); // // Net connection cache key // _CFNetConnectionCacheKey createConnectionCacheKey(CFStringRef host, SInt32 port, UInt32 connType, CFDictionaryRef properties); void releaseConnectionCacheKey(_CFNetConnectionCacheKey theKey); void getValuesFromKey(const _CFNetConnectionCacheKey theKey, CFStringRef *host, SInt32 *port, UInt32 *connType, CFDictionaryRef *properties); #ifdef DEBUG void printKey(_CFNetConnectionCacheKey key); #endif /* DEBUG */ #if defined(__cplusplus) } #endif #endif /* ! __CFNETWORK_CFNETCONNECTION__ */