SystemConfiguration.fproj/SCNetworkReachability.h

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