/* File: CFNetwork/CFHTTPMessage.h Contains: CoreFoundation Network socket streams header Copyright: Copyright (c) 2001-2008, Apple Inc. All rights reserved. Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __CFHTTPMESSAGE__ #define __CFHTTPMESSAGE__ #ifndef __CFNETWORKDEFS__ #include #endif #ifndef __CFSTRING__ #include #endif #ifndef __CFURL__ #include #endif #include #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif /* * kCFHTTPVersion1_0 * * Discussion: * Version string for HTTP 1.0. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPVersion1_0 __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * kCFHTTPVersion1_1 * * Discussion: * Version string for HTTP 1.1. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPVersion1_1 __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * kCFHTTPAuthenticationSchemeBasic * * Discussion: * HTTP Basic authentication scheme. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeBasic __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0); /* * kCFHTTPAuthenticationSchemeDigest * * Discussion: * HTTP Digest Access authentication scheme. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeDigest __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0); /* * kCFHTTPAuthenticationSchemeNTLM * * Discussion: * HTTP NTLM authentication scheme. * * Availability: * Mac OS X: in version 10.5 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeNTLM __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_2_0); /* * kCFHTTPAuthenticationSchemeNegotiate * * Discussion: * HTTP Negotiate authentication scheme. * * Availability: * Mac OS X: in version 10.5 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeNegotiate __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_2_0); /* * kCFHTTPAuthenticationSchemeNegotiate2 * * Discussion: * HTTP Negotiate v2 authentication scheme. * * Availability: * Mac OS X: in version 10.6 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeNegotiate2 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_3_0); /* * kCFHTTPAuthenticationSchemeXMobileMeAuthToken * * Discussion: * HTTP XMobileMeAuthToken authentication scheme. * * Availability: * Mac OS X: in version 10.6 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeXMobileMeAuthToken __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_3); /* * kCFHTTPAuthenticationSchemeKerberos * * Discussion: * HTTP Negotiate authentication scheme. * * Availability: * Mac OS X: in version 10.7 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT const CFStringRef kCFHTTPAuthenticationSchemeKerberos __OSX_AVAILABLE_STARTING(__MAC_10_5 /* REMINDSMA: 10_7 */,__IPHONE_2_0 /* REMINDSMA: 4_0 */); /* * CFHTTPMessageRef * * Discussion: * This is the type of a reference to an HTTP message. An HTTP * message can be a request or a response. */ typedef struct __CFHTTPMessage* CFHTTPMessageRef; /* * CFHTTPMessageGetTypeID() * * Discussion: * Return the unique type for this class. * * Mac OS X threading: * Thread safe * * Result: * A unique CFType for CFHTTPMessage. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFTypeID CFHTTPMessageGetTypeID(void) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCreateRequest() * * Discussion: * Create an HTTPMessage from an HTTP method, url and version. * * Mac OS X threading: * Thread safe * * 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. * * requestMethod: * A pointer to a CFString indicating the method of request. For a * "GET" request, for example, the value would be CFSTR("GET"). * * url: * A pointer to a CFURL structure created any of the several * CFURLCreate... functions. If this parameter is not a pointer * to a valid CFURL structure, the behavior is undefined. * * httpVersion: * A pointer to a CFString indicating the version of request. * * Result: * A pointer to the CFHTTPMessage created, or NULL if failed. It is * caller's responsibilty to release the memory allocated for the * message. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFHTTPMessageRef CFHTTPMessageCreateRequest( CFAllocatorRef alloc, CFStringRef requestMethod, CFURLRef url, CFStringRef httpVersion) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCreateResponse() * * Discussion: * Create an HTTPMessage from an HTTP status code, description and * version. * * Mac OS X threading: * Thread safe * * 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. * * statusCode: * An integer status code for the response. * * statusDescription: * A pointer to a CFString for the status. Pass NULL to use the * standard description for the given status code, as found in RFC * 2616. * * httpVersion: * A pointer to a CFString for the HTTP version. * * Result: * A pointer to the CFHTTPMessage created, or NULL if failed. It is * caller's responsibilty to release the memory allocated for the * message. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFHTTPMessageRef CFHTTPMessageCreateResponse( CFAllocatorRef alloc, CFIndex statusCode, CFStringRef statusDescription, CFStringRef httpVersion) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCreateEmpty() * * Discussion: * Creates an empty request or response, which you can then append * bytes to via CFHTTPMessageAppendBytes(). * * Mac OS X threading: * Thread safe * * 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. * * isRequest: * A boolean. Pass kCFBooleanTrue if the message should be a * request. * * Result: * A pointer to the CFHTTPMessage created, or NULL if failed. It is * caller's responsibilty to release the memory allocated for the * message. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFHTTPMessageRef CFHTTPMessageCreateEmpty( CFAllocatorRef alloc, Boolean isRequest) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCreateCopy() * * Discussion: * Creates a copy of a CFHTTPMessage. * * Mac OS X threading: * Not thread safe * * 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. * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A pointer to the CFHTTPMessage created, or NULL if failed. It is * caller's responsibilty to release the memory allocated for the * message. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFHTTPMessageRef CFHTTPMessageCreateCopy( CFAllocatorRef alloc, CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageIsRequest() * * Discussion: * Returns whether the CFHTTPMessage is a request or a response. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A Boolean. A value of kCFBooleanTrue indicates the message is a * request. A value of kCFBooleanFalse indicates the message is a * response. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT Boolean CFHTTPMessageIsRequest(CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyVersion() * * Discussion: * Returns the HTTP version. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A pointer to a CFString, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the string. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFStringRef CFHTTPMessageCopyVersion(CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyBody() * * Discussion: * Returns the body of the message. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A pointer to a CFData, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the data. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFDataRef CFHTTPMessageCopyBody(CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageSetBody() * * Discussion: * Sets the body of the message from a CFData. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * bodyData: * A pointer to a CFData containing the body to be set. If the * bodyData is NULL, the behavior is undefined. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT void CFHTTPMessageSetBody( CFHTTPMessageRef message, CFDataRef bodyData) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyHeaderFieldValue() * * Discussion: * Returns the specified header field. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * headerField: * A pointer to the CFString. If the headerField is NULL, the * behavior is undefined. * * Result: * A pointer to a CFString, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the string. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFStringRef CFHTTPMessageCopyHeaderFieldValue( CFHTTPMessageRef message, CFStringRef headerField) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyAllHeaderFields() * * Discussion: * Returns a CFDictionary containing all of the header fields. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A pointer to a CFDictionary, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the dictionary. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFDictionaryRef CFHTTPMessageCopyAllHeaderFields(CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageSetHeaderFieldValue() * * Discussion: * Sets the value of the specified header field. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * headerField: * A pointer to the CFString. If headerField is NULL, the behavior * is undefined. * * value: * A pointer to the CFString containing the value to set. Set the * value to NULL to remove the header field. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT void CFHTTPMessageSetHeaderFieldValue( CFHTTPMessageRef message, CFStringRef headerField, CFStringRef value) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageAppendBytes() * * Discussion: * Appends the given bytes to the message given (parsing out any * control information if appropriate). Returns kCFBooleanFalse if * a parsing error occurs while processing the new data. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * newBytes: * A pointer to the bytes. If newBytes is NULL, the behavior is * undefined. * * numBytes: * A CFIndex of the number of bytes to append. * * Result: * A Boolean indicating success or failure. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT Boolean CFHTTPMessageAppendBytes( CFHTTPMessageRef message, const UInt8 * newBytes, CFIndex numBytes) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageIsHeaderComplete() * * Discussion: * Returns whether further header data is expected by the message. * * Mac OS X threading: * Not thread safe * * Parameters: * * message: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A Boolean. A value of kCFBooleanTrue indicates the header is * complete and no further data is expected. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT Boolean CFHTTPMessageIsHeaderComplete(CFHTTPMessageRef message) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopySerializedMessage() * * Discussion: * Creates a self-contained copy of a CFHTTPMessage. This would be * suitable for persistant storage or for transmitting over the * network independently. * * Mac OS X threading: * Not thread safe * * Parameters: * * request: * A pointer to the CFHTTPMessage to be seralized. * * Result: * A pointer to a CFData, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the data. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFDataRef CFHTTPMessageCopySerializedMessage(CFHTTPMessageRef request) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /*********************/ /* Request functions */ /*********************/ /* * CFHTTPMessageCopyRequestURL() * * Discussion: * Creates a copy of the request URL. * * Mac OS X threading: * Not thread safe * * Parameters: * * request: * A pointer to the CFHTTPMessage. * * Result: * A pointer to a CFURL, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the url. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFURLRef CFHTTPMessageCopyRequestURL(CFHTTPMessageRef request) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyRequestMethod() * * Discussion: * Creates a copy of the request method. * * Mac OS X threading: * Not thread safe * * Parameters: * * request: * A pointer to the CFHTTPMessage. * * Result: * A pointer to a CFString, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the string. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFStringRef CFHTTPMessageCopyRequestMethod(CFHTTPMessageRef request) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageAddAuthentication() * * Discussion: * Adds authentication to the request. Tries to modify request to * contain the authentication information requested by the failed * response (which presumably is a 401 or 407 response). * * Mac OS X threading: * Not thread safe * * Parameters: * * request: * A pointer to a CFHTTPMessage request. * * authenticationFailureResponse: * A pointer to a CFHTTPMessage of the failed response. * * username: * A pointer to a CFString containing the user name to * authenticate. * * password: * A pointer to a CFString containing the password of the user. * * authenticationScheme: * A pointer to a CFString containing the authentication scheme to * use to authenticate. If authenticationScheme is NULL, strongest * supported scheme listed authenticationFailureResponse will be * used. * * forProxy: * A boolean indicating whether the authentication applies to a * proxy or not. * * Result: * A pointer to a CFString, or NULL if failed. It is caller's * responsibilty to release the memory allocated for the string. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT Boolean CFHTTPMessageAddAuthentication( CFHTTPMessageRef request, CFHTTPMessageRef authenticationFailureResponse, CFStringRef username, CFStringRef password, CFStringRef authenticationScheme, Boolean forProxy) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /**********************/ /* Response functions */ /**********************/ /* * CFHTTPMessageGetResponseStatusCode() * * Discussion: * Returns the status code for the response. * * Mac OS X threading: * Not thread safe * * Parameters: * * response: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A UInt32 indicating the status code. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFIndex CFHTTPMessageGetResponseStatusCode(CFHTTPMessageRef response) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); /* * CFHTTPMessageCopyResponseStatusLine() * * Discussion: * Returns the status line for the response. * * Mac OS X threading: * Not thread safe * * Parameters: * * response: * A pointer to the CFHTTPMessage to be copied. If the message is * NULL, the behavior is undefined. * * Result: * A CFString indicating the status code, or NULL if failed. It is * caller's responsibilty to release the memory allocated for the * string. * * Availability: * Mac OS X: in version 10.1 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ CFN_EXPORT CFStringRef CFHTTPMessageCopyResponseStatusLine(CFHTTPMessageRef response) __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0); #ifdef __cplusplus } #endif #endif /* __CFHTTPMESSAGE__ */