SystemConfiguration.fproj/SCNetworkConfiguration.h

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