CFHTTPAuthentication.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/CFHTTPAuthentication.h
 
     Contains:   CoreFoundation Network HTTP authentication 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:                CFHTTPAuthentication.i
                     Revision:        1.3
                     Dated:           2004/06/08 21:27:18
                     Last change by:  jwyld
                     Last comment:    Comment changes/cleanup
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFHTTPAUTHENTICATION__
#define __CFHTTPAUTHENTICATION__

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

#ifndef __COREFOUNDATION__
#include <CoreFoundation/CoreFoundation.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


/*
 *  CFHTTPAuthenticationRef
 *  
 *  Discussion:
 *    This is the type of a reference to HTTP authentication
 *    information.
 */
typedef struct _CFHTTPAuthentication*   CFHTTPAuthenticationRef;

/*
 *  CFStreamErrorHTTPAuthentication
 *  
 *  Discussion:
 *    Authentication errors which may be returned as a result of trying
 *    to apply authentication to a request.  These errors are in the
 *    kCFStreamErrorDomainHTTP domain.
 */
enum CFStreamErrorHTTPAuthentication {

  /*
   * The type of authentication to be applied to a request is not
   * supported.
   */
  kCFStreamErrorHTTPAuthenticationTypeUnsupported = -1000,

  /*
   * The username was in a format not suitable for applying to the
   * request.
   */
  kCFStreamErrorHTTPAuthenticationBadUserName = -1001,

  /*
   * The password was in a format not suitable for applying to the
   * request.
   */
  kCFStreamErrorHTTPAuthenticationBadPassword = -1002
};
typedef enum CFStreamErrorHTTPAuthentication CFStreamErrorHTTPAuthentication;


/*
 *  kCFHTTPAuthenticationUsername
 *  
 *  Discussion:
 *    CFDictionary key, for CFHTTPMessageApplyCredentialDictionary. The
 *    username for authentication as a CFString.  Needs to be added if
 *    CFHTTPAuthenticationRequiresUserNameAndPassword returns TRUE.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFHTTPAuthenticationUsername               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

/*
 *  kCFHTTPAuthenticationPassword
 *  
 *  Discussion:
 *    CFDictionary key, for CFHTTPMessageApplyCredentialDictionary. The
 *    password for authentication as a CFString.  Needs to be added if
 *    CFHTTPAuthenticationRequiresUserNameAndPassword returns TRUE.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFHTTPAuthenticationPassword               AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

/*
 *  kCFHTTPAuthenticationAccountDomain
 *  
 *  Discussion:
 *    CFDictionary key, for CFHTTPMessageApplyCredentialDictionary. The
 *    domain for authentication as a CFString.  Needs to be added if
 *    CFHTTPAuthenticationRequiresAccountDomain returns TRUE.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const CFStringRef kCFHTTPAuthenticationAccountDomain          AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

/*
 *  CFHTTPAuthenticationGetTypeID()
 *  
 *  Discussion:
 *    Returns the type identifier of all CFHTTPAuthentication instances.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFTypeID 
CFHTTPAuthenticationGetTypeID(void)                           AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationCreateFromResponse()
 *  
 *  Discussion:
 *    Based on a response of 401 or 407, this function will create a
 *    new authentication object which can be used for adding
 *    credentials to future requests.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      Allocator to use for creating authentication object
 *    
 *    response:
 *      Failed response.
 *  
 *  Result:
 *    A freshly created authentication object useful for applying
 *    authentication credentials to new requests.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFHTTPAuthenticationRef 
CFHTTPAuthenticationCreateFromResponse(
  CFAllocatorRef     alloc,
  CFHTTPMessageRef   response)                                AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationIsValid()
 *  
 *  Discussion:
 *    Returns TRUE if the given authentication information was
 *    instantiated correctly and contains enough information in order
 *    to be applied to a request. If FALSE is returned, the object may
 *    still contain information which is useful to the user, e.g.
 *    unsupported method name.  An invalid object may be queried for
 *    information but may not be applied to a request.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *    
 *    error:
 *      Reference to a CFStreamError which will be populated in the
 *      case of an error in creation.  Pass NULL if not interested in
 *      the failure reason.  The error domain will be
 *      kCFStreamErrorDomainHTTP, and the error code will be one of
 *      those defined in CFHTTPStream.h or one of those listed as
 *      CFStreamErrorHTTPAuthentication.
 *  
 *  Result:
 *    TRUE or FALSE depending on whether the authentication object is
 *    good for applying credentials to further requests.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPAuthenticationIsValid(
  CFHTTPAuthenticationRef   auth,
  CFStreamError *           error)       /* can be NULL */    AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationAppliesToRequest()
 *  
 *  Discussion:
 *    Returns TRUE if the given request requires credentials based upon
 *    the given authentication information.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *    
 *    request:
 *      The request which is believed to need the given authentication.
 *  
 *  Result:
 *    TRUE if the given authentication information should be applied to
 *    the request, otherwise FALSE is returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPAuthenticationAppliesToRequest(
  CFHTTPAuthenticationRef   auth,
  CFHTTPMessageRef          request)                          AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationRequiresOrderedRequests()
 *  
 *  Discussion:
 *    Some authentication methods require that future requests must be
 *    performed in an ordered manner, so that information from a
 *    response can be added to a following request.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    Returns TRUE if the given authentication method requires ordered
 *    requests.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPAuthenticationRequiresOrderedRequests(CFHTTPAuthenticationRef auth) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPMessageApplyCredentials()
 *  
 *  Discussion:
 *    Perform the authentication method required on the request using
 *    the given username and password.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    request:
 *      The request which is to receive the credentials.
 *    
 *    auth:
 *      The authentication information for the given request.
 *    
 *    username:
 *      The username to use for performing the authentication.
 *    
 *    password:
 *      The password to use for performing the authentication.
 *    
 *    error:
 *      Reference to a CFStreamError which will be populated with the
 *      error information should one occurr during the application of
 *      the credentials. Pass NULL if not interested in the failure
 *      reason.  The error domain will be kCFStreamErrorDomainHTTP, and
 *      the error code will be one of those define in CFHTTPStream.h or
 *      one of those listed as CFStreamErrorHTTPAuthentication.
 *  
 *  Result:
 *    TRUE will be returned if the application of the credentials to
 *    the request was successful, otherwise FALSE is returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPMessageApplyCredentials(
  CFHTTPMessageRef          request,
  CFHTTPAuthenticationRef   auth,
  CFStringRef               username,
  CFStringRef               password,
  CFStreamError *           error)          /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPMessageApplyCredentialDictionary()
 *  
 *  Discussion:
 *    Perform the authentication method required on the request using
 *    the given credential information.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    request:
 *      The request which is to receive the credentials.
 *    
 *    auth:
 *      The authentication information for the given request.
 *    
 *    dict:
 *      A dictionary containing credentials to be applied to the
 *      request.  Valid keys are declared above.
 *    
 *    error:
 *      Reference to a CFStreamError which will be populated with the
 *      error information should one occurr during the application of
 *      the credentials. Pass NULL if not interested in the failure
 *      reason.  The error domain will be kCFStreamErrorDomainHTTP, and
 *      the error code will be one of those define in CFHTTPStream.h or
 *      one of those listed as CFStreamErrorHTTPAuthentication.
 *  
 *  Result:
 *    TRUE will be returned if the application of the credentials to
 *    the request was successful, otherwise FALSE is returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPMessageApplyCredentialDictionary(
  CFHTTPMessageRef          request,
  CFHTTPAuthenticationRef   auth,
  CFDictionaryRef           dict,
  CFStreamError *           error)         /* can be NULL */  AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



/*
 *  CFHTTPAuthenticationCopyRealm()
 *  
 *  Discussion:
 *    Some authentication techniques provide for namespaces on top of
 *    domains. This call will return the authentication information's
 *    namespace if there is one, otherwise it will return NULL.  This
 *    namespace is usually used for prompting the application user for
 *    a name and password.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    This call will return the authentication information's namespace
 *    if there is one, otherwise it will return NULL.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFStringRef 
CFHTTPAuthenticationCopyRealm(CFHTTPAuthenticationRef auth)   AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationCopyDomains()
 *  
 *  Discussion:
 *    Returns a list of domain URL's on which the given authentication
 *    should be applied. This function is provided mostly for
 *    informational purposes. CFHTTPAuthenticationAppliesToRequest
 *    should be used in order to check whether a request requires the
 *    authentication.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    Returns a list of domain URL's on which the given authentication
 *    should be applied.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFArrayRef 
CFHTTPAuthenticationCopyDomains(CFHTTPAuthenticationRef auth) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationCopyMethod()
 *  
 *  Discussion:
 *    Returns the method of authentication which will be performed when
 *    applying credentials.  The strongest method of authentication
 *    will be chosen in the case of multiple choices.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    Returns the method of authentication which will be performed when
 *    applying credentials.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.2 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFStringRef 
CFHTTPAuthenticationCopyMethod(CFHTTPAuthenticationRef auth)  AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;



/*
 *  CFHTTPAuthenticationRequiresUserNameAndPassword()
 *  
 *  Discussion:
 *    Returns TRUE if the chosen authentication scheme requires a
 *    username and password.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    Returns TRUE if the chosen authentication scheme requires a
 *    username and password.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPAuthenticationRequiresUserNameAndPassword(CFHTTPAuthenticationRef auth) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;



/*
 *  CFHTTPAuthenticationRequiresAccountDomain()
 *  
 *  Discussion:
 *    Returns TRUE if the chosen authentication scheme requires a
 *    domain for authentication.  Currently, this will return TRUE for
 *    "NTLM" and FALSE for the other methods.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The API's to CFHTTPAuthenticationRef are thread-safe so long as
 *    multiple threads are not altering the same
 *    CFHTTPAuthenticationRef at the same time.
 *  
 *  Parameters:
 *    
 *    auth:
 *      The authentication information being queried.
 *  
 *  Result:
 *    Returns TRUE if the chosen authentication scheme requires a
 *    domain for authentication.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHTTPAuthenticationRequiresAccountDomain(CFHTTPAuthenticationRef auth) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#ifdef __cplusplus
}
#endif

#endif /* __CFHTTPAUTHENTICATION__ */