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         The SCNetworkReachabilityXXX() APIs allow an application to determine the status
  37         of a system's current network configuration and the reachability
  38         of a target host.  In addition, the reachability can be monitored
  39         with a notification being provided when/if the status has changed.
  40
  41         The term "reachable" reflects whether a data packet, sent by
  42         an application into the network stack, can be sent to the
  43         the target host/address.  Please note that there is no
  44         guarantee that the data packet will actually be received by
  45         the host.
  46  */
  47
  48 /*!
  49         @typedef SCNetworkReachabilityRef
  50         @discussion This is the handle to a network address/name.
  51  */
  52 typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef         AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  53
  54
  55 /*!
  56         @typedef SCNetworkReachabilityContext
  57  */
  58 typedef struct {
  59         CFIndex         version;
  60         void *          info;
  61         const void      *(*retain)(const void *info);
  62         void            (*release)(const void *info);
  63         CFStringRef     (*copyDescription)(const void *info);
  64 } SCNetworkReachabilityContext                                                  AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  65
  66 /*!
  67         @typedef SCNetworkReachabilityCallBack
  68         @discussion Type of the callback function used when the
  69                 reachability of a network address/name changes.
  70         @param target The SCNetworkReachability reference being monitored for changes.
  71         @param flags The new SCNetworkConnectionFlags representing the
  72                 reachability status of the network address/name.
  73         @param info ....
  74  */
  75 typedef void (*SCNetworkReachabilityCallBack)   (
  76                                                 SCNetworkReachabilityRef        target,
  77                                                 SCNetworkConnectionFlags        flags,
  78                                                 void                            *info
  79                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  80
  81 __BEGIN_DECLS
  82
  83 /*!
  84         @function SCNetworkReachabilityCreateWithAddress
  85         @discussion Creates a reference to the specified network
  86                 address.  This reference can later be used to monitor
  87                 the reachability of the target host.
  88         @param address The address of the desired host.
  89         @result A reference to the new immutable SCNetworkReachabilityRef.
  90
  91                  You must release the returned value.
  92  */
  93 SCNetworkReachabilityRef
  94 SCNetworkReachabilityCreateWithAddress          (
  95                                                 CFAllocatorRef                  allocator,
  96                                                 const struct sockaddr           *address
  97                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  98
  99 /*!
 100         @function SCNetworkReachabilityCreateWithAddressPair
 101         @discussion Creates a reference to the specified network
 102                 address.  This reference can later be used to monitor
 103                 the reachability of the target host.
 104         @param localAddress The local address associated with a network
 105                 connection.  If NULL, only the remote address is of interest.
 106         @param remoteAddress The remote address associated with a network
 107                 connection.  If NULL, only the local address is of interest.
 108         @result A reference to the new immutable SCNetworkReachabilityRef.
 109
 110                  You must release the returned value.
 111  */
 112 SCNetworkReachabilityRef
 113 SCNetworkReachabilityCreateWithAddressPair      (
 114                                                 CFAllocatorRef                  allocator,
 115                                                 const struct sockaddr           *localAddress,
 116                                                 const struct sockaddr           *remoteAddress
 117                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 118
 119 /*!
 120         @function SCNetworkReachabilityCreateWithName
 121         @discussion Creates a reference to the specified network host/node
 122                 name.  This reference can later be used to monitor the
 123                 reachability of the target host.
 124         @param nodename The node name of the desired host. This name would
 125                 be the same as that passed to gethostbyname() or getaddrinfo().
 126         @result A reference to the new immutable SCNetworkReachabilityRef.
 127
 128                 You must release the returned value.
 129  */
 130 SCNetworkReachabilityRef
 131 SCNetworkReachabilityCreateWithName             (
 132                                                 CFAllocatorRef                  allocator,
 133                                                 const char                      *nodename
 134                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 135
 136 /*!
 137         @function SCNetworkReachabilityGetTypeID
 138         Returns the type identifier of all SCNetworkReachability instances.
 139  */
 140 CFTypeID
 141 SCNetworkReachabilityGetTypeID                  (void)                          AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 142
 143
 144 /*!
 145         @function SCNetworkReachabilityGetFlags
 146         @discussion Determines if the given target is reachable using the
 147                 current network configuration.
 148         @param target The network reference associated with the address/name
 149                 to be checked for reachability.
 150         @param flags A pointer to memory that will be filled with the
 151                 SCNetworkConnectionFlags detailing the reachability
 152                 of the specified target.
 153         @result TRUE if the network connection flags are valid; FALSE if the
 154                 status could not be determined.
 155  */
 156 Boolean
 157 SCNetworkReachabilityGetFlags                   (
 158                                                 SCNetworkReachabilityRef        target,
 159                                                 SCNetworkConnectionFlags        *flags
 160                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 161
 162 /*!
 163         @function SCNetworkReachabilitySetCallback
 164         @discussion Assigns a client to a target, which receives callbacks
 165                 when the reachability of the target changes.
 166         @param target The network reference associated with the address/name
 167                 to be checked for reachability.
 168         @param callout The function to be called when the reachability of
 169                 target changes.  If NULL, the current client for the target
 170                 is removed.
 171         @param context The SCNetworkReachabilityContext associated with
 172                 the callout.
 173         @result TRUE if the notification client was successfully set.
 174  */
 175 Boolean
 176 SCNetworkReachabilitySetCallback                (
 177                                                 SCNetworkReachabilityRef        target,
 178                                                 SCNetworkReachabilityCallBack   callout,
 179                                                 SCNetworkReachabilityContext    *context
 180                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 181
 182 /*!
 183         @function SCNetworkReachabilityScheduleWithRunLoop
 184         @discussion Schedule the given target from the given run loop and mode.
 185         @param target The address/name which is set up for asynchronous mode.  Must be non-NULL.
 186         @param runLoop A reference to a runloop on which the target should be scheduled.  Must be non-NULL.
 187         @param runLoopMode The mode on which to schedule the target.  Must be non-NULL.
 188  */
 189 Boolean
 190 SCNetworkReachabilityScheduleWithRunLoop        (
 191                                                 SCNetworkReachabilityRef        target,
 192                                                 CFRunLoopRef                    runLoop,
 193                                                 CFStringRef                     runLoopMode
 194                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 195
 196 /*!
 197         @function SCNetworkReachabilityUnscheduleFromRunLoop
 198         @discussion Unschedule the given target from the given run loop and mode.
 199         @param target The address/name which is set up for asynchronous mode.  Must be non-NULL.
 200         @param runLoop A reference to a runloop on which the target should be scheduled.  Must be non-NULL.
 201         @param runLoopMode The mode on which to schedule the target.  Must be non-NULL.
 202  */
 203 Boolean
 204 SCNetworkReachabilityUnscheduleFromRunLoop      (
 205                                                 SCNetworkReachabilityRef        target,
 206                                                 CFRunLoopRef                    runLoop,
 207                                                 CFStringRef                     runLoopMode
 208                                                 )                               AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 209
 210 __END_DECLS
 211
 212 #endif /* _SCNETWORKREACHABILITY_H */