SystemConfiguration.fproj/SCNetworkReachability.h

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