Next Page >

Hide TOC

CFHTTPStream Reference

Derived from	CFType
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

CFHTTPReadStreamSetProxy

This function sets the proxy host for a read stream. (Deprecated. Use kCFStreamPropertyHTTPProxy instead.)

void CFHTTPReadStreamSetProxy (
   CFReadStreamRef httpStream,
   CFStringRef proxyHost,
   CFIndex proxyPort
);

Parameters

httpStream: The read stream for which a proxy is to be set.
proxyHost: The proxy’s fully qualified domain name or IP address in dotted decimal format.
proxyPort: The port number the proxy uses.

Discussion

Call this function if the URL for this read stream can only be reached through a proxy.

Availability

Available in Mac OS X version 10.1 and later.
Deprecated in Mac OS X version 10.3.

Declared In

CFHTTPStream.h

CFHTTPReadStreamSetRedirectsAutomatically

This function enables or disables automatic redirection for a read stream. (Deprecated. Use the kCFStreamPropertyHTTPShouldAutoredirect property instead.)

void CFHTTPReadStreamSetRedirectsAutomatically (
   CFReadStreamRef httpStream,
   Boolean shouldAutoRedirect
);

Parameters

httpStream: The read stream for which automatic redirection is to be enabled or disabled.
shouldAutoRedirect: TRUE to enable automatic redirection for the specified stream; FALSE to disable automatic redirection.

Discussion

Call this function before you call CFReadStreamOpen to open the read stream. Enabling automatic redirection allows the read stream to be redirected if the URL to which a request is sent is redirected to another URL. If automatic redirection is not enabled, and the URL to which a request is sent redirects the request, the response to this message will contain a response code ranging from 300 to 307.

Availability

Available in Mac OS X version 10.1 and later.
Deprecated in Mac OS X version 10.3.

Declared In

CFHTTPStream.h

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 Mac OS X version 10.1 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 Mac OS X version 10.2 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 Mac OS X v10.1 and later.

Declared in CFHTTPStream.h.

kCFStreamErrorHTTPRedirectionLoop

A redirection loop has been detected.

Available in Mac OS X v10.1 and later.

Declared in CFHTTPStream.h.

kCFStreamErrorHTTPBadURL

The URL is not properly formatted.

Available in Mac OS X v10.1 and later.

Declared in CFHTTPStream.h.

Availability

Available in Mac 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X version 10.5 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 Mac OS X v10.2 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 Mac OS X version 10.2 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 Mac OS X version 10.2 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 Mac OS X v10.3 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 Mac OS X v10.1 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 Mac OS X version 10.2 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 Mac OS X version 10.2 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 Mac OS X v10.2 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 Mac 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 Mac OS X v10.1 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.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.