iOS Developer Library

Developer

CoreServices Framework Reference CFHTTPStream Reference

Options
Deployment Target:

On This Page
Language:

CFHTTPStream Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CFNetwork

Objective-C

@import CFNetwork;

This document describes the CFStream functions for working with HTTP connections.

Functions

  • Creates a read stream for a CFHTTP request message.

    Declaration

    Swift

    func CFReadStreamCreateForHTTPRequest(_ alloc: CFAllocator!, _ request: CFHTTPMessage!) -> Unmanaged<CFReadStream>!

    Objective-C

    CFReadStreamRef CFReadStreamCreateForHTTPRequest ( CFAllocatorRef alloc, CFHTTPMessageRef request );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    request

    A CFHTTP request message whose body and headers have been set.

    Return Value

    A new read stream, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Discussion

    This function creates a read stream and associates it with the specified request. Automatic redirection is disabled by default. After creating the read stream, you can call CFReadStreamGetError at any time to check the status of the stream. You may want to call CFHTTPReadStreamSetRedirectsAutomatically to enable automatic redirection, or CFHTTPReadStreamSetProxy to set the name and port number for a proxy. To serialize the request and send it, call CFReadStreamOpen.

    If the body of the request is too long to keep in memory, call CFReadStreamCreateForStreamedHTTPRequest instead of this function.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Creates a read stream for a CFHTTP request message object whose body is too long to keep in memory.

    Declaration

    Swift

    func CFReadStreamCreateForStreamedHTTPRequest(_ alloc: CFAllocator!, _ requestHeaders: CFHTTPMessage!, _ requestBody: CFReadStream!) -> Unmanaged<CFReadStream>!

    Objective-C

    CFReadStreamRef CFReadStreamCreateForStreamedHTTPRequest ( CFAllocatorRef alloc, CFHTTPMessageRef requestHeaders, CFReadStreamRef requestBody );

    Parameters

    alloc

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    requestHeaders

    A CFHTTP request header.

    requestBody

    Read stream reference for the request body.

    Return Value

    A new read stream, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Discussion

    This function creates a read stream for the response to the requestHeaders plus requestBody. Call this function instead of CFReadStreamCreateForHTTPRequest when the body of the request is so long that you do not want it to be resident in memory.

    Because streams cannot be reset, read streams created this way cannot be enabled for autoredirection.

    If the Content-Length header is set in requestHeaders, it is assumed that the length is correct 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.

    After creating the read stream, you can call CFReadStreamGetError at any time to check the status of the stream. You may want to call CFHTTPReadStreamSetProxy to set the name and port number for a proxy. To serialize the request and send it, call CFReadStreamOpen.

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

Constants

  • Error codes that a read stream for an HTTP request may return.

    Declaration

    Swift

    enum CFStreamErrorHTTP : Int32 { case ParseFailure case RedirectionLoop case BadURL }

    Objective-C

    typedef enum { kCFStreamErrorHTTPParseFailure = -1, kCFStreamErrorHTTPRedirectionLoop = -2, kCFStreamErrorHTTPBadURL = -3 } CFStreamErrorHTTP;

    Constants

    • ParseFailure

      kCFStreamErrorHTTPParseFailure

      A parsing error occurred while an incoming message was being deserialized and appended to a message object. The headers of the incoming message may be formatted improperly.

      Available in iOS 2.0 and later

    • RedirectionLoop

      kCFStreamErrorHTTPRedirectionLoop

      A redirection loop has been detected.

      Available in iOS 2.0 and later

    • BadURL

      kCFStreamErrorHTTPBadURL

      The URL is not properly formatted.

      Available in iOS 2.0 and later

    Import Statement

    Objective-C

    @import CFNetwork;

    Swift

    import CFNetwork

    Availability

    Available in iOS 2.0 and later

  • Constants for setting and copying CFStream HTTP properties.

    Declaration

    Swift

    let kCFStreamPropertyHTTPAttemptPersistentConnection: CFString! let kCFStreamPropertyHTTPFinalURL: CFString! let kCFStreamPropertyHTTPFinalRequest: CFString! let kCFStreamPropertyHTTPProxy: CFString! let kCFStreamPropertyHTTPProxyHost: CFString! let kCFStreamPropertyHTTPProxyPort: CFString! let kCFStreamPropertyHTTPRequestBytesWrittenCount: CFString! let kCFStreamPropertyHTTPResponseHeader: CFString! let kCFStreamPropertyHTTPSProxyHost: CFString! let kCFStreamPropertyHTTPSProxyPort: CFString! let kCFStreamPropertyHTTPShouldAutoredirect: CFString!

    Objective-C

    const CFStringRef kCFStreamPropertyHTTPAttemptPersistentConnection; const CFStringRef kCFStreamPropertyHTTPFinalURL; extern const CFStringRef kCFStreamPropertyHTTPFinalRequest; const CFStringRef kCFStreamPropertyHTTPProxy; const CFStringRef kCFStreamPropertyHTTPRequestBytesWrittenCount; const CFStringRef kCFStreamPropertyHTTPResponseHeader; const CFStringRef kCFStreamPropertyHTTPShouldAutoredirect;

    Constants

    • kCFStreamPropertyHTTPAttemptPersistentConnection

      kCFStreamPropertyHTTPAttemptPersistentConnection

      HTTP Attempt Persistent Connection property. The value of this property is a CFBoolean. If this property is set to kCFBooleanTrue, the HTTP stream looks for an appropriate existing persistent connection to use. If it cannot find one, the HTTP stream will try to create one.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPFinalURL

      kCFStreamPropertyHTTPFinalURL

      HTTP Final URL property. A value of type CFURL containing the final HTTP URL. This value differs from the URL in the original HTTP request if an autoredirection occurred. This property cannot be set.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPFinalRequest

      kCFStreamPropertyHTTPFinalRequest

      HTTP Final Request property. A value of type CFHTTPMessage containing the final message transmitted by the stream after all modifications (including authentication, connection policy, redirects, and so on) have been made. This property cannot be set.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPProxy

      kCFStreamPropertyHTTPProxy

      HTTP Proxy property. To cause an HTTP CFStream to use an HTTP proxy, set the value of this property to a CFDictionary that includes at least one host/port pair described in “CFStream SOCKS Proxy Key Constants” in CFStream Reference. SystemConfiguration returns a CFDictionary that is usable without modification.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPProxyHost

      kCFStreamPropertyHTTPProxyHost

      HTTP Proxy Host property. If an HTTP CFStream is using an HTTP proxy, the value of this property is a CFString containing the host name or IP number of the proxy server.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPProxyPort

      kCFStreamPropertyHTTPProxyPort

      HTTP Proxy Host property. If an HTTP CFStream is using an HTTP proxy, the value of this property is a CFNumber containing the port number of the proxy server.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPRequestBytesWrittenCount

      kCFStreamPropertyHTTPRequestBytesWrittenCount

      HTTP Request Bytes Written property. This property can only be retrieved; it cannot be set. The value of this property is a CFNumber containing the number of body bytes that have been written to the server thus far. HTTP header bytes are not included in the count. You can use this property to track the progress of HTTP uploads that take a substantial amount of time to complete.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPResponseHeader

      kCFStreamPropertyHTTPResponseHeader

      HTTP Response Header property. When copied by CFReadStreamCopyProperty, the header of an HTTP response message is returned.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPSProxyHost

      kCFStreamPropertyHTTPSProxyHost

      HTTPS Proxy Host property. If a CFStream is using an HTTPS proxy, the value of this property is a CFString containing the host name or IP number of the proxy server.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPSProxyPort

      kCFStreamPropertyHTTPSProxyPort

      HTTPS Proxy Host property. If a CFStream is using an HTTPS proxy, the value of this property is a CFNumber containing the port number of the proxy server.

      Available in iOS 2.0 and later

    • kCFStreamPropertyHTTPShouldAutoredirect

      kCFStreamPropertyHTTPShouldAutoredirect

      HTTP Should Auto Redirect property. Set this property to kCFBooleanTrue to enable autoredirection; set this property to kCFBooleanFalse to disable autoredirection.

      Available in iOS 2.0 and later

    Discussion

    The CFStream HTTP property constants are used to specify the HTTP property to set when calling CFReadStreamSetProperty or CFWriteStreamSetProperty. They are also used to specify the HTTP property to copy when calling CFReadStreamCopyProperty or CFWriteStreamCopyProperty.

  • Error domains specific to CFHTTPStream calls.

    Declaration

    Swift

    let kCFStreamErrorDomainHTTP: Int32

    Objective-C

    extern const SInt32 kCFStreamErrorDomainHTTP;

    Constants

    • kCFStreamErrorDomainHTTP

      kCFStreamErrorDomainHTTP

      Error domain that returns errors associated with the CFHTTPStream layer.

      Available in iOS 2.0 and later

    Discussion

    To determine the source of an error, examine the userInfo dictionary included in the CFError object returned by a function call or call CFErrorGetDomain and pass in the CFError object and the domain whose value you want to read.