CFHTTPConnectionPriv.h   [plain text]


/*
 * 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@
 */
/*
     File:       CFNetwork/CFHTTPConnectionPriv.h
 
     Contains:   CoreFoundation Network HTTP connection SPI
 
     Copyright:   2004-2005 by Apple Computer, Inc., all rights reserved
 
     Warning:    *** APPLE INTERNAL USE ONLY ***
                 This file contains unreleased SPI's
 
     BuildInfo:  Built by:            anonymous
                 On:                  Wed Apr 27 10:45:36 2005
                 With Interfacer:     3.0d46   (Mac OS X for PowerPC)
                 From:                CFHTTPConnectionPriv.i
                     Revision:        1.6
                     Dated:           2004/06/08 00:02:25
                     Last change by:  rew
                     Last comment:    Add symbol to allow CFHTTPConnection to handle streamed uploads
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFHTTPCONNECTIONPRIV__
#define __CFHTTPCONNECTIONPRIV__

#ifndef __CFNETWORKDEFS__
#include <CFNetwork/CFNetworkDefs.h>
#endif

#ifndef __COREFOUNDATION__
#include <CoreFoundation/CoreFoundation.h>
#endif

#ifndef __CFNETWORK__
#include <CFNetwork/CFNetwork.h>
#endif



#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint on
#endif


/*
 *  _CFHTTPConnectionType
 *  
 *  Discussion:
 *    The different kinds of connections that can be passed in to
 *    CFHTTPConnectionCreate()
 */
enum _CFHTTPConnectionType {

  /*
   * A direct HTTP connection to the server
   */
  kHTTP                         = 0,

  /*
   * A direct HTTPS connection to the server
   */
  kHTTPS                        = 1,

  /*
   * A connection to an HTTP proxy
   */
  kHTTPProxy                    = 2,

  /*
   * A connection to an HTTPS proxy
   */
  kHTTPSProxy                   = 3,
  kSOCKSProxy                   = 4
};
typedef enum _CFHTTPConnectionType _CFHTTPConnectionType;



/*
 *  CFHTTPConnectionRef
 *  
 *  Discussion:
 *    A connection to a particular host over which HTTP requests may be
 *    enqueued
 */
typedef CFTypeRef                       CFHTTPConnectionRef;
/*
 *  kCFStreamErrorHTTPConnectionLost
 *  
 *  Discussion:
 *    The error in the domain kCFStreamErrorDomainHTTP returned when an
 *    upstream request has detected that the connection is dying (often
 *    because of a request limit from the server). If you receive this
 *    error, you may assume that there is nothing wrong with your
 *    request itself, just that the connection did not survive long
 *    enough to process your request.
 *  
 */
extern const SInt32 kCFStreamErrorHTTPConnectionLost                 AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
/*
 *  _kCFStreamPropertyHTTPConnection
 *  
 *  Discussion:
 *    Retrievable property on streams returned by
 *    CFHTTPConnectionEnqueue, below.  Returns the CFHTTPConnectionRef
 *    on which the stream is scheduled.
 *  
 */
extern const CFStringRef _kCFStreamPropertyHTTPConnection            AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
/*
 *  CFHTTPConnectionCreate()
 *  
 *  Discussion:
 *    Creates a new HTTP connection.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      The CFAllocator to be used to create the new connection
 *    
 *    host:
 *      The target host for the new connection
 *    
 *    port:
 *      The target port for the new connection
 *    
 *    connectionType:
 *      The type of connection desired; taken from
 *      _CFHTTPConnectionType above.
 *    
 *    streamProperties:
 *      Any additional properties to be set on the underlying socket
 *      stream(s) before the connection is first used
 *  
 *  Result:
 *    Returns the newly created CFHTTPConnection, or NULL if
 *    unsuccessful
 *  
 */
extern CFHTTPConnectionRef 
CFHTTPConnectionCreate(
  CFAllocatorRef    alloc,
  CFStringRef       host,
  SInt32            port,
  UInt32            connectionType,
  CFDictionaryRef   streamProperties)                         AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionEnqueue()
 *  
 *  Discussion:
 *    Enqueues the given HTTP request on the given connection.
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection you wish to send the request over
 *    
 *    request:
 *      The request you wish to send
 *  
 *  Result:
 *    A CFReadStream with which you can monitor the request's progress
 *    through the connection. Note that the request will not actually
 *    be scheduled on the connection until the returned stream is
 *    opened.
 *  
 */
extern CFReadStreamRef 
CFHTTPConnectionEnqueue(
  CFHTTPConnectionRef   connection,
  CFHTTPMessageRef      request)                              AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionEnqueueWithBodyStream()
 *  
 *  Discussion:
 *    Enqueues the given HTTP request on the given connection.
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection you wish to send the request over
 *    
 *    request:
 *      The request you wish to send
 *    
 *    bodyStream:
 *      An unopened read stream which will return the body bytes to be
 *      transmitted with request
 *  
 *  Result:
 *    A CFReadStream with which you can monitor the request's progress
 *    through the connection. Note that the request will not actually
 *    be scheduled on the connection until the returned stream is
 *    opened.
 *  
 */
extern CFReadStreamRef 
CFHTTPConnectionEnqueueWithBodyStream(
  CFHTTPConnectionRef   connection,
  CFHTTPMessageRef      request,
  CFReadStreamRef       bodyStream)                           AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionSetShouldPipeline()
 *  
 *  Discussion:
 *    Sets whether the given connection will pipeline outgoing
 *    requests, transmitting the requests in sequence without waiting
 *    for the full responses to earlier requests.
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection to be configured
 *    
 *    shouldPipeline:
 *      TRUE if you wish the connection to pipeline outgoing requests;
 *      FALSE if you wish the connection to wait for one request's
 *      response before sending the next request
 *  
 */
extern void 
CFHTTPConnectionSetShouldPipeline(
  CFHTTPConnectionRef   connection,
  Boolean               shouldPipeline)                       AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionLost()
 *  
 *  Discussion:
 *    Informs the connection that after the current response, no
 *    further request can be processed. Causes the connection to error
 *    out all further requests on the connection, returning an error
 *    code of {kCFStreamErrorDomainHTTP,
 *    kCFStreamErrorHTTPConnectionLost}
 *  
 *  Parameters:
 *    
 *    conn:
 *      The connection that has been lost
 *  
 */
extern void 
CFHTTPConnectionLost(CFHTTPConnectionRef conn)                AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionInvalidate()
 *  
 *  Discussion:
 *    Invalidates the given connection, stopping all traffic on that
 *    connection and causing all requests in progress to return the
 *    error given.  This also closes the underlying system resources to
 *    be release, and the connection to the remote host to be severed.
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection to be shut down
 *    
 *    error:
 *      The error to be returned by all active requests on the
 *      connection being shut down
 *  
 */
extern void 
CFHTTPConnectionInvalidate(
  CFHTTPConnectionRef   connection,
  CFStreamError *       error)                                AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionAcceptsRequests()
 *  
 *  Discussion:
 *    Returns whether the given connection would current accept new
 *    requests.  It would not accept new requests if the connection has
 *    been invalidated, or if the connection has detected an underlying
 *    networking error, rendering its network connection to the remote
 *    host unusable.
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection to query about its status
 *  
 *  Result:
 *    TRUE if the connection currently believes it can process further
 *    requests; FALSE otherwise. Note that a TRUE return value does not
 *    guarantee that future requests will be accepted - the connection
 *    could become invalid between this call and accepting the new
 *    request, or between accepting the new request and the resulting
 *    stream being opened - but a FALSE return can be used as an early
 *    indicator of a bad connection.
 *  
 */
extern Boolean 
CFHTTPConnectionAcceptsRequests(CFHTTPConnectionRef connection) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFHTTPConnectionGetLastAccessTime()
 *  
 *  Discussion:
 *    Returns the last time the connection had an active request in it
 *  
 *  Parameters:
 *    
 *    connection:
 *      The connection to query about its last access tiem
 *  
 *  Result:
 *    The last time the connection had an active request
 *  
 */
extern CFAbsoluteTime 
CFHTTPConnectionGetLastAccessTime(CFHTTPConnectionRef connection) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



/*
 *  CFHTTPConnectionGetQueueDepth()
 *  
 *  Discussion:
 *    Returns the current depth of the request queue, counting from the
 *    request currently receiving its response
 *  
 *  Parameters:
 *    
 *    conn:
 *      The connection to query about its queue
 *  
 *  Result:
 *    The current depth of the queue
 *  
 */
extern int 
CFHTTPConnectionGetQueueDepth(CFHTTPConnectionRef conn)       AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



/*
 *  _CFHTTPGetConnectionInfoForProxyURL()
 *  
 */
extern void 
_CFHTTPGetConnectionInfoForProxyURL(
  CFURLRef           proxyURL,
  CFHTTPMessageRef   request,
  CFStringRef *      host,
  SInt32 *           port,
  UInt32 *           theType,
  CFDictionaryRef *  streamProperties)                        AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;




/*
 *  _CFProxyStreamCallBack
 *  
 *  Discussion:
 *    Callback function which is called once an asynchronous proxy
 *    lookup completes
 *  
 *  Parameters:
 *    
 *    proxyStream:
 *      The proxy stream returned when the asynchronous lookup began
 *    
 *    clientInfo:
 *      The opaque client context passed in to
 *      _CFNetworkFindProxyForURLAsync, below
 */
typedef CALLBACK_API_C( void , _CFProxyStreamCallBack )(CFReadStreamRef proxyStream, void *clientInfo);
/*
 *  _CFNetworkFindProxyForURLAsync()
 *  
 *  Discussion:
 *    Given a url, host name, and proxy dictionary (as returned by SC)
 *    produce the proxy list of attempts for establishing connnections.
 *  
 *  Parameters:
 *    
 *    scheme:
 *      The target or intended scheme which the callee thinks applies
 *      to the given url.  This value if set trumps the scheme on the
 *      url.
 *    
 *    url:
 *      A CFURLRef representing the object to be obtained.  If NULL,
 *      host must be specified.
 *    
 *    host:
 *      A CFStringRef representing the far server which will receive
 *      the connection.  If NULL, url must be specified in which case
 *      the host field from the URL will be used.
 *    
 *    proxies:
 *      A CFDictionaryRef contatining all proxy information to be
 *      considered.  All proxy information will be consulted and the
 *      best fit for the given url and host will be returned.
 *    
 *    cb:
 *      A callback function to be called once an answer to "which
 *      proxy?" is available.  If NULL, this function will block until
 *      an answer is available.
 *    
 *    clientInfo:
 *      A pointer of the caller's choosing that will be passed back
 *      when cb is invoked.  It is the caller's responsibility to
 *      ensure that the clientInfo pointer remains good until either cb
 *      is invoked or proxyStream is closed.
 *    
 *    proxyStream:
 *      The stream returned when async operation is required.  Must not
 *      be NULL if cb is non-NULL.  The caller should schedule the
 *      returned stream on whichever run loop it wishes to receive cb. 
 *      The caller must not set the client of proxyStream.
 *  
 *  Result:
 *    A CFMutableArrayRef containing the list of proxies to be
 *    attempted in respective order.  Individual proxy items are
 *    CFURLRef's where the scheme indicates the proxy type (i.e. http,
 *    https, socks4, etc.), the host indicates the proxy host name, the
 *    port indicates the proxy port, the username is the user's
 *    username on the proxy (if needed), and the password is the user's
 *    password for accessing the proxy (if needed). The username and
 *    password would primarily be needed for SOCKS.  A kCFNull in the
 *    list indicates that a direct connection is to be used and proxies
 *    should be bypassed for that attempt.  If all entries in the list
 *    are attempted, the connection has failed.  If NULL is returned,
 *    asynchronous operation has begun, and the caller should wait for
 *    their callback to be invoked, or poll via
 *    _CFNetworkCopyProxyFromProxyStream, below.
 *  
 */
extern CFMutableArrayRef 
_CFNetworkFindProxyForURLAsync(
  CFStringRef              scheme,
  CFURLRef                 url,
  CFStringRef              host,
  CFDictionaryRef          proxies,
  _CFProxyStreamCallBack   cb,
  void *                   clientInfo,
  CFReadStreamRef *        proxyStream)                       AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  _CFNetworkCopyProxyFromProxyStream()
 *  
 *  Discussion:
 *    Once an asynchronous search for the correct proxy has begun (via
 *    _CFNetworkFindProxyForURLAsync, above), call this function to
 *    discover whether the correct proxy has been found, and if so,
 *    what that proxy is.
 *  
 *  Parameters:
 *    
 *    proxyStream:
 *      The proxy stream returned by _CFNetworkFindProxyForURLAsync,
 *      above
 *    
 *    isComplete:
 *      This out parameter is set to true if the asynchronous search is
 *      now complete, or false otherwise.
 *  
 *  Result:
 *    A CFMutableArrayRef giving the discovered proxies, in the same
 *    format as returned by _CFNetworkFindProxyForURLAsync, above.
 *  
 */
extern CFMutableArrayRef 
_CFNetworkCopyProxyFromProxyStream(
  CFReadStreamRef   proxyStream,
  Boolean *         isComplete)                               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#ifdef __cplusplus
}
#endif

#endif /* __CFHTTPCONNECTIONPRIV__ */