/* * Copyright (c) 2003-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@ */ #ifndef _SCNETWORKREACHABILITY_H #define _SCNETWORKREACHABILITY_H #include <AvailabilityMacros.h> #include <sys/cdefs.h> #include <sys/types.h> #include <sys/socket.h> #include <CoreFoundation/CoreFoundation.h> #include <SystemConfiguration/SCNetwork.h> #if MAC_OS_X_VERSION_MAX_ALLOWED >= 1030 /*! @header SCNetworkReachability @discussion The SCNetworkReachability API allows an application to determine the status of a system's current network configuration and the reachability of a target host. In addition, reachability can be monitored with notifications that are sent when the status has changed. "Reachability" reflects whether a data packet, sent by an application into the network stack, can leave the local computer. Note that reachability does <i>not</i> guarantee that the data packet will actually be received by the host. */ /*! @typedef SCNetworkReachabilityRef @discussion This is the handle to a network address or name. */ typedef const struct __SCNetworkReachability * SCNetworkReachabilityRef; /*! @typedef SCNetworkReachabilityContext Structure containing user-specified data and callbacks for SCNetworkReachability. @field version The version number of the structure type being passed in as a parameter to the SCDynamicStore creation function. This structure is version 0. @field info A C pointer to a user-specified block of data. @field retain The callback used to add a retain for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL. @field release The calllback used to remove a retain previously added for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL. @field copyDescription The callback used to provide a description of the info field. */ typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCNetworkReachabilityContext; /*! @typedef SCNetworkReachabilityCallBack @discussion Type of the callback function used when the reachability of a network address or name changes. @param target The SCNetworkReachability reference being monitored for changes. @param flags The new SCNetworkConnectionFlags representing the reachability status of the network address/name. @param info A C pointer to a user-specified block of data. */ typedef void (*SCNetworkReachabilityCallBack) ( SCNetworkReachabilityRef target, SCNetworkConnectionFlags flags, void *info ); __BEGIN_DECLS /*! @function SCNetworkReachabilityCreateWithAddress @discussion Creates a reference to the specified network address. This reference can be used later to monitor the reachability of the target host. @param address The address of the desired host. @result Returns a reference to the new immutable SCNetworkReachabilityRef. You must release the returned value. */ SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddress ( CFAllocatorRef allocator, const struct sockaddr *address ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityCreateWithAddressPair @discussion Creates a reference to the specified network address. This reference can be used later to monitor the reachability of the target host. @param localAddress The local address associated with a network connection. If NULL, only the remote address is of interest. @param remoteAddress The remote address associated with a network connection. If NULL, only the local address is of interest. @result Returns a reference to the new immutable SCNetworkReachabilityRef. You must release the returned value. */ SCNetworkReachabilityRef SCNetworkReachabilityCreateWithAddressPair ( CFAllocatorRef allocator, const struct sockaddr *localAddress, const struct sockaddr *remoteAddress ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityCreateWithName @discussion Creates a reference to the specified network host or node name. This reference can be used later to monitor the reachability of the target host. @param nodename The node name of the desired host. This name would be the same as that passed to the gethostbyname(3) or getaddrinfo(3) functions. @result Returns a reference to the new immutable SCNetworkReachabilityRef. You must release the returned value. */ SCNetworkReachabilityRef SCNetworkReachabilityCreateWithName ( CFAllocatorRef allocator, const char *nodename ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityGetTypeID @discussion Returns the type identifier of all SCNetworkReachability instances. */ CFTypeID SCNetworkReachabilityGetTypeID (void) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityGetFlags @discussion Determines if the given target is reachable using the current network configuration. @param target The network reference associated with the address or name to be checked for reachability. @param flags A pointer to memory that will be filled with the SCNetworkConnectionFlags detailing the reachability of the specified target. @result Returns TRUE if the network connection flags are valid; FALSE if the status could not be determined. */ Boolean SCNetworkReachabilityGetFlags ( SCNetworkReachabilityRef target, SCNetworkConnectionFlags *flags ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilitySetCallback @discussion Assigns a client to a target, which receives callbacks when the reachability of the target changes. @param target The network reference associated with the address or name to be checked for reachability. @param callout The function to be called when the reachability of the target changes. If NULL, the current client for the target is removed. @param context The SCNetworkReachabilityContext associated with the callout. The value may be NULL. @result Returns TRUE if the notification client was successfully set. */ Boolean SCNetworkReachabilitySetCallback ( SCNetworkReachabilityRef target, SCNetworkReachabilityCallBack callout, SCNetworkReachabilityContext *context ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityScheduleWithRunLoop @discussion Schedules the given target with the given run loop and mode. @param target The address or name that is set up for asynchronous notifications. Must be non-NULL. @param runLoop A reference to a run loop on which the target should be scheduled. Must be non-NULL. @param runLoopMode The mode on which to schedule the target. Must be non-NULL. @result Returns TRUE if the target is scheduled successfully; FALSE otherwise. */ Boolean SCNetworkReachabilityScheduleWithRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /*! @function SCNetworkReachabilityUnscheduleFromRunLoop @discussion Unschedules the given target from the given run loop and mode. @param target The address or name that is set up for asynchronous notifications. Must be non-NULL. @param runLoop A reference to a run loop from which the target should be unscheduled. Must be non-NULL. @param runLoopMode The mode on which to unschedule the target. Must be non-NULL. @result Returns TRUE if the target is unscheduled successfully; FALSE otherwise. */ Boolean SCNetworkReachabilityUnscheduleFromRunLoop ( SCNetworkReachabilityRef target, CFRunLoopRef runLoop, CFStringRef runLoopMode ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; __END_DECLS #endif /* MAC_OS_X_VERSION_MAX_ALLOWED >= 1030 */ #endif /* _SCNETWORKREACHABILITY_H */