SystemConfiguration.fproj/SCNetworkReachability.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _SCNETWORKREACHABILITY_H
  27 #define _SCNETWORKREACHABILITY_H
  28
  29 #include <sys/cdefs.h>
  30 #include <sys/types.h>
  31 #include <sys/socket.h>
  32 #include <AvailabilityMacros.h>
  33 #include <CoreFoundation/CoreFoundation.h>
  34 #include <SystemConfiguration/SCNetwork.h>
  35
  36 /*!
  37         @header SCNetworkReachability
  38         The SCNetworkReachabilityXXX() APIs allow an application to determine the status
  39         of a system's current network configuration and the reachability
  40         of a target host.  In addition, the reachability can be monitored
  41         with a notification being provided when/if the status has changed.
  42
  43         The term "reachable" reflects whether a data packet, sent by
  44         an application into the network stack, can be sent to the
  45         the target host/address.  Please note that there is no
  46         guarantee that the data packet will actually be received by
  47         the host.
  48  */
  49
  50 /*!
  51         @typedef SCNetworkReachabilityRef
  52         @discussion This is the handle to a network address/name.
  53  */
  54 typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef         AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  55
  56
  57 /*!
  58         @typedef SCNetworkReachabilityContext
  59  */
  60 typedef struct {
  61         CFIndex         version;
  62         void *          info;
  63         const void      *(*retain)(const void *info);
  64         void            (*release)(const void *info);
  65         CFStringRef     (*copyDescription)(const void *info);
  66 } SCNetworkReachabilityContext                                                  AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  67
  68 /*!
  69         @typedef SCNetworkReachabilityCallBack
  70         @discussion Type of the callback function used when the
  71                 reachability of a network address/name changes.
  72         @param target The SCNetworkReachability reference being monitored for changes.
  73         @param flags The new SCNetworkConnectionFlags representing the
  74                 reachability status of the network address/name.
  75         @param info ....
  76  */
  77 typedef void (*SCNetworkReachabilityCallBack)   (
  78                                                 SCNetworkReachabilityRef        target,
  79                                                 SCNetworkConnectionFlags        flags,
  80                                                 void                            *info
  81                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  82
  83 __BEGIN_DECLS
  84
  85 /*!
  86         @function SCNetworkReachabilityCreateWithAddress
  87         @discussion Creates a reference to the specified network
  88                 address.  This reference can later be used to monitor
  89                 the reachability of the target host.
  90         @param address The address of the desired host.
  91         @result A reference to the new immutable SCNetworkReachabilityRef.
  92
  93                  You must release the returned value.
  94  */
  95 SCNetworkReachabilityRef
  96 SCNetworkReachabilityCreateWithAddress          (
  97                                                 CFAllocatorRef                  allocator,
  98                                                 const struct sockaddr           *address
  99                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 100
 101 /*!
 102         @function SCNetworkReachabilityCreateWithAddressPair
 103         @discussion Creates a reference to the specified network
 104                 address.  This reference can later be used to monitor
 105                 the reachability of the target host.
 106         @param localAddress The local address associated with a network
 107                 connection.  If NULL, only the remote address is of interest.
 108         @param remoteAddress The remote address associated with a network
 109                 connection.  If NULL, only the local address is of interest.
 110         @result A reference to the new immutable SCNetworkReachabilityRef.
 111
 112                  You must release the returned value.
 113  */
 114 SCNetworkReachabilityRef
 115 SCNetworkReachabilityCreateWithAddressPair      (
 116                                                 CFAllocatorRef                  allocator,
 117                                                 const struct sockaddr           *localAddress,
 118                                                 const struct sockaddr           *remoteAddress
 119                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 120
 121 /*!
 122         @function SCNetworkReachabilityCreateWithName
 123         @discussion Creates a reference to the specified network host/node
 124                 name.  This reference can later be used to monitor the
 125                 reachability of the target host.
 126         @param nodename The node name of the desired host. This name would
 127                 be the same as that passed to gethostbyname() or getaddrinfo().
 128         @result A reference to the new immutable SCNetworkReachabilityRef.
 129
 130                 You must release the returned value.
 131  */
 132 SCNetworkReachabilityRef
 133 SCNetworkReachabilityCreateWithName             (
 134                                                 CFAllocatorRef                  allocator,
 135                                                 const char                      *nodename
 136                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 137
 138 /*!
 139         @function SCNetworkReachabilityGetTypeID
 140         Returns the type identifier of all SCNetworkReachability instances.
 141  */
 142 CFTypeID
 143 SCNetworkReachabilityGetTypeID                  (void)                          AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 144
 145
 146 /*!
 147         @function SCNetworkReachabilityGetFlags
 148         @discussion Determines if the given target is reachable using the
 149                 current network configuration.
 150         @param target The network reference associated with the address/name
 151                 to be checked for reachability.
 152         @param flags A pointer to memory that will be filled with the
 153                 SCNetworkConnectionFlags detailing the reachability
 154                 of the specified target.
 155         @result TRUE if the network connection flags are valid; FALSE if the
 156                 status could not be determined.
 157  */
 158 Boolean
 159 SCNetworkReachabilityGetFlags                   (
 160                                                 SCNetworkReachabilityRef        target,
 161                                                 SCNetworkConnectionFlags        *flags
 162                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 163
 164 /*!
 165         @function SCNetworkReachabilitySetCallback
 166         @discussion Assigns a client to a target, which receives callbacks
 167                 when the reachability of the target changes.
 168         @param target The network reference associated with the address/name
 169                 to be checked for reachability.
 170         @param callout The function to be called when the reachability of
 171                 target changes.  If NULL, the current client for the target
 172                 is removed.
 173         @param context The SCNetworkReachabilityContext associated with
 174                 the callout.
 175         @result TRUE if the notification client was successfully set.
 176  */
 177 Boolean
 178 SCNetworkReachabilitySetCallback                (
 179                                                 SCNetworkReachabilityRef        target,
 180                                                 SCNetworkReachabilityCallBack   callout,
 181                                                 SCNetworkReachabilityContext    *context
 182                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 183
 184 /*!
 185         @function SCNetworkReachabilityScheduleWithRunLoop
 186         @discussion Schedule the given target from the given run loop and mode.
 187         @param target The address/name which is set up for asynchronous mode.  Must be non-NULL.
 188         @param runLoop A reference to a runloop on which the target should be scheduled.  Must be non-NULL.
 189         @param runLoopMode The mode on which to schedule the target.  Must be non-NULL.
 190  */
 191 Boolean
 192 SCNetworkReachabilityScheduleWithRunLoop        (
 193                                                 SCNetworkReachabilityRef        target,
 194                                                 CFRunLoopRef                    runLoop,
 195                                                 CFStringRef                     runLoopMode
 196                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 197
 198 /*!
 199         @function SCNetworkReachabilityUnscheduleFromRunLoop
 200         @discussion Unschedule the given target from the given run loop and mode.
 201         @param target The address/name which is set up for asynchronous mode.  Must be non-NULL.
 202         @param runLoop A reference to a runloop on which the target should be scheduled.  Must be non-NULL.
 203         @param runLoopMode The mode on which to schedule the target.  Must be non-NULL.
 204  */
 205 Boolean
 206 SCNetworkReachabilityUnscheduleFromRunLoop      (
 207                                                 SCNetworkReachabilityRef        target,
 208                                                 CFRunLoopRef                    runLoop,
 209                                                 CFStringRef                     runLoopMode
 210                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 211
 212 __END_DECLS
 213
 214 #endif /* _SCNETWORKREACHABILITY_H */