CFHTTPStream.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/CFHTTPStream.h
 
     Contains:   CoreFoundation Network HTTP streams header
 
     Copyright:   2001-2005 by Apple Computer, Inc., all rights reserved
 
     Warning:    *** APPLE INTERNAL USE ONLY ***
                 This file may contain unreleased API's
 
     BuildInfo:  Built by:            anonymous
                 On:                  Wed Apr 27 10:45:36 2005
                 With Interfacer:     3.0d46   (Mac OS X for PowerPC)
                 From:                CFHTTPStream.i
                     Revision:        1.6
                     Dated:           2004/08/03 22:57:05
                     Last change by:  jiarocci
                     Last comment:    Update Interface files to include headerdoc and remove warnings.
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFHTTPSTREAM__
#define __CFHTTPSTREAM__

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

#ifndef __CFSTREAM__
#include <CoreFoundation/CFStream.h>
#endif

#ifndef __CFHTTPMESSAGE__
#include <CFNetwork/CFHTTPMessage.h>
#endif





#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint on
#endif

/*
 *  kCFStreamErrorDomainHTTP
 *  
 *  Discussion:
 *    Result code returned by HTTP server
 *  
 *  Availability:
 *    Mac OS X:         in version 10.1 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const SInt32 kCFStreamErrorDomainHTTP                         AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;

/*
 *  CFStreamErrorHTTP
 *  
 *  Discussion:
 *    Errors from the kCFStreamErrorDomainHTTP domain.
 */
enum CFStreamErrorHTTP {

  /*
   * Could not parse the request/response.
   */
  kCFStreamErrorHTTPParseFailure = -1,

  /*
   * A loop was detected during redirection.
   */
  kCFStreamErrorHTTPRedirectionLoop = -2,

  /*
   * Could not retreive url for request/response.
   */
  kCFStreamErrorHTTPBadURL      = -3
};
typedef enum CFStreamErrorHTTP CFStreamErrorHTTP;

/*
 *  kCFStreamPropertyHTTPResponseHeader
 *  
 *  Discussion:
 *    Stream property key, for copy operations. Value is a
 *    CFHTTPMessage with 0 bytes data.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.1 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPResponseHeader         AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;


/*
 *  kCFStreamPropertyHTTPFinalURL
 *  
 *  Discussion:
 *    Stream property key, for copy operations. The response header
 *    value is the CFURL from the final request; will only differ from
 *    the URL in the original request if an autoredirection has
 *    occurred.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPFinalURL               AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  kCFStreamPropertyHTTPProxy
 *  
 *  Discussion:
 *    Stream property key, for both set and copy operations. The value
 *    is a CFDictionary. HTTP proxy information is set the same way as
 *    SOCKS proxies (see CFSocketStream.h). Call
 *    CFReadStreamSetProperty() passing an HTTP stream and the property
 *    kCFStreamPropertyHTTPProxy. The value should include at least one
 *    Host/Port pair from the keys below. Use the dictionary returned
 *    by SystemConfiguration.framework to set the default values for
 *    the system. HTTP proxies are not applied automatically.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPProxy                  AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  kCFStreamPropertyHTTPProxyHost
 *  
 *  Discussion:
 *    Proxy dictionary key. The hostname of an HTTP proxy. The value is
 *    a CFString. The key name matches kSCPropNetProxiesHTTPProxy.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPProxyHost              AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  kCFStreamPropertyHTTPProxyPort
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFNumber.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPProxyPort              AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* matches kSCPropNetProxiesHTTPPort */


/*
 *  kCFStreamPropertyHTTPSProxyHost
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFString.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPSProxyHost             AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* matches kSCPropNetProxiesHTTPSProxy */


/*
 *  kCFStreamPropertyHTTPSProxyPort
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFNumber.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPSProxyPort             AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;
/* matches kSCPropNetProxiesHTTPSPort */


/*
 *  kCFStreamPropertyHTTPShouldAutoredirect
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFBoolean. Redirection is not
 *    performed by default.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPShouldAutoredirect     AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  kCFStreamPropertyHTTPAttemptPersistentConnection
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFBoolean.  If this property is
 *    set to kCFBooleanTrue, an HTTP stream will look for an
 *    appropriate extant persistent connection to use, and if it finds
 *    none, will try to create one. Persistent connections are not used
 *    by default.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPAttemptPersistentConnection AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  kCFStreamPropertyHTTPRequestBytesWrittenCount
 *  
 *  Discussion:
 *    Proxy dictionary key. Value is a CFNumber. This property can only
 *    be retrieved, not set. The number returned is the number of bytes
 *    from the body of the request that have been written to the
 *    underlying socket
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFStreamPropertyHTTPRequestBytesWrittenCount AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*********************/
/* Creation routines */
/*********************/
/*
 *  CFReadStreamCreateForHTTPRequest()
 *  
 *  Discussion:
 *    Create an HTTP read stream for the response to the given request.
 *    When the stream is opened, it will begin transmitting the
 *    request. The bytes returned are the pure body bytes; the response
 *    header has been parsed off. To retrieve the response header, ask
 *    for kCFStreamPropertyHTTPResponseHeader, above, any time after
 *    the first bytes arrive on the stream (or when stream end is
 *    reported, if there are no data bytes). When an HTTP/1.1 server
 *    returns a chunked a response, the chunks will be formed into one
 *    continuous stream.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      A pointer to the CFAllocator which should be used to allocate
 *      memory for the CF read stream and its storage for values. If
 *      this reference is not a valid CFAllocator, the behavior is
 *      undefined.
 *    
 *    request:
 *      A pointer to a CFHTTPMessage created by the
 *      CFHTTPMessageCreateRequest function.
 *  
 *  Result:
 *    A pointer to the CF read stream created, or NULL if failed. It is
 *    caller's responsibilty to release the memory allocated for the
 *    read stream.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.1 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFReadStreamRef 
CFReadStreamCreateForHTTPRequest(
  CFAllocatorRef     alloc,
  CFHTTPMessageRef   request)                                 AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;


/*
 *  CFReadStreamCreateForStreamedHTTPRequest()
 *  
 *  Discussion:
 *    Creates a read stream for the response to the given
 *    requestHeaders plus requestBody. Use in preference to
 *    CFReadStreamCreateForHTTPRequest() when the body of the request
 *    is larger than you wish to be resident in memory.  Note that
 *    because streams cannot be reset, read streams created this way
 *    cannot have autoredirection enabled.  If the Content-Length
 *    header is set in requestHeaders, it is assumed that the caller
 *    got the length right and that requestBody will report
 *    end-of-stream after precisely Content-Length bytes have been read
 *    from it. If the Content-Length header is not set, the chunked
 *    transfer-encoding will be added to requestHeaders, and bytes read
 *    from requestBody will be transmitted chunked. The body of
 *    requestHeaders is ignored.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      A pointer to the CFAllocator which should be used to allocate
 *      memory for the CF read stream and its storage for values. If
 *      this reference is not a valid CFAllocator, the behavior is
 *      undefined.
 *    
 *    requestHeaders:
 *      A pointer to a CFHTTPMessage created by the
 *      CFHTTPMessageCreateRequest function. The body of requestHeaders
 *      is ignored.
 *    
 *    requestBody:
 *      A pointer to a CFReadStream.
 *  
 *  Result:
 *    A pointer to the CF read stream created, or NULL if failed. It is
 *    caller's responsibilty to release the memory allocated for the
 *    read stream.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFReadStreamRef 
CFReadStreamCreateForStreamedHTTPRequest(
  CFAllocatorRef     alloc,
  CFHTTPMessageRef   requestHeaders,
  CFReadStreamRef    requestBody)                             AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;


/*
 *  CFHTTPReadStreamSetRedirectsAutomatically()   *** DEPRECATED ***
 *  
 *  Deprecated:
 *    Use the kCFStreamPropertyHTTPShouldAutoredirect property above
 *    instead.
 *  
 *  Discussion:
 *    Sets the redirection property on the http stream.
 *  
 *  Parameters:
 *    
 *    httpStream:
 *      A pointer to the CFHTTPStream to be set.
 *    
 *    shouldAutoRedirect:
 *      A boolean indicating whether to redirect or not.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.1 and later in CoreServices.framework but deprecated in 10.3
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFHTTPReadStreamSetRedirectsAutomatically(
  CFReadStreamRef   httpStream,
  Boolean           shouldAutoRedirect)                       AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3;


/*
 *  CFHTTPReadStreamSetProxy()   *** DEPRECATED ***
 *  
 *  Deprecated:
 *    Use the kCFStreamPropertyHTTPProxy above instead.
 *  
 *  Discussion:
 *    Sets the redirection property on the http stream.
 *  
 *  Parameters:
 *    
 *    httpStream:
 *      A pointer to the CFHTTPStream to be set.
 *    
 *    proxyHost:
 *      The proxy hostname. A CFString value.
 *    
 *    proxyPort:
 *      The port number. A CFNumber value.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.1 and later in CoreServices.framework but deprecated in 10.3
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFHTTPReadStreamSetProxy(
  CFReadStreamRef   httpStream,
  CFStringRef       proxyHost,
  CFIndex           proxyPort)                                AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#ifdef __cplusplus
}
#endif

#endif /* __CFHTTPSTREAM__ */