CFNetDiagnostics.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/CFNetDiagnostics.h
 
     Contains:   CFNetDiagnostics interface
 
     Version:    1.0
 
     Copyright:   2004-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:                CFNetDiagnostics.i
                     Revision:        1.3
                     Dated:           2004/08/03 22:57:05
                     Last change by:  jiarocci
                     Last comment:    Update Interface files to include headerdoc and remove warnings.
 
     Bugs:       Report bugs to Radar component "System Interfaces", "Latest"
                 List the version information (from above) in the Problem Description.
 
*/
#ifndef __CFNETDIAGNOSTICS__
#define __CFNETDIAGNOSTICS__

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

#include <stdint.h>


#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint on
#endif


/*
 *  CFNetDiagnosticStatus
 *  
 *  Discussion:
 *    Returned by the various status and diagnostic calls
 */
typedef int32_t                         CFNetDiagnosticStatus;

/*
 *  CFNetDiagnosticRef
 *  
 *  Discussion:
 *    This is the type used to describe the types of connection that
 *    clients may be querying about
 */
typedef struct __CFNetDiagnostic*       CFNetDiagnosticRef;

/*
 *  CFNetDiagnosticStatusValues
 *  
 *  Discussion:
 *    Values for CFNetDiagnosticStatus
 */
enum CFNetDiagnosticStatusValues {

  /*
   * There is no status, but no error has occured
   */
  kCFNetDiagnosticNoErr         = 0,

  /*
   * An error occured that prevented the call from completing
   */
  kCFNetDiagnosticErr           = -66560L,

  /*
   * The connection appears to be working
   */
  kCFNetDiagnosticConnectionUp  = -66559L,
  kCFNetDiagnosticConnectionIndeterminate = -66558L,

  /*
   * The connection does not appear to be working
   */
  kCFNetDiagnosticConnectionDown = -66557L
};
typedef enum CFNetDiagnosticStatusValues CFNetDiagnosticStatusValues;


/*
 *  CFNetDiagnosticCreateWithStreams()
 *  
 *  Discussion:
 *    Creates a CFNetDiagnosticRef from a pair of CFStreams. Either
 *    stream may be NULL. This is the preferred interface for creating
 *    a CFNetDiagnosticRef.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      The CF allocator to use.
 *    
 *    readStream:
 *      CFReadStreamRef referring to the failed connection. May be NULL.
 *    
 *    writeStream:
 *      CFWriteStreamRef referring to the failed connection. May be
 *      NULL.
 *  
 *  Result:
 *    A CFNetDiagnosticRef referring to the current networking issue.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFNetDiagnosticRef 
CFNetDiagnosticCreateWithStreams(
  CFAllocatorRef     alloc,
  CFReadStreamRef    readStream,
  CFWriteStreamRef   writeStream)                             AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFNetDiagnosticCreateWithURL()
 *  
 *  Discussion:
 *    Creates a CFNetDiagnosticRef based on a CFURLRef passed in by the
 *    application.
 *  
 *  Parameters:
 *    
 *    alloc:
 *      The CF allocator to use.
 *    
 *    url:
 *      CFURLRef referring to the failed connection.
 *  
 *  Result:
 *    A CFNetDiagnosticRef referring to the current networking issue.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFNetDiagnosticRef 
CFNetDiagnosticCreateWithURL(
  CFAllocatorRef   alloc,
  CFURLRef         url)                                       AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



/*
 *  CFNetDiagnosticSetName()
 *  
 *  Discussion:
 *    If the framework requires an application name to be displayed to
 *    the user it will derive it from the bundle identifier of the
 *    currently running application, in that application's current
 *    localization. If you want to override that you may use
 *    CFNetDiagnosticAddName to specify a CFStringRef to be used.
 *  
 *  Parameters:
 *    
 *    details:
 *      CFNetDiagnosticRef referring to the current problem.
 *    
 *    name:
 *      The localized name that should appear to the user when
 *      referring to the application.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern void 
CFNetDiagnosticSetName(
  CFNetDiagnosticRef   details,
  CFStringRef          name)                                  AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



/*
 *  CFNetDiagnosticDiagnoseProblemInteractively()
 *  
 *  Discussion:
 *    Opens the Network Diagnostics window and returns immediately once
 *    it is open. The client passes in a CFNetDiagnosticRef built with
 *    one of the creator functions.
 *  
 *  Parameters:
 *    
 *    details:
 *      CFNetDiagnosticRef referring to the current problem.
 *  
 *  Result:
 *    A CFNetDiagnosticStatus. Will either be CFNetDiagnosticNoErr, or
 *    CFNetDiagnosticErr if there was an error attempting to run the
 *    diagnosis.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFNetDiagnosticStatus 
CFNetDiagnosticDiagnoseProblemInteractively(CFNetDiagnosticRef details) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;


/*
 *  CFNetDiagnosticCopyNetworkStatusPassively()
 *  
 *  Discussion:
 *    Returns a status value that can be used to display basic
 *    information about the connection. If the caller wishes they may
 *    pass in a pointer to a CFStringRef that will be used to pass back
 *    a localized description of the problem. It is the caller's
 *    responsibility to release the CFStringRef. If the caller does not
 *    want a description they may pass in NULL.
 *    CFNetDiagnosticCopyNetworkStatusPassively() is guaranteed not to
 *    cause network activity.
 *  
 *  Parameters:
 *    
 *    details:
 *      CFNetDiagnosticRef referring to the current problem
 *    
 *    description:
 *      A pointer to a CFStringRef that, upon return, will point to a
 *      localized string containing a description of the current
 *      network status. May be NULL. If it is not NULL, the client must
 *      call CFRelease on the returned object.
 *  
 *  Availability:
 *    Mac OS X:         in version 10.4 and later in CoreServices.framework
 *    CarbonLib:        not available
 *    Non-Carbon CFM:   not available
 */
extern CFNetDiagnosticStatus 
CFNetDiagnosticCopyNetworkStatusPassively(
  CFNetDiagnosticRef   details,
  CFStringRef *        description)                           AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;



#if PRAGMA_ENUM_ALWAYSINT
    #pragma enumsalwaysint reset
#endif

#ifdef __cplusplus
}
#endif

#endif /* __CFNETDIAGNOSTICS__ */