CFHost.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/CFHost.h
 
     Contains:   CoreFoundation CFHost 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:                CFHost.i
                     Revision:        1.8
                     Dated:           2004/06/01 17:53:05
                     Last change by:  rew
                     Last comment:    Updating all copyrights to include 2004
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFHOST__
#define __CFHOST__

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

#ifndef __COREFOUNDATION__
#include <CoreFoundation/CoreFoundation.h>
#endif




#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#pragma options align=mac68k

#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint on
#endif


/*
 *  CFHostRef
 *  
 *  Discussion:
 *    This is the type of a reference to a host name or address lookup.
 */
typedef struct __CFHost*                CFHostRef;

/*
 *  kCFStreamErrorDomainNetDB
 *  
 *  Discussion:
 *    Errors listed in netdb.h
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const SInt32 kCFStreamErrorDomainNetDB                        AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  kCFStreamErrorDomainSystemConfiguration
 *  
 *  Discussion:
 *    Errors listed in SystemConfiguration/SystemConfiguration.h
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern const SInt32 kCFStreamErrorDomainSystemConfiguration          AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;



/*
 *  CFHostInfoType
 *  
 *  Discussion:
 *    Host information types to be resolved.
 */
enum CFHostInfoType {

  /*
   * Results value is a CFArray of CFData's (each being a struct
   * sockaddr)
   */
  kCFHostAddresses              = 0,

  /*
   * Results value is a CFArray of CFString's
   */
  kCFHostNames                  = 1,

  /*
   * Results value is a CFData wrapping SCNetworkConnectionFlags
   * (defined in SystemConfiguration/SCNetwork.h)
   */
  kCFHostReachability           = 2
};
typedef enum CFHostInfoType CFHostInfoType;


/*
 *  CFHostClientContext
 *  
 *  Discussion:
 *    Structure containing the user-defined data and callbacks for
 *    CFHost objects.
 */
struct CFHostClientContext {

  /*
   * The version number of the structure type being passed in as a
   * parameter to the CFHost client function. Valid version number is
   * currently 0.
   */
  CFIndex             version;

  /*
   * An arbitrary pointer to client-defined data, which can be
   * associated with the host and is passed to the callbacks.
   */
  void *              info;

  /*
   * The callback used to add a retain for the host on the info pointer
   * for the life of the host, and may be used for temporary references
   * the host needs to take. This callback returns the actual info
   * pointer to store in the host, almost always just the pointer
   * passed as the parameter.
   */
  CFAllocatorRetainCallBack  retain;

  /*
   * The callback used to remove a retain previously added for the host
   * on the info pointer.
   */
  CFAllocatorReleaseCallBack  release;

  /*
   * The callback used to create a descriptive string representation of
   * the info pointer (or the data pointed to by the info pointer) for
   * debugging purposes. This is used by the CFCopyDescription()
   * function.
   */
  CFAllocatorCopyDescriptionCallBack  copyDescription;
};
typedef struct CFHostClientContext      CFHostClientContext;

/*
 *  CFHostClientCallBack
 *  
 *  Discussion:
 *    Callback function which is called upon error or completion of an
 *    asynchronous resolve.
 *  
 *  Parameters:
 *    
 *    theHost:
 *      Host whose resolution is complete.
 *    
 *    typeInfo:
 *      Enum representing which info resolution is complete.
 *    
 *    error:
 *      Reference to an error structure if the resolution failed.
 *    
 *    info:
 *      Client's info reference which was passed into the client
 *      context.
 */
typedef CALLBACK_API_C( void , CFHostClientCallBack )(CFHostRef theHost, CFHostInfoType typeInfo, const CFStreamError *error, void *info);


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


/*
 *  CFHostCreateWithName()
 *  
 *  Discussion:
 *    Creates a new host object with the given name.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    allocator:
 *      The CFAllocator which should be used to allocate memory for the
 *      host. If this reference is not a valid CFAllocator, the
 *      behavior is undefined.
 *    
 *    hostname:
 *      A CFStringRef representing the name of the host. Must be
 *      non-NULL.  If this If this reference is not a valid
 *      CFStringRef, the behavior is undefined.
 *  
 *  Result:
 *    A valid CFHostRef which may now be resolved, or NULL if
 *    unsuccessful.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFHostRef 
CFHostCreateWithName(
  CFAllocatorRef   allocator,
  CFStringRef      hostname)                                  AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostCreateWithAddress()
 *  
 *  Discussion:
 *    Creates a new host object with the given address.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    allocator:
 *      The CFAllocator which should be used to allocate memory for the
 *      host. If this reference is not a valid CFAllocator, the
 *      behavior is undefined.
 *    
 *    addr:
 *      A CFDataRef containing a struct sockaddr which is the address
 *      of the host. Must be non-NULL.  If this If this reference is
 *      not a valid CFDataRef, the behavior is undefined.
 *  
 *  Result:
 *    A valid CFHostRef which may now be resolved, or NULL if
 *    unsuccessful.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFHostRef 
CFHostCreateWithAddress(
  CFAllocatorRef   allocator,
  CFDataRef        addr)                                      AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostCreateCopy()
 *  
 *  Discussion:
 *    Creates a new host object as a copy of host argument.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    alloc:
 *      The CFAllocator which should be used to allocate memory for the
 *      new host. If this reference is not a valid CFAllocator, the
 *      behavior is undefined.
 *    
 *    host:
 *      A CFHostRef representing the original host. Must be non-NULL. 
 *      If this If this reference is not a valid CFHostRef, the
 *      behavior is undefined.
 *  
 *  Result:
 *    A valid CFHostRef which contains a copy of all previously
 *    resolved data from the original.  NULL is returned in the case of
 *    failure.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFHostRef 
CFHostCreateCopy(
  CFAllocatorRef   alloc,
  CFHostRef        host)                                      AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostStartInfoResolution()
 *  
 *  Discussion:
 *    Performs a lookup for the given host.  It will search for the
 *    requested information if there is no other active request. 
 *    Previously cached information of the given type will be released.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which should be resolved. Must be non-NULL. If
 *      this reference is not a valid CFHostRef, the behavior is
 *      undefined.
 *    
 *    info:
 *      The enum representing the type of information to be retrieved. 
 *      If the value is not a valid type, the behavior is undefined.
 *    
 *    error:
 *      A reference to a CFStreamError structure which will be filled
 *      with any error information should an error occur.  May be set
 *      to NULL if error information is not wanted.
 *  
 *  Result:
 *    Returns TRUE on success and FALSE on failure.  In asynchronous
 *    mode, this function will return immediately.  In synchronous
 *    mode, it will block until the resolve has completed or until the
 *    resolve is cancelled.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHostStartInfoResolution(
  CFHostRef        theHost,
  CFHostInfoType   info,
  CFStreamError *  error)         /* can be NULL */           AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostGetAddressing()
 *  
 *  Discussion:
 *    Tries to retrieve the known addresses from the given host.
 *    Returns a CFArrayRef of addresses if known and there were some.
 *    NULL is returned otherwise.  Each address is a CFDataRef wrapping
 *    a struct sockaddr.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The function gets the data in a thread-safe manner, but the
 *    resulting data is not safe.  Since it is returned as a matter of
 *    a get opposed to a copy, the data is not safe if the host is
 *    being altered from another thread.
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which contains the relevant information. Must be
 *      non-NULL. If this reference is not a valid CFHostRef, the
 *      behavior is undefined.
 *    
 *    hasBeenResolved:
 *      A reference to a Boolean which returns FALSE if the information
 *      was not available (e.g. CFHostStartInfoResolution has not been
 *      called), otherwise TRUE will be returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFArrayRef 
CFHostGetAddressing(
  CFHostRef   theHost,
  Boolean *   hasBeenResolved)       /* can be NULL */        AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostGetNames()
 *  
 *  Discussion:
 *    Tries to retrieve the names/aliases from the given host. Returns
 *    a CFArrayRef of names for the given host.  NULL is returned
 *    otherwise.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The function gets the data in a thread-safe manner, but the
 *    resulting data is not safe.  Since it is returned as a matter of
 *    a get opposed to a copy, the data is not safe if the host is
 *    being altered from another thread.
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which contains the relevant information. Must be
 *      non-NULL. If this reference is not a valid CFHostRef, the
 *      behavior is undefined.
 *    
 *    hasBeenResolved:
 *      A reference to a Boolean which returns FALSE if the information
 *      was not available (e.g. CFHostStartInfoResolution has not been
 *      called), otherwise TRUE will be returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFArrayRef 
CFHostGetNames(
  CFHostRef   theHost,
  Boolean *   hasBeenResolved)       /* can be NULL */        AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostGetReachability()
 *  
 *  Discussion:
 *    Tries to retrieve the reachability of the given host. Returns a
 *    CFDataRef which wraps the reachability flags. NULL will be
 *    returned if the value has not been resolved. The possible values
 *    of these flags is declared in SystemConfiguration/SCNetwork.h.
 *    Returns FALSE if the information was not available, otherwise
 *    TRUE will be returned with the results containing the requested
 *    information.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *    The function gets the data in a thread-safe manner, but the
 *    resulting data is not safe.  Since it is returned as a matter of
 *    a get opposed to a copy, the data is not safe if the host is
 *    being altered from another thread.
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which contains the relevant information. Must be
 *      non-NULL. If this reference is not a valid CFHostRef, the
 *      behavior is undefined.
 *    
 *    hasBeenResolved:
 *      A reference to a Boolean which returns FALSE if the information
 *      was not available (e.g. CFHostStartInfoResolution has not been
 *      called), otherwise TRUE will be returned.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFDataRef 
CFHostGetReachability(
  CFHostRef   theHost,
  Boolean *   hasBeenResolved)       /* can be NULL */        AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostCancelInfoResolution()
 *  
 *  Discussion:
 *    Cancels an outstanding asynchronous or synchronous resolve.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which is currently resolving.  Must be non-NULL.
 *      If this reference is not a valid CFHostRef, the behavior is
 *      undefined.
 *    
 *    info:
 *      The enum representing which resolution to be canceled.  If the
 *      value is not a valid type, the behavior is undefined.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFHostCancelInfoResolution(
  CFHostRef        theHost,
  CFHostInfoType   info)                                      AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostSetClient()
 *  
 *  Discussion:
 *    Associates a client context and callback function with a
 *    CFHostRef.  This is required for asynchronous usage.  If not set,
 *    resolve will take place synchronously.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which is getting a client.  Must be non-NULL. If
 *      this reference is not a valid CFHostRef, the behavior is
 *      undefined.
 *    
 *    clientCB:
 *      A CFHostClientCallBack which will be called when the resolve
 *      completes or is cancelled.  Use NULL to remove the client
 *      association with a host object.
 *    
 *    clientContext:
 *      A CFHostClientContext which is used to set the contextual
 *      information associated with the host object.  The info pointer
 *      from the struct will be passed to the callback function. If
 *      setting a client, this value must be non-NULL.
 *  
 *  Result:
 *    Returns TRUE if the procedure was a success, otherwise it returns
 *    FALSE.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern Boolean 
CFHostSetClient(
  CFHostRef              theHost,
  CFHostClientCallBack   clientCB,            /* can be NULL */
  CFHostClientContext *  clientContext)       /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostScheduleWithRunLoop()
 *  
 *  Discussion:
 *    Schedules the given host on a run loop and mode so the client
 *    will receive its callbacks on that loop and mode.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which is being scheduled.  Must be non-NULL. If
 *      this reference is not a valid CFHostRef, the behavior is
 *      undefined.
 *    
 *    runLoop:
 *      A CFRunLoopRef on which the host should be scheduled. Must be
 *      non-NULL.  If this reference is not a valid CFRunLoopRef, the
 *      behavior is undefined.
 *    
 *    runLoopMode:
 *      A CFStringRef which is the mode in which the run loop will be
 *      running when notification occurs.  Must be non-NULL. If this
 *      reference is not a valid CFStringRef, the behavior is undefined.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFHostScheduleWithRunLoop(
  CFHostRef      theHost,
  CFRunLoopRef   runLoop,
  CFStringRef    runLoopMode)                                 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;


/*
 *  CFHostUnscheduleFromRunLoop()
 *  
 *  Discussion:
 *    Unschedules the given host from a run loop and mode so the client
 *    will not receive its callbacks on that loop and mode.
 *  
 *  Mac OS X threading:
 *    Thread safe
 *  
 *  Parameters:
 *    
 *    theHost:
 *      The CFHostRef which is being unscheduled.  Must be non-NULL. If
 *      this reference is not a valid CFHostRef, the behavior is
 *      undefined.
 *    
 *    runLoop:
 *      A CFRunLoopRef on which the host is scheduled and should now be
 *      unscheduled.  Must be non-NULL.  If this reference is not a
 *      valid CFRunLoopRef, the behavior is undefined.
 *    
 *    runLoopMode:
 *      A CFStringRef which is the mode in which the host is scheduled
 *      and should be unscheduled.  Must be non-NULL. If this reference
 *      is not a valid CFStringRef, the behavior is undefined.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.3 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFHostUnscheduleFromRunLoop(
  CFHostRef      theHost,
  CFRunLoopRef   runLoop,
  CFStringRef    runLoopMode)                                 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#pragma options align=reset

#ifdef __cplusplus
}
#endif

#endif /* __CFHOST__ */