SystemConfiguration.fproj/SCNetworkConfiguration.h

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