SCNetworkConfiguration Reference

Framework
Declared in
SCNetworkConfiguration.h

Overview

The SCNetworkConfiguration programming interface provides access to the stored network configuration. The functions include providing access to the network-capable devices on the system, the network sets, network services, and network protocols. Note that these functions follow Core Foundation function-name conventions. A function that has "Create" or "Copy" in its name returns a reference you must release with the CFRelease function.

Note that when using the functions in this programming interface, you must call the SCPreferencesCommitChanges function to ensure that your changes are committed to permanent storage.

Functions by Task

Configuring Ethernet Bond Interfaces

Configuring Network Interfaces

Configuring Network Protocols

Configuring Network Services

Configuring Network Sets

Configuring VLAN Interfaces

Functions

SCBondInterfaceCopyAll

Returns all Ethernet bond interfaces on the system.

CFArrayRef SCBondInterfaceCopyAll (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The list of Ethernet bond interfaces on the system. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceCopyAvailableMemberInterfaces

Returns all network capable devices on the system that can be added to an Ethernet bond interface.

CFArrayRef SCBondInterfaceCopyAvailableMemberInterfaces (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The list of interfaces. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceCopyStatus

Returns the status of the specified Ethernet bond interface.

SCBondStatusRef SCBondInterfaceCopyStatus (
   SCBondInterfaceRef bond
);
Parameters
bond

The Ethernet bond interface.

Return Value

The status associated with the interface. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceCreate

Creates a new Ethernet bond interface.

SCBondInterfaceRef SCBondInterfaceCreate (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The new Ethernet bond interface, represented by an SCBondInterfaceRef object. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceGetMemberInterfaces

Returns the member interfaces for the specified Ethernet bond interface.

CFArrayRef SCBondInterfaceGetMemberInterfaces (
   SCBondInterfaceRef bond
);
Parameters
bond

The Ethernet bond interface.

Return Value

The list of interfaces.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceGetOptions

Returns the configuration settings associated with the specified Ethernet bond interface.

CFDictionaryRef SCBondInterfaceGetOptions (
   SCBondInterfaceRef bond
);
Parameters
bond

The Ethernet bond interface.

Return Value

The configuration settings associated with the Ethernet bond interface, or NULL if no changes to the default configuration have been saved.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceRemove

Removes the Ethernet bond interface from the configuration.

Boolean SCBondInterfaceRemove (
   SCBondInterfaceRef bond
);
Parameters
bond

The Ethernet bond interface.

Return Value

TRUE if the interface was removed; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceSetLocalizedDisplayName

Sets the localized display name for the specified Ethernet bond interface.

Boolean SCBondInterfaceSetLocalizedDisplayName (
   SCBondInterfaceRef bond,
   CFStringRef newName
);
Parameters
bond

The Ethernet bond interface.

newName

The new display name.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceSetMemberInterfaces

Sets the member interfaces for the specified Ethernet bond interface.

Boolean SCBondInterfaceSetMemberInterfaces (
   SCBondInterfaceRef bond,
   CFArrayRef members
);
Parameters
bond

The Ethernet bond interface

members

The desired member interfaces.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceSetOptions

Sets the configuration settings for the specified Ethernet bond interface.

Boolean SCBondInterfaceSetOptions (
   SCBondInterfaceRef bond,
   CFDictionaryRef newOptions
);
Parameters
bond

The Ethernet bond interface.

newOptions

The new configuration settings.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondStatusGetInterfaceStatus

Returns the status of the specified member interface of an Ethernet bond or the status of the bond as a whole.

CFDictionaryRef SCBondStatusGetInterfaceStatus (
   SCBondStatusRef bondStatus,
   SCNetworkInterfaceRef interface
);
Parameters
bondStatus

The Ethernet bond status.

interface

The member interface whose status is needed. Pass NULL to get the status of the Ethernet bond.

Return Value

The interface status.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondStatusGetMemberInterfaces

Returns the member interfaces that are represented with the Ethernet bond interface.

CFArrayRef SCBondStatusGetMemberInterfaces (
   SCBondStatusRef bondStatus
);
Parameters
bondStatus

The Ethernet bond status.

Return Value

The list of interfaces.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondStatusGetTypeID

Returns the type identifier of all SCBondStatusRef instances.

CFTypeID SCBondStatusGetTypeID (
   void
);
Return Value

The type identifier of all SCBondStatusRef instances.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCopyAll

Returns all network-capable interfaces on the system.

CFArrayRef SCNetworkInterfaceCopyAll (
   void
);
Return Value

The list of interfaces on the system. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCopyMediaOptions

Returns information media options for the specified network interface.

Boolean SCNetworkInterfaceCopyMediaOptions (
   SCNetworkInterfaceRef interface,
   CFDictionaryRef *current,
   CFDictionaryRef *active,
   CFArrayRef *available,
   Boolean filter
);
Parameters
interface

The network interface.

current

On output, a dictionary representing the currently requested media options (subtype, options). If NULL, the current options are not returned.

active

On output, a dictionary representing the active media options (subtype, options). If NULL, the active options are not returned.

available

On output, an array representing the possible media options (subtype, options). If NULL, the current options are not returned.

filter

A Boolean value indicating whether the available options should be filtered to exclude those options which would not normally be requested by a user/admin (for example, hw-loopback).

Return Value

TRUE if requested information has been returned.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCopyMediaSubTypeOptions

Returns a list of available media options for the specified interface configuration options and subtype.

CFArrayRef SCNetworkInterfaceCopyMediaSubTypeOptions (
   CFArrayRef available,
   CFStringRef subType
);
Parameters
available

The available options as returned by the SCNetworkInterfaceCopyMediaOptions function.

subType

The subtype.

Return Value

An array of available media options, or NULL if no options are available. Each of the available options is returned as an array of strings.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCopyMediaSubTypes

Returns a list of available media subtypes for the specified interface configuration options.

CFArrayRef SCNetworkInterfaceCopyMediaSubTypes (
   CFArrayRef available
);
Parameters
available

The available options as returned by the SCNetworkInterfaceCopyMediaOptions function.

Return Value

An array of available media subtypes (for example, 10BaseT/UTP, 100baseTX, etc), or NULL if no subtypes are available

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCopyMTU

Returns the current MTU setting and the range of allowable values for the specified network interface.

Boolean SCNetworkInterfaceCopyMTU (
   SCNetworkInterfaceRef interface,
   int *mtu_cur,
   int *mtu_min,
   int *mtu_max
);
Parameters
interface

The network interface.

mtu_cur

On output, the current MTU setting for the interface.

mtu_min

On output, the minimum MTU setting for the interface. If negative, the minimum setting could not be determined.

mtu_max

On output, the maximum MTU setting for the interface. If negative, the maximum setting could not be determined.

Return Value

TRUE if the requested information has been returned.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceCreateWithInterface

Creates a new network interface layered on top of the specified interface.

SCNetworkInterfaceRef SCNetworkInterfaceCreateWithInterface (
   SCNetworkInterfaceRef interface,
   CFStringRef interfaceType
);
Parameters
interface

The network interface.

interfaceType

The type of interface to layer on top of the network interface specified in interface.

Return Value

A reference to the new network interface. You must release the returned value.

Discussion

You can use this function to create a "PPP" interface on top of a "modem."

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceForceConfigurationRefresh

Sends a notification to interested network configuration agents to immediately retry their configuration.

Boolean SCNetworkInterfaceForceConfigurationRefresh (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The desired network interface.

Return Value

TRUE if the notification was sent; otherwise, FALSE.

Discussion

Calling this function causes the DHCP client to contact the DHCP server immediately rather than waiting until its timeout has expired. The caller uses this function to inform the system that the network infrastructure or configuration has changed.

Note that this function requires root privilege; alternatively, you can pass in an interface that is derived from a sequence of calls to:

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetBSDName

Returns the BSD interface or device name for the specified interface.

CFStringRef SCNetworkInterfaceGetBSDName (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The BSD name associated with the interface (for example, en0), or NULL if no BSD name is available.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetConfiguration

Returns the configuration settings associated with the specified interface.

CFDictionaryRef SCNetworkInterfaceGetConfiguration (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The configuration settings associated with the interface, or NULL if no configuration settings are associated with the interface or an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetExtendedConfiguration

Returns the extended configuration settings associated with the specified interface.

CFDictionaryRef SCNetworkInterfaceGetExtendedConfiguration (
   SCNetworkInterfaceRef interface,
   CFStringRef extendedType
);
Parameters
interface

The network interface.

extendedType

The type of extended information (for example, EAPOL).

Return Value

The configuration settings associated with the interface, or NULL if no configuration settings are associated with the interface or an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetHardwareAddressString

Returns a displayable link layer address for the specified interface.

CFStringRef SCNetworkInterfaceGetHardwareAddressString (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The hardware MAC (Media Access Control) address for the interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetInterface

Returns the underlying interface, for layered network interfaces.

SCNetworkInterfaceRef SCNetworkInterfaceGetInterface (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The underlying network interface, or NULL if the specified interface is a leaf interface.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetInterfaceType

Returns the network interface type of the specified interface.

CFStringRef SCNetworkInterfaceGetInterfaceType (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The interface type.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetLocalizedDisplayName

Returns the localized display name, such as "Ethernet" or "FireWire," for the specified interface.

CFStringRef SCNetworkInterfaceGetLocalizedDisplayName (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The localized display name for the interface, or NULL if no name is available.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetSupportedInterfaceTypes

Identifies all of the network interface types, such as PPP, that can be layered on top of the specified interface.

CFArrayRef SCNetworkInterfaceGetSupportedInterfaceTypes (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The list of network interface types supported by the specified interface, or NULL if no interface types are supported.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetSupportedProtocolTypes

Identifies all of the network protocol types, such as IPv4 and IPv6, that can be layered on top of the specified interface.

CFArrayRef SCNetworkInterfaceGetSupportedProtocolTypes (
   SCNetworkInterfaceRef interface
);
Parameters
interface

The network interface.

Return Value

The list of network protocol types supported by the specified interface, or NULL if no protocol types are supported.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceGetTypeID

Returns the type identifier of all SCNetworkInterface instances.

CFTypeID SCNetworkInterfaceGetTypeID (
   void
);
Return Value

The type identifier of all SCNetworkInterface instances.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceSetConfiguration

Stores the configuration settings for the specified interface.

Boolean SCNetworkInterfaceSetConfiguration (
   SCNetworkInterfaceRef interface,
   CFDictionaryRef config
);
Parameters
interface

The network interface.

config

The configuration settings to store.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceSetExtendedConfiguration

Stores the extended configuration settings for the specified interface.

Boolean SCNetworkInterfaceSetExtendedConfiguration (
   SCNetworkInterfaceRef interface,
   CFStringRef extendedType,
   CFDictionaryRef config
);
Parameters
interface

The network interface.

extendedType

The type of extended information.

config

The extended configuration settings to store.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceSetMediaOptions

Sets the requested media subtype and options for the specified network interface.

Boolean SCNetworkInterfaceSetMediaOptions (
   SCNetworkInterfaceRef interface,
   CFStringRef subtype,
   CFArrayRef options
);
Parameters
interface

The network interface.

subtype

The media subtype to set (for example, "autoselect" or "100baseTX").

options

The media options to set (for example, "half-duplex" or "full-duplex"). If NULL, the active options are not returned.

Return Value

TRUE if the configuration was updated; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkInterfaceSetMTU

Sets the requested MTU setting for the specified network interface.

Boolean SCNetworkInterfaceSetMTU (
   SCNetworkInterfaceRef interface,
   int mtu
);
Parameters
interface

The network interface.

mtu

The MTU setting.

Return Value

TRUE if the configuration was updated; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolGetConfiguration

Returns the configuration settings associated with the specified protocol.

CFDictionaryRef SCNetworkProtocolGetConfiguration (
   SCNetworkProtocolRef protocol
);
Parameters
protocol

The network protocol.

Return Value

The configuration settings associated with the protocol, or NULL if no configuration settings are associated with the protocol or an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolGetEnabled

Returns a Boolean value indicating whether the specified protocol is enabled.

Boolean SCNetworkProtocolGetEnabled (
   SCNetworkProtocolRef protocol
);
Parameters
protocol

The network protocol.

Return Value

TRUE if the protocol is enabled; otherwise, FALSE.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolGetProtocolType

Returns the type of the specified network protocol.

CFStringRef SCNetworkProtocolGetProtocolType (
   SCNetworkProtocolRef protocol
);
Parameters
protocol

The network protocol.

Return Value

The protocol type.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolGetTypeID

Returns the type identifier of all SCNetworkProtocol instances.

CFTypeID SCNetworkProtocolGetTypeID (
   void
);
Return Value

The type identifier of all SCNetworkProtocol instances.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolSetConfiguration

Stores the configuration settings for the specified network protocol.

Boolean SCNetworkProtocolSetConfiguration (
   SCNetworkProtocolRef protocol,
   CFDictionaryRef config
);
Parameters
protocol

The network protocol.

config

The configuration settings to store.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolSetEnabled

Enables or disables the specified protocol.

Boolean SCNetworkProtocolSetEnabled (
   SCNetworkProtocolRef protocol,
   Boolean enabled
);
Parameters
protocol

The network protocol to enable or disable.

enabled

TRUE if the protocol should be enabled.

Return Value

TRUE if the enabled status was saved; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceAddProtocolType

Adds the network protocol of the specified type to the specified service.

Boolean SCNetworkServiceAddProtocolType (
   SCNetworkServiceRef service,
   CFStringRef protocolType
);
Parameters
service

The network service.

protocolType

The type of network protocol to add to the service.

Return Value

TRUE if the protocol was added to the service; FALSE if the protocol was already present or an error occurred.

Discussion

The protocol configuration is set to default values that are appropriate for the interface associated with the service.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceCopy

Returns the network service with the specified identifier.

SCNetworkServiceRef SCNetworkServiceCopy (
   SCPreferencesRef prefs,
   CFStringRef serviceID
);
Parameters
prefs

The preferences session.

serviceID

The unique identifier of the network service.

Return Value

The network service from the associated preferences, or NULL if the service ID does not exist in the preferences or if an error occurred. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceCopyAll

Returns all available network services for the specified preferences.

CFArrayRef SCNetworkServiceCopyAll (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The list of network services associated with the preferences. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceCopyProtocol

Returns the network protocol of the specified type for the specified service.

SCNetworkProtocolRef SCNetworkServiceCopyProtocol (
   SCNetworkServiceRef service,
   CFStringRef protocolType
);
Parameters
service

The network service.

protocolType

The type of network protocol.

Return Value

The network protocol associated with the service, or NULL if this protocol has not been added or if an error occurred. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceCopyProtocols

Returns all network protocols associated with the specified service.

CFArrayRef SCNetworkServiceCopyProtocols (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

The network protocols associated with the service. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceCreate

Creates a new network service for the specified interface in the configuration.

SCNetworkServiceRef SCNetworkServiceCreate (
   SCPreferencesRef prefs,
   SCNetworkInterfaceRef interface
);
Parameters
prefs

The preferences session.

interface

The network interface for which to create the new service.

Return Value

The new network service. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceEstablishDefaultConfiguration

Establishes the default configuration for the specified network service.

Boolean SCNetworkServiceEstablishDefaultConfiguration (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

TRUE if the configuration was updated; FALSE if an error occurred.

Discussion

The default configuration includes the addition of network protocols for the service (with default configuration options).

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceGetEnabled

Returns a Boolean value indicating whether the specified service is enabled.

Boolean SCNetworkServiceGetEnabled (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

TRUE if the service is enabled; otherwise, FALSE.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceGetInterface

Returns the network interface associated with the specified service.

SCNetworkInterfaceRef SCNetworkServiceGetInterface (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

The network interface associated with the service, or NULL if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceGetName

Returns the user-specified name associated with the specified service.

CFStringRef SCNetworkServiceGetName (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

The user-specified name associated with the service.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceGetServiceID

Returns the identifier for the specified service.

CFStringRef SCNetworkServiceGetServiceID (
   SCNetworkServiceRef service
);
Parameters
service

The network service.

Return Value

The service identifier.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceGetTypeID

Returns the type identifier of all SCNetworkService instances.

CFTypeID SCNetworkServiceGetTypeID (
   void
);
Return Value

The type identifier of all SCNetworkService instances.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceRemove

Removes the specified network service from the configuration.

Boolean SCNetworkServiceRemove (
   SCNetworkServiceRef service
);
Parameters
service

The network service to remove.

Return Value

TRUE if the service was removed; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceRemoveProtocolType

Removes the network protocol of the specified type from the specified service.

Boolean SCNetworkServiceRemoveProtocolType (
   SCNetworkServiceRef service,
   CFStringRef protocolType
);
Parameters
service

The network service.

protocolType

The type of network protocol to remove from the service.

Return Value

TRUE if the protocol was removed to the service; FALSE if the protocol was not configured or an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceSetEnabled

Enables or disables the specified service.

Boolean SCNetworkServiceSetEnabled (
   SCNetworkServiceRef service,
   Boolean enabled
);
Parameters
service

The network service to enable or disable.

enabled

Pass TRUE if the service should be enabled; FALSE otherwise.

Return Value

TRUE if the enabled status was saved; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceSetName

Stores the user-specified name for the specified service.

Boolean SCNetworkServiceSetName (
   SCNetworkServiceRef service,
   CFStringRef name
);
Parameters
service

The network service.

name

The user-defined name to associate with the service.

Return Value

TRUE if the name was saved; FALSE if an error occurred.

Discussion

Although it is not technically required, the user-specified names for all services within any given set should be unique. For this reason, an error will be returned if you attempt to name two services with the same string.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetAddService

Adds the specified network service to the specified set.

Boolean SCNetworkSetAddService (
   SCNetworkSetRef set,
   SCNetworkServiceRef service
);
Parameters
set

The set (the complete configuration for a single location).

service

The service to add to the set.

Return Value

TRUE if the service was added to the set; FALSE if the service was already present or an error occurred.

Discussion

Prior to OS X v10.5, the Network Preferences pane did not support having a single service being a member of more than one set. Therefore, an error is returned if you attempt to add a service to more than one set on a pre-10.5 system.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetContainsInterface

Returns a Boolean value indicating whether the specified interface is represented by at least one network service in the specified set.

Boolean SCNetworkSetContainsInterface (
   SCNetworkSetRef set,
   SCNetworkInterfaceRef interface
);
Parameters
set

The set (the complete configuration for a single location).

interface

The network interface.

Return Value

TRUE if the interface is represented in the set; otherwise, FALSE.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetCopy

Returns the set with the specified identifier.

SCNetworkSetRef SCNetworkSetCopy (
   SCPreferencesRef prefs,
   CFStringRef setID
);
Parameters
prefs

The preferences session.

setID

The unique identifier for the set.

Return Value

The network set from the associated preferences, or NULL if the identifier does not exist in the preferences or if an error occurred. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetCopyAll

Returns all available sets for the specified preferences session.

CFArrayRef SCNetworkSetCopyAll (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The list of network sets associated with the preferences. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetCopyCurrent

Returns the current set.

SCNetworkSetRef SCNetworkSetCopyCurrent (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The current set, or NULL if no current set has been defined.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetCopyServices

Returns all network services associated with the specified set.

CFArrayRef SCNetworkSetCopyServices (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

The list of network services associated with the set. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetCreate

Creates a new set in the configuration.

SCNetworkSetRef SCNetworkSetCreate (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The new network set. You must release the returned value.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetGetName

Returns the user-specified name associated with the specified set.

CFStringRef SCNetworkSetGetName (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

The user-specified name associated with the set.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetGetServiceOrder

Returns the user-specified ordering of network services within the specified set.

CFArrayRef SCNetworkSetGetServiceOrder (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

The ordered list of service identifiers associated with the set, or NULL if no service order has been specified or if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetGetSetID

Returns the identifier for the specified set.

CFStringRef SCNetworkSetGetSetID (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

The set identifier.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetGetTypeID

Returns the type identifier of all SCNetworkSet instances.

CFTypeID SCNetworkSetGetTypeID (
   void
);
Return Value

The type identifier of all SCNetworkSet instances.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetRemove

Removes the specified set from the configuration.

Boolean SCNetworkSetRemove (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

TRUE if the set was removed; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetRemoveService

Removes the specified network service from the specified set.

Boolean SCNetworkSetRemoveService (
   SCNetworkSetRef set,
   SCNetworkServiceRef service
);
Parameters
set

The set (the complete configuration for a single location).

service

The service to remove.

Return Value

TRUE if the service was removed from the set; FALSE if the service was not already present or an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetSetCurrent

Specifies the set that should be the current set.

Boolean SCNetworkSetSetCurrent (
   SCNetworkSetRef set
);
Parameters
set

The set (the complete configuration for a single location).

Return Value

TRUE if the current set was updated; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetSetName

Stores the user-specified name for the specified set.

Boolean SCNetworkSetSetName (
   SCNetworkSetRef set,
   CFStringRef name
);
Parameters
set

The set (the complete configuration for a single location).

name

The user-defined name to associate with the set.

Return Value

TRUE if the name was saved; FALSE if an error occurred.

Discussion

Although it is not technically required, the user-specified names for all sets should be unique. For this reason, an error is returned if you attempt to name two sets with the same string.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetSetServiceOrder

Stores the user-specified ordering of network services for the specified set.

Boolean SCNetworkSetSetServiceOrder (
   SCNetworkSetRef set,
   CFArrayRef newOrder
);
Parameters
set

The set (the complete configuration for a single location).

newOrder

The ordered list of service identifiers for the set.

Return Value

TRUE if the new service order was saved; FALSE if an error occurred.

Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceCopyAll

Returns all virtual LAN (VLAN) interfaces on the system.

CFArrayRef SCVLANInterfaceCopyAll (
   SCPreferencesRef prefs
);
Parameters
prefs

The preferences session.

Return Value

The list of VLAN interfaces on the system. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceCopyAvailablePhysicalInterfaces

Returns the network capable devices on the system that can be associated with a virtual LAN (VLAN) interface.

CFArrayRef SCVLANInterfaceCopyAvailablePhysicalInterfaces (
   void
);
Return Value

The list of interfaces. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceCreate

Creates a new virtual LAN (VLAN) interface.

SCVLANInterfaceRef SCVLANInterfaceCreate (
   SCPreferencesRef prefs,
   SCNetworkInterfaceRef physical,
   CFNumberRef tag
);
Parameters
prefs

The preferences session.

physical

The physical interface to associate with the VLAN.

tag

The tag to associate with the VLAN. This value must be between 1 and 4094.

Return Value

The new VLAN interface. You must release the returned value.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceGetOptions

Returns the configuration settings associated with the virtual LAN (VLAN) interface.

CFDictionaryRef SCVLANInterfaceGetOptions (
   SCVLANInterfaceRef vlan
);
Parameters
vlan

The VLAN interface.

Return Value

The configuration settings associated with the VLAN interface, or NULL if no changes to the default configuration have been saved.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceGetPhysicalInterface

Returns the physical interface for the specified virtual LAN (VLAN) interface.

SCNetworkInterfaceRef SCVLANInterfaceGetPhysicalInterface (
   SCVLANInterfaceRef vlan
);
Parameters
vlan

The VLAN interface.

Return Value

The list of interfaces.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceGetTag

Returns the tag for the specified virtual LAN (VLAN) interface.

CFNumberRef SCVLANInterfaceGetTag (
   SCVLANInterfaceRef vlan
);
Parameters
vlan

The VLAN interface.

Return Value

The tag for the VLAN interface.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceRemove

Removes the virtual LAN (VLAN) interface from the configuration.

Boolean SCVLANInterfaceRemove (
   SCVLANInterfaceRef vlan
);
Parameters
vlan

The VLAN interface to remove.

Return Value

TRUE if the interface was removed; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceSetLocalizedDisplayName

Sets the localized display name for the specified virtual LAN (VLAN) interface.

Boolean SCVLANInterfaceSetLocalizedDisplayName (
   SCVLANInterfaceRef vlan,
   CFStringRef newName
);
Parameters
vlan

The VLAN interface.

newName

The new display name.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceSetOptions

Sets the specified configuration settings for the specified virtual LAN (VLAN) interface.

Boolean SCVLANInterfaceSetOptions (
   SCVLANInterfaceRef vlan,
   CFDictionaryRef newOptions
);
Parameters
vlan

The VLAN interface.

newOptions

The new configuration settings for the VLAN interface.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceSetPhysicalInterfaceAndTag

Updates the specified virtual LAN (VLAN) interface with the specified information.

Boolean SCVLANInterfaceSetPhysicalInterfaceAndTag (
   SCVLANInterfaceRef vlan,
   SCNetworkInterfaceRef physical,
   CFNumberRef tag
);
Parameters
vlan

The VLAN interface to update.

physical

The physical interface to associate with the VLAN interface.

tag

The tag to associate with the VLAN interface. This value must be between 1 and 4094.

Return Value

TRUE if the configuration was stored; FALSE if an error occurred.

Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

Data Types

SCNetworkInterfaceRef

The reference to an object that represents a network interface.

typedef const struct __SCNetworkInterface * SCNetworkInterfaceRef;
Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCBondInterfaceRef

The reference to an object that represents an Ethernet bond interface.

typedef SCNetworkInterfaceRef SCBondInterfaceRef;
Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCBondStatusRef

The reference to an object that represents the status of an Ethernet bond interface.

typedef const struct __SCBondStatus * SCBondStatusRef;
Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCVLANInterfaceRef

The reference to an object that represents a virtual LAN (VLAN) interface.

typedef SCNetworkInterfaceRef SCVLANInterfaceRef;
Availability
  • Available in OS X v10.5 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkProtocolRef

The reference to an object that represents a network protocol.

typedef const struct __SCNetworkProtocol * SCNetworkProtocolRef;
Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkServiceRef

The reference to an object that represents a network service.

typedef const struct __SCNetworkService * SCNetworkServiceRef;
Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

SCNetworkSetRef

The reference to an object that represents a network set.

typedef const struct __SCNetworkSet    * SCNetworkSetRef;
Availability
  • Available in OS X v10.4 and later.
Declared In
SCNetworkConfiguration.h

Constants

Ethernet Bond Aggregation Status

Ethernet bond aggregation status codes.

enum {
   kSCBondStatusOK = 0,
   kSCBondStatusLinkInvalid = 1,
   kSCBondStatusNoPartner = 2,
   kSCBondStatusNotInActiveGroup = 3,
   kSCBondStatusUnknown = 999
};
Constants
kSCBondStatusOK

The status is valid (for example, enabled, active, running, and so forth.)

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusLinkInvalid

The link state is not valid (such as down, half-duplex, or wrong speed).

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusNoPartner

The port on the switch to which the device is connected doesn't seem to have 802.3ad Link Aggregation enabled.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusNotInActiveGroup

Communication with a partner is occurring, but the link aggregation group is different from the one that is active.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusUnknown

Nonspecific failure.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

Ethernet Bond Status Constants

Ethernet bond status codes.

const CFStringRef kSCBondStatusDeviceAggregationStatus;
const CFStringRef kSCBondStatusDeviceCollecting;
const CFStringRef kSCBondStatusDeviceDistributing;
Constants
kSCBondStatusDeviceAggregationStatus

Device is aggregating. See “Ethernet Bond Aggregation Status” for a list of possible values.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusDeviceCollecting

Can be 0 or 1.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCBondStatusDeviceDistributing

Can be 0 or 1.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

Network Interface Types

Keys that identify network interface types.

const CFStringRef kSCNetworkInterfaceType6to4;
const CFStringRef kSCNetworkInterfaceTypeBluetooth;
const CFStringRef kSCNetworkInterfaceTypeBond;
const CFStringRef kSCNetworkInterfaceTypeEthernet;
const CFStringRef kSCNetworkInterfaceTypeFireWire;
const CFStringRef kSCNetworkInterfaceTypeIEEE80211;
const CFStringRef kSCNetworkInterfaceTypeIPSec;
const CFStringRef kSCNetworkInterfaceTypeIrDA;
const CFStringRef kSCNetworkInterfaceTypeL2TP;
const CFStringRef kSCNetworkInterfaceTypeModem;
const CFStringRef kSCNetworkInterfaceTypePPP;
const CFStringRef kSCNetworkInterfaceTypePPTP;
const CFStringRef kSCNetworkInterfaceTypeSerial;
const CFStringRef kSCNetworkInterfaceTypeVLAN;
const CFStringRef kSCNetworkInterfaceTypeWWAN;
const CFStringRef kSCNetworkInterfaceTypeIPv4;
const SCNetworkInterfaceRef kSCNetworkInterfaceIPv4;
Constants
kSCNetworkInterfaceType6to4

The 6to4 interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeBluetooth

The Bluetooth interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeBond

The Ethernet bond interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeEthernet

The Ethernet interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeFireWire

The FireWire interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeIEEE80211

The IEEE 802.11 interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeIPSec

The IPSec interface.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeIrDA

The IrDA interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeL2TP

The L2TP interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeModem

The modem interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypePPP

The PPP interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypePPTP

The PPTP interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeSerial

The serial interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeVLAN

The VLAN interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeWWAN

The WWAN interface.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceTypeIPv4

The IPv4 interface.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkInterfaceIPv4

A network interface that can used for layering other interfaces (for example, 6to4, PPTP, or L2TP) over an existing IPv4 network.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

Network Protocol Types

Keys that identify network protocol types.

const CFStringRef kSCNetworkProtocolTypeAppleTalk;
const CFStringRef kSCNetworkProtocolTypeDNS;
const CFStringRef kSCNetworkProtocolTypeIPv4;
const CFStringRef kSCNetworkProtocolTypeIPv6;
const CFStringRef kSCNetworkProtocolTypeProxies;
const CFStringRef kSCNetworkProtocolTypeSMB;
Constants
kSCNetworkProtocolTypeAppleTalk

The AppleTalk protocol.

Available in OS X v10.4 and later.

Deprecated in OS X v10.6.

Declared in SCNetworkConfiguration.h.

kSCNetworkProtocolTypeDNS

The DNS protocol.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkProtocolTypeIPv4

The IPv4 protocol.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkProtocolTypeIPv6

The IPv6 protocol.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkProtocolTypeProxies

Protocol proxies.

Available in OS X v10.4 and later.

Declared in SCNetworkConfiguration.h.

kSCNetworkProtocolTypeSMB

The SMB procotol.

Available in OS X v10.5 and later.

Declared in SCNetworkConfiguration.h.