SystemConfiguration.fproj/SCNetworkConfiguration.h

   1 /*
   2  * Copyright (c) 2004-2011, 2015, 2016, 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 _SCNETWORKCONFIGURATION_H
  25 #define _SCNETWORKCONFIGURATION_H
  26
  27 #include <os/availability.h>
  28 #include <TargetConditionals.h>
  29 #include <sys/cdefs.h>
  30 #include <CoreFoundation/CoreFoundation.h>
  31 #include <SystemConfiguration/SystemConfiguration.h>
  32
  33 CF_IMPLICIT_BRIDGING_ENABLED
  34 CF_ASSUME_NONNULL_BEGIN
  35
  36 /*!
  37         @header SCNetworkConfiguration
  38         @discussion The SCNetworkConfiguration API provides access to the
  39                 stored network configuration.  The functions include
  40                 providing access to the network capable devices on the
  41                 system, the network sets, network services, and network
  42                 protocols.
  43
  44                 Note: When using the SCNetworkConfiguraiton APIs you must
  45                 keep in mind that in order for any of your changes to be
  46                 committed to permanent storage a call must be made to the
  47                 SCPreferencesCommitChanges function.
  48  */
  49
  50
  51 /*!
  52         @group Interface configuration
  53  */
  54
  55 #pragma mark -
  56 #pragma mark SCNetworkInterface configuration (typedefs, consts)
  57
  58 /*!
  59         @typedef SCNetworkInterfaceRef
  60         @discussion This is the type of a reference to an object that represents
  61                 a network interface.
  62  */
  63 typedef const struct CF_BRIDGED_TYPE(id) __SCNetworkInterface * SCNetworkInterfaceRef;
  64
  65 /*!
  66         @const kSCNetworkInterfaceType6to4
  67  */
  68 extern const CFStringRef kSCNetworkInterfaceType6to4                                            API_AVAILABLE(macos(10.4))
  69                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
  70
  71 /*!
  72         @const kSCNetworkInterfaceTypeBluetooth
  73  */
  74 extern const CFStringRef kSCNetworkInterfaceTypeBluetooth                                       API_AVAILABLE(macos(10.4))
  75                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
  76
  77 /*!
  78         @const kSCNetworkInterfaceTypeBond
  79  */
  80 extern const CFStringRef kSCNetworkInterfaceTypeBond                                            API_AVAILABLE(macos(10.4))
  81                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
  82
  83 /*!
  84         @const kSCNetworkInterfaceTypeEthernet
  85  */
  86 extern const CFStringRef kSCNetworkInterfaceTypeEthernet                                        API_AVAILABLE(macos(10.4))
  87                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
  88
  89 /*!
  90         @const kSCNetworkInterfaceTypeFireWire
  91  */
  92 extern const CFStringRef kSCNetworkInterfaceTypeFireWire                                        API_AVAILABLE(macos(10.4))
  93                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
  94
  95 /*!
  96         @const kSCNetworkInterfaceTypeIEEE80211
  97  */
  98 extern const CFStringRef kSCNetworkInterfaceTypeIEEE80211                                       API_AVAILABLE(macos(10.4))
  99                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));        // IEEE 802.11, AirPort
 100
 101 /*!
 102         @const kSCNetworkInterfaceTypeIPSec
 103  */
 104 extern const CFStringRef kSCNetworkInterfaceTypeIPSec                                           API_AVAILABLE(macos(10.5))
 105                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 106
 107 /*!
 108         @const kSCNetworkInterfaceTypeIrDA
 109  */
 110 extern const CFStringRef kSCNetworkInterfaceTypeIrDA                                            API_AVAILABLE(macos(10.4))
 111                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 112
 113 /*!
 114         @const kSCNetworkInterfaceTypeL2TP
 115  */
 116 extern const CFStringRef kSCNetworkInterfaceTypeL2TP                                            API_AVAILABLE(macos(10.4))
 117                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 118
 119 /*!
 120         @const kSCNetworkInterfaceTypeModem
 121  */
 122 extern const CFStringRef kSCNetworkInterfaceTypeModem                                           API_AVAILABLE(macos(10.4))
 123                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 124
 125 /*!
 126         @const kSCNetworkInterfaceTypePPP
 127  */
 128 extern const CFStringRef kSCNetworkInterfaceTypePPP                                             API_AVAILABLE(macos(10.4))
 129                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 130
 131 /*!
 132         @const kSCNetworkInterfaceTypePPTP
 133  */
 134 extern const CFStringRef kSCNetworkInterfaceTypePPTP                                            API_DEPRECATED("No longer supported", macos(10.4,10.12))
 135                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 136
 137
 138 /*!
 139         @const kSCNetworkInterfaceTypeSerial
 140  */
 141 extern const CFStringRef kSCNetworkInterfaceTypeSerial                                          API_AVAILABLE(macos(10.4))
 142                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 143
 144 /*!
 145         @const kSCNetworkInterfaceTypeVLAN
 146  */
 147 extern const CFStringRef kSCNetworkInterfaceTypeVLAN                                            API_AVAILABLE(macos(10.4))
 148                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 149
 150 /*!
 151         @const kSCNetworkInterfaceTypeWWAN
 152  */
 153 extern const CFStringRef kSCNetworkInterfaceTypeWWAN                                            API_AVAILABLE(macos(10.5))
 154                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 155
 156 /* special network interfaces (and types) */
 157
 158 /*!
 159         @const kSCNetworkInterfaceTypeIPv4
 160  */
 161 extern const CFStringRef kSCNetworkInterfaceTypeIPv4                                            API_AVAILABLE(macos(10.4))
 162                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 163
 164 /*!
 165         @const kSCNetworkInterfaceIPv4
 166         @discussion A network interface that can used for layering other
 167                 interfaces (e.g. 6to4, IPSec, PPTP, L2TP) over an existing
 168                 IPv4 network.
 169  */
 170 extern const SCNetworkInterfaceRef kSCNetworkInterfaceIPv4                                      API_AVAILABLE(macos(10.4))
 171                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 172
 173 /*!
 174         @group Interface configuration (Bond)
 175  */
 176
 177 #pragma mark -
 178
 179 /*!
 180         @typedef SCBondInterfaceRef
 181         @discussion This is the type of a reference to an object that represents
 182                 an Ethernet Bond interface.
 183  */
 184 typedef SCNetworkInterfaceRef SCBondInterfaceRef;
 185
 186 /*!
 187         @typedef SCBondStatusRef
 188         @discussion This is the type of a reference to an object that represents
 189                 the status of an Ethernet Bond interface.
 190  */
 191 typedef const struct CF_BRIDGED_TYPE(id) __SCBondStatus *               SCBondStatusRef;
 192
 193 /*!
 194         @enum Ethernet Bond Aggregation Status (kSCBondStatusDeviceAggregationStatus) codes
 195         @discussion Returned status codes.
 196         @constant kSCBondStatusOK               Enabled, active, running, ...
 197         @constant kSCBondStatusLinkInvalid      The link state was not valid (i.e. down, half-duplex, wrong speed)
 198         @constant kSCBondStatusNoPartner        The port on the switch that the device is connected doesn't seem to have 802.3ad Link Aggregation enabled
 199         @constant kSCBondStatusNotInActiveGroup We're talking to a partner, but the link aggregation group is different from the one that's active
 200         @constant kSCBondStatusUnknown          Non-specific failure
 201  */
 202 enum {
 203         kSCBondStatusOK                 = 0,    /* enabled, active, running, ... */
 204         kSCBondStatusLinkInvalid        = 1,    /* The link state was not valid (i.e. down, half-duplex, wrong speed) */
 205         kSCBondStatusNoPartner          = 2,    /* The port on the switch that the device is connected doesn't seem to have 802.3ad Link Aggregation enabled */
 206         kSCBondStatusNotInActiveGroup   = 3,    /* We're talking to a partner, but the link aggregation group is different from the one that's active */
 207         kSCBondStatusUnknown            = 999   /* Non-specific failure */
 208 };
 209
 210 /*!
 211         @const kSCBondStatusDeviceAggregationStatus
 212  */
 213 extern const CFStringRef kSCBondStatusDeviceAggregationStatus   /* CFNumber */                  API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 214
 215 /*!
 216         @const kSCBondStatusDeviceCollecting
 217  */
 218 extern const CFStringRef kSCBondStatusDeviceCollecting          /* CFNumber (0 or 1) */         API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 219
 220 /*!
 221         @const kSCBondStatusDeviceDistributing
 222  */
 223 extern const CFStringRef kSCBondStatusDeviceDistributing        /* CFNumber (0 or 1) */         API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 224
 225 /*!
 226         @group Interface configuration (VLAN)
 227  */
 228
 229 #pragma mark -
 230
 231 /*!
 232         @typedef SCVLANInterfaceRef
 233         @discussion This is the type of a reference to an object that represents
 234                 a Virtual LAN (VLAN) interface.
 235  */
 236 typedef SCNetworkInterfaceRef SCVLANInterfaceRef;
 237
 238
 239 /*!
 240         @group Protocol configuration
 241  */
 242
 243 #pragma mark -
 244 #pragma mark SCNetworkProtocol configuration (typedefs, consts)
 245
 246 /*!
 247         @typedef SCNetworkProtocolRef
 248         @discussion This is the type of a reference to an object that represents
 249                 a network protocol.
 250  */
 251 typedef const struct CF_BRIDGED_TYPE(id) __SCNetworkProtocol * SCNetworkProtocolRef;
 252
 253 /* network "protocol" types */
 254
 255 /*!
 256         @const kSCNetworkProtocolTypeDNS
 257  */
 258 extern const CFStringRef kSCNetworkProtocolTypeDNS                                              API_AVAILABLE(macos(10.4))
 259                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 260
 261 /*!
 262         @const kSCNetworkProtocolTypeIPv4
 263  */
 264 extern const CFStringRef kSCNetworkProtocolTypeIPv4                                             API_AVAILABLE(macos(10.4))
 265                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 266
 267 /*!
 268         @const kSCNetworkProtocolTypeIPv6
 269  */
 270 extern const CFStringRef kSCNetworkProtocolTypeIPv6                                             API_AVAILABLE(macos(10.4))
 271                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 272
 273 /*!
 274         @const kSCNetworkProtocolTypeProxies
 275  */
 276 extern const CFStringRef kSCNetworkProtocolTypeProxies                                          API_AVAILABLE(macos(10.4))
 277                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 278
 279 /*!
 280         @const kSCNetworkProtocolTypeSMB
 281  */
 282 extern const CFStringRef kSCNetworkProtocolTypeSMB                                              API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 283
 284 /*!
 285         @group Service configuration
 286  */
 287
 288 #pragma mark -
 289 #pragma mark SCNetworkService configuration (typedefs, consts)
 290
 291 /*!
 292         @typedef SCNetworkServiceRef
 293         @discussion This is the type of a reference to an object that represents
 294                 a network service.
 295  */
 296 typedef const struct CF_BRIDGED_TYPE(id) __SCNetworkService * SCNetworkServiceRef;
 297
 298
 299 /*!
 300         @group Set configuration
 301  */
 302
 303 #pragma mark -
 304 #pragma mark SCNetworkSet configuration (typedefs, consts)
 305
 306 /*!
 307         @typedef SCNetworkSetRef
 308         @discussion This is the type of a reference to an object that represents
 309                 a network set.
 310  */
 311 typedef const struct CF_BRIDGED_TYPE(id) __SCNetworkSet * SCNetworkSetRef;
 312
 313
 314 __BEGIN_DECLS
 315
 316
 317 /* --------------------------------------------------------------------------------
 318  * INTERFACES
 319  * -------------------------------------------------------------------------------- */
 320
 321 /*!
 322         @group Interface configuration
 323  */
 324
 325 #pragma mark -
 326 #pragma mark SCNetworkInterface configuration (APIs)
 327
 328 /*!
 329         @function SCNetworkInterfaceGetTypeID
 330         @discussion Returns the type identifier of all SCNetworkInterface instances.
 331  */
 332 CFTypeID
 333 SCNetworkInterfaceGetTypeID                     (void)                                          API_AVAILABLE(macos(10.4))
 334                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 335
 336 /*!
 337         @function SCNetworkInterfaceCopyAll
 338         @discussion Returns all network capable interfaces on the system.
 339         @result The list of interfaces on the system.
 340                 You must release the returned value.
 341  */
 342 CFArrayRef /* of SCNetworkInterfaceRef's */
 343 SCNetworkInterfaceCopyAll                       (void)                                          API_AVAILABLE(macos(10.4))
 344                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 345
 346 /*!
 347         @function SCNetworkInterfaceGetSupportedInterfaceTypes
 348         @discussion Identify all of the network interface types (e.g. PPP) that
 349                 can be layered on top of this interface.
 350         @param interface The network interface.
 351         @result The list of SCNetworkInterface types supported by the interface;
 352                 NULL if no interface types are supported.
 353  */
 354 CFArrayRef /* of kSCNetworkInterfaceTypeXXX CFStringRef's */ __nullable
 355 SCNetworkInterfaceGetSupportedInterfaceTypes    (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 356                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 357
 358 /*!
 359         @function SCNetworkInterfaceGetSupportedProtocolTypes
 360         @discussion Identify all of the network protocol types (e.g. IPv4, IPv6) that
 361                 can be layered on top of this interface.
 362         @param interface The network interface.
 363         @result The list of SCNetworkProtocol types supported by the interface;
 364                 NULL if no protocol types are supported.
 365  */
 366 CFArrayRef /* of kSCNetworkProtocolTypeXXX CFStringRef's */ __nullable
 367 SCNetworkInterfaceGetSupportedProtocolTypes     (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 368                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 369
 370 /*!
 371         @function SCNetworkInterfaceCreateWithInterface
 372         @discussion Create a new network interface layered on top of another.  For
 373                 example, this function would be used to create a "PPP" interface
 374                 on top of a "modem".
 375         @param interface The network interface.
 376         @param interfaceType The type of SCNetworkInterface to be layered on
 377                 top of the provided interface.
 378         @result A reference to the new SCNetworkInterface.
 379                 You must release the returned value.
 380  */
 381 SCNetworkInterfaceRef __nullable
 382 SCNetworkInterfaceCreateWithInterface           (SCNetworkInterfaceRef          interface,
 383                                                  CFStringRef                    interfaceType)  API_AVAILABLE(macos(10.4))
 384                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 385
 386 /*!
 387         @function SCNetworkInterfaceGetBSDName
 388         @discussion Returns the BSD interface (en0) or device name (modem)
 389                 for the interface.
 390         @param interface The network interface.
 391         @result The BSD name associated with the interface (e.g. "en0");
 392                 NULL if no BSD name is available.
 393  */
 394 CFStringRef __nullable
 395 SCNetworkInterfaceGetBSDName                    (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 396                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 397
 398 /*!
 399         @function SCNetworkInterfaceGetConfiguration
 400         @discussion Returns the configuration settings associated with a interface.
 401         @param interface The network interface.
 402         @result The configuration settings associated with the interface;
 403                 NULL if no configuration settings are associated with the interface
 404                 or an error was encountered.
 405  */
 406 CFDictionaryRef __nullable
 407 SCNetworkInterfaceGetConfiguration              (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 408                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 409
 410 /*!
 411         @function SCNetworkInterfaceGetExtendedConfiguration
 412         @discussion Returns the configuration settings associated with a interface.
 413         @param interface The network interface.
 414         @param extendedType A string representing the type of extended information (e.g. EAPOL).
 415         @result The configuration settings associated with the interface;
 416                 NULL if no configuration settings are associated with the interface
 417                 or an error was encountered.
 418  */
 419 CFDictionaryRef __nullable
 420 SCNetworkInterfaceGetExtendedConfiguration      (SCNetworkInterfaceRef          interface,
 421                                                  CFStringRef                    extendedType)   API_AVAILABLE(macos(10.5))
 422                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 423
 424 /*!
 425         @function SCNetworkInterfaceGetHardwareAddressString
 426         @discussion Returns a displayable link layer address for the interface.
 427         @param interface The network interface.
 428         @result A string representing the hardware (MAC) address for the interface.
 429  */
 430 CFStringRef __nullable
 431 SCNetworkInterfaceGetHardwareAddressString      (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 432                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 433
 434 /*!
 435         @function SCNetworkInterfaceGetInterface
 436         @discussion For layered network interfaces, return the underlying interface.
 437         @param interface The network interface.
 438         @result The underlying network interface;
 439                 NULL if this is a leaf interface.
 440  */
 441 SCNetworkInterfaceRef __nullable
 442 SCNetworkInterfaceGetInterface                  (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 443                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 444
 445 /*!
 446         @function SCNetworkInterfaceGetInterfaceType
 447         @discussion Returns the associated network interface type.
 448         @param interface The network interface.
 449         @result The interface type.
 450  */
 451 CFStringRef __nullable
 452 SCNetworkInterfaceGetInterfaceType              (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 453                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 454
 455 /*!
 456         @function SCNetworkInterfaceGetLocalizedDisplayName
 457         @discussion Returns the localized name (e.g. "Ethernet", "FireWire") for
 458                 the interface.
 459         @param interface The network interface.
 460         @result A localized, display name for the interface;
 461                 NULL if no name is available.
 462  */
 463 CFStringRef __nullable
 464 SCNetworkInterfaceGetLocalizedDisplayName       (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
 465                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 466
 467 /*!
 468         @function SCNetworkInterfaceSetConfiguration
 469         @discussion Stores the configuration settings for the interface.
 470         @param interface The network interface.
 471         @param config The configuration settings to associate with this interface.
 472         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 473  */
 474 Boolean
 475 SCNetworkInterfaceSetConfiguration              (SCNetworkInterfaceRef          interface,
 476                                                  CFDictionaryRef __nullable     config)         API_AVAILABLE(macos(10.4))
 477                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 478
 479 /*!
 480         @function SCNetworkInterfaceSetExtendedConfiguration
 481         @discussion Stores the configuration settings for the interface.
 482         @param interface The network interface.
 483         @param config The configuration settings to associate with this interface.
 484         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 485  */
 486 Boolean
 487 SCNetworkInterfaceSetExtendedConfiguration      (SCNetworkInterfaceRef          interface,
 488                                                  CFStringRef                    extendedType,
 489                                                  CFDictionaryRef __nullable     config)         API_AVAILABLE(macos(10.5))
 490                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 491
 492 #pragma mark -
 493
 494 /*!
 495         @function SCNetworkInterfaceCopyMediaOptions
 496         @discussion For the specified network interface, returns information
 497                 about the currently requested media options, the active media
 498                 options, and the media options which are available.
 499         @param interface The desired network interface.
 500         @param current A pointer to memory that will be filled with a CFDictionaryRef
 501                 representing the currently requested media options (subtype, options).
 502                 If NULL, the current options will not be returned.
 503         @param active A pointer to memory that will be filled with a CFDictionaryRef
 504                 representing the active media options (subtype, options).
 505                 If NULL, the active options will not be returned.
 506         @param available A pointer to memory that will be filled with a CFArrayRef
 507                 representing the possible media options (subtype, options).
 508                 If NULL, the available options will not be returned.
 509         @param filter A boolean indicating whether the available options should be
 510                 filtered to exclude those options which would not normally be
 511                 requested by a user/admin (e.g. hw-loopback).
 512         @result TRUE if requested information has been returned.
 513  */
 514 Boolean
 515 SCNetworkInterfaceCopyMediaOptions              (SCNetworkInterfaceRef                                          interface,
 516                                                  CFDictionaryRef                __nullable      * __nullable    current,
 517                                                  CFDictionaryRef                __nullable      * __nullable    active,
 518                                                  CFArrayRef                     __nullable      * __nullable    available,
 519                                                  Boolean                                        filter)         API_AVAILABLE(macos(10.5))
 520                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 521
 522 /*!
 523         @function SCNetworkInterfaceCopyMediaSubTypes
 524         @discussion For the provided interface configuration options, return a list
 525                 of available media subtypes.
 526         @param available The available options as returned by the
 527                 SCNetworkInterfaceCopyMediaOptions function.
 528         @result An array of available media subtypes CFString's (e.g. 10BaseT/UTP,
 529                 100baseTX, etc).  NULL if no subtypes are available.
 530  */
 531 CFArrayRef __nullable
 532 SCNetworkInterfaceCopyMediaSubTypes             (CFArrayRef                     available)      API_AVAILABLE(macos(10.5))
 533                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 534
 535 /*!
 536         @function SCNetworkInterfaceCopyMediaSubTypeOptions
 537         @discussion For the provided interface configuration options and specific
 538                 subtype, return a list of available media options.
 539         @param available The available options as returned by the
 540                 SCNetworkInterfaceCopyMediaOptions function.
 541         @param subType The subtype
 542         @result An array of available media options.  Each of the available options
 543                 is returned as an array of CFString's (e.g. <half-duplex>,
 544                 <full-duplex,flow-control>).  NULL if no options are available.
 545  */
 546 CFArrayRef __nullable
 547 SCNetworkInterfaceCopyMediaSubTypeOptions       (CFArrayRef                     available,
 548                                                  CFStringRef                    subType)        API_AVAILABLE(macos(10.5))
 549                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 550
 551 /*!
 552         @function SCNetworkInterfaceCopyMTU
 553         @discussion For the specified network interface, returns information
 554                 about the currently MTU setting and the range of allowable
 555                 values.
 556         @param interface The desired network interface.
 557         @param mtu_cur A pointer to memory that will be filled with the current
 558                 MTU setting for the interface.
 559         @param mtu_min A pointer to memory that will be filled with the minimum
 560                 MTU setting for the interface.  If negative, the minimum setting
 561                 could not be determined.
 562         @param mtu_max A pointer to memory that will be filled with the maximum
 563                 MTU setting for the interface.  If negative, the maximum setting
 564                 could not be determined.
 565         @result TRUE if requested information has been returned.
 566  */
 567 Boolean
 568 SCNetworkInterfaceCopyMTU                       (SCNetworkInterfaceRef                  interface,
 569                                                  int                    * __nullable    mtu_cur,
 570                                                  int                    * __nullable    mtu_min,
 571                                                  int                    * __nullable    mtu_max)        API_AVAILABLE(macos(10.5))
 572                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 573
 574 /*!
 575         @function SCNetworkInterfaceSetMediaOptions
 576         @discussion For the specified network interface, sets the requested
 577                 media subtype and options.
 578         @param interface The desired network interface.
 579         @param subtype The desired media subtype (e.g. "autoselect", "100baseTX", ...).
 580                 If NULL, no specific media subtype will be requested.
 581         @param options The desired media options (e.g. "half-duplex", "full-duplex", ...).
 582                 If NULL, no specific media options will be requested.
 583         @result TRUE if the configuration was updated; FALSE if an error was encountered.
 584  */
 585 Boolean
 586 SCNetworkInterfaceSetMediaOptions               (SCNetworkInterfaceRef                  interface,
 587                                                  CFStringRef            __nullable      subtype,
 588                                                  CFArrayRef             __nullable      options)        API_AVAILABLE(macos(10.5))
 589                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 590
 591 /*!
 592         @function SCNetworkInterfaceSetMTU
 593         @discussion For the specified network interface, sets the
 594                 requested MTU setting.
 595         @param interface The desired network interface.
 596         @param mtu The desired MTU setting for the interface.
 597                 If zero, the interface will use the default MTU setting.
 598         @result TRUE if the configuration was updated; FALSE if an error was encountered.
 599  */
 600 Boolean
 601 SCNetworkInterfaceSetMTU                        (SCNetworkInterfaceRef          interface,
 602                                                  int                            mtu)            API_AVAILABLE(macos(10.5))
 603                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 604
 605 /*!
 606         @function SCNetworkInterfaceForceConfigurationRefresh
 607         @discussion Sends a notification to interested network configuration
 608                 agents to immediately retry their configuration. For example,
 609                 calling this function will cause the DHCP client to contact
 610                 the DHCP server immediately rather than waiting until its
 611                 timeout has expired.  The utility of this function is to
 612                 allow the caller to give a hint to the system that the
 613                 network infrastructure or configuration has changed.
 614
 615                 Note: This function requires root (euid==0) privilege or,
 616                 alternatively, you may pass an SCNetworkInterface which
 617                 is derived from a sequence of calls to :
 618
 619                         SCPreferencesCreateWithAuthorization
 620                         SCNetworkSetCopy...
 621                         SCNetworkServiceGetInterface
 622         @param interface The desired network interface.
 623         @result Returns TRUE if the notification was sent; FALSE otherwise.
 624  */
 625 Boolean
 626 SCNetworkInterfaceForceConfigurationRefresh     (SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.5))
 627                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 628
 629 /*!
 630         @group Interface configuration (Bond)
 631  */
 632
 633 #pragma mark -
 634 #pragma mark SCBondInterface configuration (APIs)
 635
 636 /*!
 637         @function SCBondInterfaceCopyAll
 638         @discussion Returns all Ethernet Bond interfaces on the system.
 639         @param prefs The "preferences" session.
 640         @result The list of Ethernet Bond interfaces on the system.
 641                 You must release the returned value.
 642  */
 643 CFArrayRef /* of SCBondInterfaceRef's */
 644 SCBondInterfaceCopyAll                          (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 645
 646 /*!
 647         @function SCBondInterfaceCopyAvailableMemberInterfaces
 648         @discussion Returns all network capable devices on the system
 649                 that can be added to an Ethernet Bond interface.
 650         @param prefs The "preferences" session.
 651         @result The list of interfaces.
 652                 You must release the returned value.
 653  */
 654 CFArrayRef /* of SCNetworkInterfaceRef's */
 655 SCBondInterfaceCopyAvailableMemberInterfaces    (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 656
 657 /*!
 658         @function SCBondInterfaceCreate
 659         @discussion Create a new SCBondInterface interface.
 660         @param prefs The "preferences" session.
 661         @result A reference to the new SCBondInterface.
 662                 You must release the returned value.
 663  */
 664 SCBondInterfaceRef __nullable
 665 SCBondInterfaceCreate                           (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 666
 667 /*!
 668         @function SCBondInterfaceRemove
 669         @discussion Removes the SCBondInterface from the configuration.
 670         @param bond The SCBondInterface interface.
 671         @result TRUE if the interface was removed; FALSE if an error was encountered.
 672  */
 673 Boolean
 674 SCBondInterfaceRemove                           (SCBondInterfaceRef             bond)           API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 675
 676 /*!
 677         @function SCBondInterfaceGetMemberInterfaces
 678         @discussion Returns the member interfaces for the specified Ethernet Bond interface.
 679         @param bond The SCBondInterface interface.
 680         @result The list of interfaces.
 681  */
 682 CFArrayRef /* of SCNetworkInterfaceRef's */ __nullable
 683 SCBondInterfaceGetMemberInterfaces              (SCBondInterfaceRef             bond)           API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 684
 685 /*!
 686         @function SCBondInterfaceGetOptions
 687         @discussion Returns the configuration settings associated with a Ethernet Bond interface.
 688         @param bond The SCBondInterface interface.
 689         @result The configuration settings associated with the Ethernet Bond interface;
 690                 NULL if no changes to the default configuration have been saved.
 691  */
 692 CFDictionaryRef __nullable
 693 SCBondInterfaceGetOptions                       (SCBondInterfaceRef             bond)           API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 694
 695 /*!
 696         @function SCBondInterfaceSetMemberInterfaces
 697         @discussion Sets the member interfaces for the specified Ethernet Bond interface.
 698         @param bond The SCBondInterface interface.
 699         @param members The desired member interfaces.
 700         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 701  */
 702 Boolean
 703 SCBondInterfaceSetMemberInterfaces              (SCBondInterfaceRef             bond,
 704                                                  CFArrayRef                     members) /* of SCNetworkInterfaceRef's */
 705                                                                                                 API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 706
 707 /*!
 708         @function SCBondInterfaceSetLocalizedDisplayName
 709         @discussion Sets the localized display name for the specified Ethernet Bond interface.
 710         @param bond The SCBondInterface interface.
 711         @param newName The new display name.
 712         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 713  */
 714 Boolean
 715 SCBondInterfaceSetLocalizedDisplayName          (SCBondInterfaceRef             bond,
 716                                                  CFStringRef                    newName)        API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 717
 718 /*!
 719         @function SCBondInterfaceSetOptions
 720         @discussion Sets the configuration settings for the specified Ethernet Bond interface.
 721         @param bond The SCBondInterface interface.
 722         @param newOptions The new configuration settings.
 723         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 724  */
 725 Boolean
 726 SCBondInterfaceSetOptions                       (SCBondInterfaceRef             bond,
 727                                                  CFDictionaryRef                newOptions)     API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 728
 729 #pragma mark -
 730
 731 /*!
 732         @function SCBondInterfaceCopyStatus
 733         @discussion Returns the status of the specified Ethernet Bond interface.
 734         @param bond The SCBondInterface interface.
 735         @result The status associated with the interface.
 736                 You must release the returned value.
 737  */
 738 SCBondStatusRef __nullable
 739 SCBondInterfaceCopyStatus                       (SCBondInterfaceRef     bond)                   API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 740
 741 /*!
 742         @function SCBondStatusGetTypeID
 743         @discussion Returns the type identifier of all SCBondStatus instances.
 744  */
 745 CFTypeID
 746 SCBondStatusGetTypeID                           (void)                                          API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 747
 748 /*!
 749         @function SCBondStatusGetMemberInterfaces
 750         @discussion Returns the member interfaces that are represented with the
 751                 Ethernet Bond interface.
 752         @param bondStatus The Ethernet Bond status.
 753         @result The list of interfaces.
 754  */
 755 CFArrayRef __nullable /* of SCNetworkInterfaceRef's */
 756 SCBondStatusGetMemberInterfaces                 (SCBondStatusRef        bondStatus)             API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 757
 758 /*!
 759         @function SCBondStatusGetInterfaceStatus
 760         @discussion Returns the status of a specific member interface of an
 761                 Ethernet Bond or the status of the bond as a whole.
 762         @param bondStatus The Ethernet Bond status.
 763         @param interface The specific member interface; NULL if you want the
 764                 status of the Ethernet Bond.
 765         @result The interface status.
 766
 767         Note: at present, no information about the status of the Ethernet
 768               Bond is returned.  As long as one member interface is active
 769               then the bond should be operational.
 770  */
 771 CFDictionaryRef __nullable
 772 SCBondStatusGetInterfaceStatus                  (SCBondStatusRef                        bondStatus,
 773                                                  SCNetworkInterfaceRef  __nullable      interface)      API_AVAILABLE(macos(10.5)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
 774
 775 /*!
 776         @group Interface configuration (VLAN)
 777  */
 778
 779 #pragma mark -
 780 #pragma mark SCVLANInterface configuration (APIs)
 781
 782 /*!
 783         @function SCVLANInterfaceCopyAll
 784         @discussion Returns all VLAN interfaces on the system.
 785         @result The list of VLAN interfaces on the system.
 786                 You must release the returned value.
 787  */
 788 CFArrayRef /* of SCVLANInterfaceRef's */
 789 SCVLANInterfaceCopyAll                          (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.5))
 790                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 791
 792 /*!
 793         @function SCVLANInterfaceCopyAvailablePhysicalInterfaces
 794         @discussion Returns the network capable devices on the system
 795                 that can be associated with a VLAN interface.
 796         @result The list of interfaces.
 797                 You must release the returned value.
 798  */
 799 CFArrayRef /* of SCNetworkInterfaceRef's */
 800 SCVLANInterfaceCopyAvailablePhysicalInterfaces  (void)                                          API_AVAILABLE(macos(10.5))
 801                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 802
 803 /*!
 804         @function SCVLANInterfaceCreate
 805         @discussion Create a new SCVLANInterface interface.
 806         @param prefs The "preferences" session.
 807         @param physical The physical interface to associate with the VLAN.
 808         @param tag The tag to associate with the VLAN.
 809         @result A reference to the new SCVLANInterface.
 810                 You must release the returned value.
 811
 812         Note: the tag must be in the range (1 <= tag <= 4094)
 813  */
 814 SCVLANInterfaceRef __nullable
 815 SCVLANInterfaceCreate                           (SCPreferencesRef               prefs,
 816                                                  SCNetworkInterfaceRef          physical,
 817                                                  CFNumberRef                    tag)            API_AVAILABLE(macos(10.5))
 818                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 819
 820 /*!
 821         @function SCVLANInterfaceRemove
 822         @discussion Removes the SCVLANInterface from the configuration.
 823         @param vlan The SCVLANInterface interface.
 824         @result TRUE if the interface was removed; FALSE if an error was encountered.
 825  */
 826 Boolean
 827 SCVLANInterfaceRemove                           (SCVLANInterfaceRef             vlan)           API_AVAILABLE(macos(10.5))
 828                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 829
 830 /*!
 831         @function SCVLANInterfaceGetPhysicalInterface
 832         @discussion Returns the physical interface for the specified VLAN interface.
 833         @param vlan The SCVLANInterface interface.
 834         @result The list of interfaces.
 835  */
 836 SCNetworkInterfaceRef __nullable
 837 SCVLANInterfaceGetPhysicalInterface             (SCVLANInterfaceRef             vlan)           API_AVAILABLE(macos(10.5))
 838                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 839
 840 /*!
 841         @function SCVLANInterfaceGetTag
 842         @discussion Returns the tag for the specified VLAN interface.
 843         @param vlan The SCVLANInterface interface.
 844         @result The tag.
 845  */
 846 CFNumberRef __nullable
 847 SCVLANInterfaceGetTag                           (SCVLANInterfaceRef             vlan)           API_AVAILABLE(macos(10.5))
 848                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 849
 850 /*!
 851         @function SCVLANInterfaceGetOptions
 852         @discussion Returns the configuration settings associated with the VLAN interface.
 853         @param vlan The SCVLANInterface interface.
 854         @result The configuration settings associated with the VLAN interface;
 855                 NULL if no changes to the default configuration have been saved.
 856  */
 857 CFDictionaryRef __nullable
 858 SCVLANInterfaceGetOptions                       (SCVLANInterfaceRef             vlan)           API_AVAILABLE(macos(10.5))
 859                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 860
 861 /*!
 862         @function SCVLANInterfaceSetPhysicalInterfaceAndTag
 863         @discussion Updates the specified VLAN interface.
 864         @param vlan The SCVLANInterface interface.
 865         @param physical The physical interface to associate with the VLAN.
 866         @param tag The tag to associate with the VLAN.
 867         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 868
 869         Note: the tag must be in the range (1 <= tag <= 4094)
 870  */
 871 Boolean
 872 SCVLANInterfaceSetPhysicalInterfaceAndTag       (SCVLANInterfaceRef             vlan,
 873                                                  SCNetworkInterfaceRef          physical,
 874                                                  CFNumberRef                    tag)            API_AVAILABLE(macos(10.5))
 875                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 876
 877 /*!
 878         @function SCVLANInterfaceSetLocalizedDisplayName
 879         @discussion Sets the localized display name for the specified VLAN interface.
 880         @param vlan The SCVLANInterface interface.
 881         @param newName The new display name.
 882         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 883  */
 884 Boolean
 885 SCVLANInterfaceSetLocalizedDisplayName          (SCVLANInterfaceRef             vlan,
 886                                                  CFStringRef                    newName)        API_AVAILABLE(macos(10.5))
 887                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 888
 889 /*!
 890         @function SCVLANInterfaceSetOptions
 891         @discussion Sets the configuration settings for the specified VLAN interface.
 892         @param vlan The SCVLANInterface interface.
 893         @param newOptions The new configuration settings.
 894         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 895  */
 896 Boolean
 897 SCVLANInterfaceSetOptions                       (SCVLANInterfaceRef             vlan,
 898                                                  CFDictionaryRef                newOptions)     API_AVAILABLE(macos(10.5))
 899                                                                                                 SPI_AVAILABLE(ios(4.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 900
 901
 902 /* --------------------------------------------------------------------------------
 903  * PROTOCOLS
 904  * -------------------------------------------------------------------------------- */
 905
 906 /*!
 907         @group Protocol configuration
 908  */
 909
 910 #pragma mark -
 911 #pragma mark SCNetworkProtocol configuration (APIs)
 912
 913 /*!
 914         @function SCNetworkProtocolGetTypeID
 915         @discussion Returns the type identifier of all SCNetworkProtocol instances.
 916  */
 917 CFTypeID
 918 SCNetworkProtocolGetTypeID                      (void)                                          API_AVAILABLE(macos(10.4))
 919                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 920
 921 /*!
 922         @function SCNetworkProtocolGetConfiguration
 923         @discussion Returns the configuration settings associated with the protocol.
 924         @param protocol The network protocol.
 925         @result The configuration settings associated with the protocol;
 926                 NULL if no configuration settings are associated with the protocol
 927                 or an error was encountered.
 928  */
 929 CFDictionaryRef __nullable
 930 SCNetworkProtocolGetConfiguration               (SCNetworkProtocolRef           protocol)       API_AVAILABLE(macos(10.4))
 931                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 932
 933 /*!
 934         @function SCNetworkProtocolGetEnabled
 935         @discussion Returns whether this protocol has been enabled.
 936         @param protocol The network protocol.
 937         @result TRUE if the protocol is enabled.
 938  */
 939 Boolean
 940 SCNetworkProtocolGetEnabled                     (SCNetworkProtocolRef           protocol)       API_AVAILABLE(macos(10.4))
 941                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 942
 943 /*!
 944         @function SCNetworkProtocolGetProtocolType
 945         @discussion Returns the associated network protocol type.
 946         @param protocol The network protocol.
 947         @result The protocol type.
 948  */
 949 CFStringRef __nullable
 950 SCNetworkProtocolGetProtocolType                (SCNetworkProtocolRef           protocol)       API_AVAILABLE(macos(10.4))
 951                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 952
 953 /*!
 954         @function SCNetworkProtocolSetConfiguration
 955         @discussion Stores the configuration settings for the protocol.
 956         @param protocol The network protocol.
 957         @param config The configuration settings to associate with this protocol.
 958         @result TRUE if the configuration was stored; FALSE if an error was encountered.
 959  */
 960 Boolean
 961 SCNetworkProtocolSetConfiguration               (SCNetworkProtocolRef           protocol,
 962                                                  CFDictionaryRef __nullable     config)         API_AVAILABLE(macos(10.4))
 963                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 964
 965 /*!
 966         @function SCNetworkProtocolSetEnabled
 967         @discussion Enables or disables the protocol.
 968         @param protocol The network protocol.
 969         @param enabled TRUE if the protocol should be enabled.
 970         @result TRUE if the enabled status was saved; FALSE if an error was encountered.
 971  */
 972 Boolean
 973 SCNetworkProtocolSetEnabled                     (SCNetworkProtocolRef           protocol,
 974                                                  Boolean                        enabled)        API_AVAILABLE(macos(10.4))
 975                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 976
 977 /* --------------------------------------------------------------------------------
 978  * SERVICES
 979  * -------------------------------------------------------------------------------- */
 980
 981 /*!
 982         @group Service configuration
 983  */
 984
 985 #pragma mark -
 986 #pragma mark SCNetworkService configuration (APIs)
 987
 988 /*!
 989         @function SCNetworkServiceGetTypeID
 990         @discussion Returns the type identifier of all SCNetworkService instances.
 991  */
 992 CFTypeID
 993 SCNetworkServiceGetTypeID                       (void)                                          API_AVAILABLE(macos(10.4))
 994                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
 995
 996 /*!
 997         @function SCNetworkServiceAddProtocolType
 998         @discussion Adds a network protocol of the specified type to the
 999                 service.  The protocal configuration is set to default values
1000                 that are appropriate for the interface associated with the
1001                 service.
1002         @param service The network service.
1003         @param protocolType The type of SCNetworkProtocol to be added to the service.
1004         @result TRUE if the protocol was added to the service; FALSE if the
1005                 protocol was already present or an error was encountered.
1006  */
1007 Boolean
1008 SCNetworkServiceAddProtocolType                 (SCNetworkServiceRef            service,
1009                                                  CFStringRef                    protocolType)   API_AVAILABLE(macos(10.4))
1010                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1011
1012 /*!
1013         @function SCNetworkServiceCopyAll
1014         @discussion Returns all available network services for the specified preferences.
1015         @param prefs The "preferences" session.
1016         @result The list of SCNetworkService services associated with the preferences.
1017                 You must release the returned value.
1018  */
1019 CFArrayRef /* of SCNetworkServiceRef's */ __nullable
1020 SCNetworkServiceCopyAll                         (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.4))
1021                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1022
1023 /*!
1024         @function SCNetworkServiceCopyProtocols
1025         @discussion Returns all network protocols associated with the service.
1026         @param service The network service.
1027         @result The list of SCNetworkProtocol protocols associated with the service.
1028                 You must release the returned value.
1029  */
1030 CFArrayRef /* of SCNetworkProtocolRef's */ __nullable
1031 SCNetworkServiceCopyProtocols                   (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1032                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1033
1034 /*!
1035         @function SCNetworkServiceCreate
1036         @discussion Create a new network service for the specified interface in the
1037                 configuration.
1038         @param prefs The "preferences" session.
1039         @result A reference to the new SCNetworkService.
1040                 You must release the returned value.
1041  */
1042 SCNetworkServiceRef __nullable
1043 SCNetworkServiceCreate                          (SCPreferencesRef               prefs,
1044                                                  SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.4))
1045                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1046
1047 /*!
1048         @function SCNetworkServiceCopy
1049         @discussion Returns the network service with the specified identifier.
1050         @param prefs The "preferences" session.
1051         @param serviceID The unique identifier for the service.
1052         @result A reference to the SCNetworkService from the associated preferences;
1053                 NULL if the serviceID does not exist in the preferences or if an
1054                 error was encountered.
1055                 You must release the returned value.
1056  */
1057 SCNetworkServiceRef __nullable
1058 SCNetworkServiceCopy                            (SCPreferencesRef               prefs,
1059                                                  CFStringRef                    serviceID)      API_AVAILABLE(macos(10.4))
1060                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1061
1062 /*!
1063         @function SCNetworkServiceEstablishDefaultConfiguration
1064         @discussion Establishes the "default" configuration for a network
1065                 service.  This configuration includes the addition of
1066                 network protocols for the service (with "default"
1067                 configuration options).
1068         @param service The network service.
1069         @result TRUE if the configuration was updated; FALSE if an error was encountered.
1070 */
1071 Boolean
1072 SCNetworkServiceEstablishDefaultConfiguration   (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.5))
1073                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1074
1075 /*!
1076         @function SCNetworkServiceGetEnabled
1077         @discussion Returns whether this service has been enabled.
1078         @param service The network service.
1079         @result TRUE if the service is enabled.
1080  */
1081 Boolean
1082 SCNetworkServiceGetEnabled                      (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1083                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1084
1085 /*!
1086         @function SCNetworkServiceGetInterface
1087         @discussion Returns the network interface associated with the service.
1088         @param service The network service.
1089         @result A reference to the SCNetworkInterface associated with the service;
1090                 NULL if an error was encountered.
1091  */
1092 SCNetworkInterfaceRef __nullable
1093 SCNetworkServiceGetInterface                    (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1094                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1095
1096 /*!
1097         @function SCNetworkServiceGetName
1098         @discussion Returns the [user specified] name associated with the service.
1099         @param service The network service.
1100         @result The [user specified] name.
1101  */
1102 CFStringRef __nullable
1103 SCNetworkServiceGetName                         (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1104                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1105
1106 /*!
1107         @function SCNetworkServiceCopyProtocol
1108         @discussion Returns the network protocol of the specified type for
1109                 the service.
1110         @param service The network service.
1111         @result A reference to the SCNetworkProtocol associated with the service;
1112                 NULL if this protocol has not been added or if an error was encountered.
1113                 You must release the returned value.
1114  */
1115 SCNetworkProtocolRef __nullable
1116 SCNetworkServiceCopyProtocol                    (SCNetworkServiceRef            service,
1117                                                  CFStringRef                    protocolType)   API_AVAILABLE(macos(10.4))
1118                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1119
1120 /*!
1121         @function SCNetworkServiceGetServiceID
1122         @discussion Returns the identifier for the service.
1123         @param service The network service.
1124         @result The service identifier.
1125  */
1126 CFStringRef __nullable
1127 SCNetworkServiceGetServiceID                    (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1128                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1129
1130 /*!
1131         @function SCNetworkServiceRemove
1132         @discussion Removes the network service from the configuration.
1133         @param service The network service.
1134         @result TRUE if the service was removed; FALSE if an error was encountered.
1135  */
1136 Boolean
1137 SCNetworkServiceRemove                          (SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1138                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1139
1140 /*!
1141         @function SCNetworkServiceRemoveProtocolType
1142         @discussion Removes the network protocol of the specified type from the service.
1143         @param service The network service.
1144         @param protocolType The type of SCNetworkProtocol to be removed from the service.
1145         @result TRUE if the protocol was removed to the service; FALSE if the
1146                 protocol was not configured or an error was encountered.
1147  */
1148 Boolean
1149 SCNetworkServiceRemoveProtocolType              (SCNetworkServiceRef            service,
1150                                                  CFStringRef                    protocolType)   API_AVAILABLE(macos(10.4))
1151                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1152
1153 /*!
1154         @function SCNetworkServiceSetEnabled
1155         @discussion Enables or disables the service.
1156         @param service The network service.
1157         @param enabled TRUE if the service should be enabled.
1158         @result TRUE if the enabled status was saved; FALSE if an error was encountered.
1159  */
1160 Boolean
1161 SCNetworkServiceSetEnabled                      (SCNetworkServiceRef            service,
1162                                                  Boolean                        enabled)        API_AVAILABLE(macos(10.4))
1163                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1164
1165 /*!
1166         @function SCNetworkServiceSetName
1167         @discussion Stores the [user specified] name for the service.
1168         @param service The network service.
1169         @param name The [user defined] name to associate with the service.
1170         @result TRUE if the name was saved; FALSE if an error was encountered.
1171
1172         Note: although not technically required, the [user specified] names
1173         for all services within any given set should be unique.  As such, an
1174         error will be returned if you attemp to name two services with the
1175         same string.
1176  */
1177 Boolean
1178 SCNetworkServiceSetName                         (SCNetworkServiceRef            service,
1179                                                  CFStringRef __nullable         name)           API_AVAILABLE(macos(10.4))
1180                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1181
1182
1183 /* --------------------------------------------------------------------------------
1184  * SETS
1185  * -------------------------------------------------------------------------------- */
1186
1187 /*!
1188         @group Set configuration
1189  */
1190
1191 #pragma mark -
1192 #pragma mark SCNetworkSet configuration (APIs)
1193
1194 /*!
1195         @function SCNetworkSetGetTypeID
1196         @discussion Returns the type identifier of all SCNetworkSet instances.
1197  */
1198 CFTypeID
1199 SCNetworkSetGetTypeID                           (void)                                          API_AVAILABLE(macos(10.4))
1200                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1201
1202 /*!
1203         @function SCNetworkSetAddService
1204         @discussion Adds the network service to the set.
1205         @param set The network set.
1206         @param service The service to be added.
1207         @result TRUE if the service was added to the set; FALSE if the
1208                 service was already present or an error was encountered.
1209
1210         Note: prior to Mac OS X 10.5, the Network Preferences UI
1211         did not support having a single service being a member of
1212         more than one set.  An error will be returned if you attempt
1213         to add a service to more than one set on a pre-10.5 system.
1214  */
1215 Boolean
1216 SCNetworkSetAddService                          (SCNetworkSetRef                set,
1217                                                  SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1218                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1219
1220 /*!
1221         @function SCNetworkSetContainsInterface
1222         @discussion Checks if an interface is represented by at least one
1223                 network service in the specified set.
1224         @param set The network set.
1225         @param interface The network interface.
1226         @result TRUE if the interface is represented in the set; FALSE if not.
1227  */
1228 Boolean
1229 SCNetworkSetContainsInterface                   (SCNetworkSetRef                set,
1230                                                  SCNetworkInterfaceRef          interface)      API_AVAILABLE(macos(10.5))
1231                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1232
1233 /*!
1234         @function SCNetworkSetCopyAll
1235         @discussion Returns all available sets for the specified preferences.
1236         @param prefs The "preferences" session.
1237         @result The list of SCNetworkSet sets associated with the preferences.
1238                 You must release the returned value.
1239  */
1240 CFArrayRef /* of SCNetworkSetRef's */ __nullable
1241 SCNetworkSetCopyAll                             (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.4))
1242                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1243
1244 /*!
1245         @function SCNetworkSetCopyCurrent
1246         @discussion Returns the "current" set.
1247         @param prefs The "preferences" session.
1248         @result The current set; NULL if no current set has been defined.
1249  */
1250 SCNetworkSetRef __nullable
1251 SCNetworkSetCopyCurrent                         (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.4))
1252                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1253
1254 /*!
1255         @function SCNetworkSetCopyServices
1256         @discussion Returns all network services associated with the set.
1257         @param set The network set.
1258         @result The list of SCNetworkService services associated with the set.
1259                 You must release the returned value.
1260  */
1261 CFArrayRef /* of SCNetworkServiceRef's */ __nullable
1262 SCNetworkSetCopyServices                        (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1263                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1264
1265 /*!
1266         @function SCNetworkSetCreate
1267         @discussion Create a new set in the configuration.
1268         @param prefs The "preferences" session.
1269         @result A reference to the new SCNetworkSet.
1270                 You must release the returned value.
1271  */
1272 SCNetworkSetRef __nullable
1273 SCNetworkSetCreate                              (SCPreferencesRef               prefs)          API_AVAILABLE(macos(10.4))
1274                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1275
1276 /*!
1277         @function SCNetworkSetCopy
1278         @discussion Returns the set with the specified identifier.
1279         @param prefs The "preferences" session.
1280         @param setID The unique identifier for the set.
1281         @result A reference to the SCNetworkSet from the associated preferences;
1282                 NULL if the setID does not exist in the preferences or if an
1283                 error was encountered.
1284                 You must release the returned value.
1285  */
1286 SCNetworkSetRef __nullable
1287 SCNetworkSetCopy                                (SCPreferencesRef               prefs,
1288                                                  CFStringRef                    setID)          API_AVAILABLE(macos(10.4))
1289                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1290
1291 /*!
1292         @function SCNetworkSetGetName
1293         @discussion Returns the [user specified] name associated with the set.
1294         @param set The network set.
1295         @result The [user specified] name.
1296  */
1297 CFStringRef __nullable
1298 SCNetworkSetGetName                             (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1299                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1300
1301 /*!
1302         @function SCNetworkSetGetSetID
1303         @discussion Returns the identifier for the set.
1304         @param set The network set.
1305         @result The set identifier.
1306  */
1307 CFStringRef __nullable
1308 SCNetworkSetGetSetID                            (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1309                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1310
1311 /*!
1312         @function SCNetworkSetGetServiceOrder
1313         @discussion Returns the [user specified] ordering of network services
1314                 within the set.
1315         @param set The network set.
1316         @result The ordered list of CFStringRef service identifiers associated
1317                 with the set;
1318                 NULL if no service order has been specified or if an error
1319                 was encountered.
1320  */
1321 CFArrayRef /* of serviceID CFStringRef's */ __nullable
1322 SCNetworkSetGetServiceOrder                     (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1323                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1324
1325 /*!
1326         @function SCNetworkSetRemove
1327         @discussion Removes the set from the configuration.
1328         @param set The network set.
1329         @result TRUE if the set was removed; FALSE if an error was encountered.
1330  */
1331 Boolean
1332 SCNetworkSetRemove                              (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1333                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1334
1335 /*!
1336         @function SCNetworkSetRemoveService
1337         @discussion Removes the network service from the set.
1338         @param set The network set.
1339         @param service The service to be removed.
1340         @result TRUE if the service was removed from the set; FALSE if the
1341                 service was not already present or an error was encountered.
1342  */
1343 Boolean
1344 SCNetworkSetRemoveService                       (SCNetworkSetRef                set,
1345                                                  SCNetworkServiceRef            service)        API_AVAILABLE(macos(10.4))
1346                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1347
1348 /*!
1349         @function SCNetworkSetSetCurrent
1350         @discussion Specifies the set that should be the "current" set.
1351         @param set The network set.
1352         @result TRUE if the current set was updated;
1353                 FALSE if an error was encountered.
1354  */
1355 Boolean
1356 SCNetworkSetSetCurrent                          (SCNetworkSetRef                set)            API_AVAILABLE(macos(10.4))
1357                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1358
1359 /*!
1360         @function SCNetworkSetSetName
1361         @discussion Stores the [user specified] name for the set.
1362         @param set The network set.
1363         @param name The [user defined] name to associate with the set.
1364         @result TRUE if the name was saved; FALSE if an error was encountered.
1365
1366         Note: although not technically required, the [user specified] names
1367         for all set should be unique.  As such, an error will be returned if
1368         you attemp to name two sets with the same string.
1369  */
1370 Boolean
1371 SCNetworkSetSetName                             (SCNetworkSetRef                set,
1372                                                  CFStringRef __nullable         name)           API_AVAILABLE(macos(10.4))
1373                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
1374
1375 /*!
1376         @function SCNetworkSetSetServiceOrder
1377         @discussion Stores the [user specified] ordering of network services for the set.
1378         @param set The network set.
1379         @param newOrder The ordered list of CFStringRef service identifiers for the set.
1380         @result TRUE if the new service order was saved; FALSE if an error was encountered.
1381  */
1382 Boolean
1383 SCNetworkSetSetServiceOrder                     (SCNetworkSetRef                set,
1384                                                  CFArrayRef                     newOrder)       API_AVAILABLE(macos(10.4))
1385                                                                                                 SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));        /* serviceID CFStringRef's */
1386
1387
1388 __END_DECLS
1389
1390 CF_ASSUME_NONNULL_END
1391 CF_IMPLICIT_BRIDGING_DISABLED
1392
1393 #endif  /* _SCNETWORKCONFIGURATION_H */