CFHTTPStream Reference

Derived from
Framework
CoreServices
Declared in
CFHTTPStream.h
Companion guides
Getting Started with Networking
CFNetwork Programming Guide

Overview

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

Functions

CFReadStreamCreateForHTTPRequest

Creates a read stream for a CFHTTP request message.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPStream.h

CFReadStreamCreateForStreamedHTTPRequest

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

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFHTTPStream.h

Constants

CFStream HTTP Error Constants

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

typedef enum {
   kCFStreamErrorHTTPParseFailure = -1,
   kCFStreamErrorHTTPRedirectionLoop = -2,
   kCFStreamErrorHTTPBadURL = -3
} CFStreamErrorHTTP;
Constants
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.

Declared in CFHTTPStream.h.

kCFStreamErrorHTTPRedirectionLoop

A redirection loop has been detected.

Available in iOS 2.0 and later.

Declared in CFHTTPStream.h.

kCFStreamErrorHTTPBadURL

The URL is not properly formatted.

Available in iOS 2.0 and later.

Declared in CFHTTPStream.h.

Availability
  • Available in OS X version 10.1 and later.
Declared In
<CFNetwork/CFHTTPStream.h>

CFStream HTTP Property Constants

Constants for setting and copying CFStream HTTP properties.

const CFStringRef kCFStreamPropertyHTTPAttemptPersistentConnection;
const CFStringRef kCFStreamPropertyHTTPFinalURL;
extern const CFStringRef kCFStreamPropertyHTTPFinalRequest;
const CFStringRef kCFStreamPropertyHTTPProxy;
const CFStringRef kCFStreamPropertyHTTPRequestBytesWrittenCount;
const CFStringRef kCFStreamPropertyHTTPResponseHeader;
const CFStringRef kCFStreamPropertyHTTPShouldAutoredirect;
Constants
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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

Available in iOS 2.0 and later.

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.

Declared in CFHTTPStream.h.

Available in iOS 2.0 and later.

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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

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.

Declared in CFHTTPStream.h.

Available in iOS 2.0 and later.

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.

Declared in CFHTTPStream.h.

Available in iOS 2.0 and later.

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.

Declared in CFHTTPStream.h.

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.

Availability
  • Available in OS X version 10.1 and later.
Declared In
<CFNetwork/CFHTTPStream.h>

Error Domains

Error domains specific to CFHTTPStream calls.

extern const SInt32 kCFStreamErrorDomainHTTP;
Constants
kCFStreamErrorDomainHTTP

Error domain that returns errors associated with the CFHTTPStream layer.

Available in iOS 2.0 and later.

Declared in CFHTTPStream.h.

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.