SystemConfiguration.fproj/SCNetworkInterfaceProvider.h

   1 /*
   2  * Copyright (c) 2018 Apple 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 _SCNETWORKINTERFACEPROVIDER_H
  25 #define _SCNETWORKINTERFACEPROVIDER_H
  26
  27 /*
  28  * Modification History
  29  *
  30  * January 17, 2018             Dieter Siegmund (dieter@apple.com)
  31  * - initial revision
  32  */
  33
  34 /*
  35  * SCNetworkInterfaceProvider.h
  36  */
  37
  38
  39 #include <os/availability.h>
  40 #include <CoreFoundation/CoreFoundation.h>
  41 #include <SystemConfiguration/SCNetworkConfiguration.h>
  42
  43 __BEGIN_DECLS
  44
  45 typedef CF_ENUM(uint32_t, SCNetworkInterfaceProviderEvent) {
  46         kSCNetworkInterfaceProviderEventActivationRequested = 1,
  47         kSCNetworkInterfaceProviderEventActivationNoLongerRequested = 2,
  48 };
  49
  50 typedef struct CF_BRIDGED_TYPE(id) __SCNetworkInterfaceProvider *
  51 SCNetworkInterfaceProviderRef;
  52
  53 /*!
  54         @typedef SCNetworkInterfaceProviderEventHandler
  55         @discussion Event handler callback to process SCNetworkInterfaceProvider
  56         events.
  57         @param event The event to handle.
  58         @param event_data The event data, always NULL currently.
  59  */
  60 typedef void
  61 (^SCNetworkInterfaceProviderEventHandler)(SCNetworkInterfaceProviderEvent event,
  62                                           CFDictionaryRef event_data);
  63
  64 /*!
  65         @function SCNetworkInterfaceProviderCreate
  66         @discussion  Create an interface provider for a single network
  67         interface. The interface provider processes the events on the
  68         interface and takes actions based on the specific event.
  69         After calling this function, activate the event handler by calling
  70         SCNetworkInterfaceProviderSetEventHandler() followed by
  71         SCNetworkInterfaceProviderResume().
  72         Calling CFRelease() will free resources and deactivate the
  73         SCNetworkInterfaceProvider callback.
  74         @param interfaceType The kSCNetworkInterfaceType that the interface
  75         provider handles e.g. kSCNetworkInterfaceTypeCellular.
  76         @param interfaceName The name of the network interface, e.g. "pdp_ip0".
  77         @param options NULL for now.
  78         @result A non-NULL SCNetworkInterfaceProviderRef if the interface
  79         provider was successfully registered, NULL otherwise.
  80  */
  81 SCNetworkInterfaceProviderRef
  82 SCNetworkInterfaceProviderCreate(CFStringRef interfaceType,
  83                                  CFStringRef interfaceName,
  84                                  CFDictionaryRef options)
  85      API_AVAILABLE(macos(10.14), ios(12.0));
  86
  87 /*!
  88         @function SCNetworkInterfaceProviderSetEventHandler
  89         @discussion  Set the event handler to process events for the
  90         SCNetworkInterfaceProvider object.
  91         @param provider The SCNetworkInterfaceProvider to set the callback for.
  92         @param handler The event handler to process events. Invoking this
  93         function more than once or with a NULL handler is not valid.
  94  */
  95 void
  96 SCNetworkInterfaceProviderSetEventHandler(SCNetworkInterfaceProviderRef provider,
  97                                           SCNetworkInterfaceProviderEventHandler handler)
  98      API_AVAILABLE(macos(10.14), ios(12.0));
  99
 100 /*!
 101         @function SCNetworkInterfaceProviderResume
 102         @discussion  Activate the interface provider so that its event handler
 103         will get called.
 104         @param provider The provider object to enable events on.
 105  */
 106 void
 107 SCNetworkInterfaceProviderResume(SCNetworkInterfaceProviderRef provider)
 108      API_AVAILABLE(macos(10.14), ios(12.0));
 109
 110 __END_DECLS
 111 #endif /* _SCNETWORKINTERFACEPROVIDER_H */