Mac Developer Library

Developer

System Configuration Framework Reference SCNetworkConnection Reference

Options
Deployment Target:

On This Page
Language:

SCNetworkConnection Reference

The SCNetworkConnection programming interface contains functions that allow an application to control connection-oriented services defined in the system and get connection-status information. Note that these functions allow you to control and get information about existing services only. If you need to create, change, or remove services, you should use the SCNetworkConfiguration programming interface instead.

Functions

  • Returns the type identifier of all SCNetworkConnection instances.

    Declaration

    Swift

    func SCNetworkConnectionGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID SCNetworkConnectionGetTypeID ( void );

    Return Value

    The type identifier of all SCNetworkConnection instances.

    Availability

    Available in OS X v10.3 and later.

  • Provides the default service ID and a dictionary of user options for the specified connection.

    Declaration

    Swift

    func SCNetworkConnectionCopyUserPreferences(_ selectionOptions: CFDictionary?, _ serviceID: UnsafeMutablePointer<Unmanaged<CFString>?>, _ userOptions: UnsafeMutablePointer<Unmanaged<CFDictionary>?>) -> Bool

    Objective-C

    Boolean SCNetworkConnectionCopyUserPreferences ( CFDictionaryRef selectionOptions, CFStringRef _Nonnull *serviceID, CFDictionaryRef _Nonnull *userOptions );

    Parameters

    selectionOptions

    Currently unimplemented. Pass NULL.

    serviceID

    On output, a reference to the default service ID for starting connections.

    userOptions

    On output, a reference to the default user options dictionary for starting connections.

    Return Value

    TRUE if there is a valid service to dial; FALSE if the function was unable to retrieve a service to dial.

    Discussion

    You can use the service ID and user options values returned by this function to open a connection on the fly.

    Availability

    Available in OS X v10.3 and later.

  • Returns the service ID associated with the specified network connection.

    Declaration

    Swift

    func SCNetworkConnectionCopyServiceID(_ connection: SCNetworkConnection) -> CFString?

    Objective-C

    CFStringRef SCNetworkConnectionCopyServiceID ( SCNetworkConnectionRef connection );

    Parameters

    connection

    The network connection.

    Return Value

    The service ID associated with the network connection.

    Availability

    Available in OS X v10.3 and later.

  • Returns the status of the specified network connection.

    Declaration

    Swift

    func SCNetworkConnectionGetStatus(_ connection: SCNetworkConnection) -> SCNetworkConnectionStatus

    Objective-C

    SCNetworkConnectionStatus SCNetworkConnectionGetStatus ( SCNetworkConnectionRef connection );

    Parameters

    connection

    The network connection.

    Return Value

    The status of the network connection. See Network Connection Status Values for a list of possible values.

    Availability

    Available in OS X v10.3 and later.

  • Returns the extended status of the connection.

    Declaration

    Swift

    func SCNetworkConnectionCopyExtendedStatus(_ connection: SCNetworkConnection) -> CFDictionary?

    Objective-C

    CFDictionaryRef SCNetworkConnectionCopyExtendedStatus ( SCNetworkConnectionRef connection );

    Parameters

    connection

    The network connection.

    Return Value

    The status dictionary, or NULL if an error occurred (use the SCError function to retrieve the specific error).

    Discussion

    An extended status dictionary contains specific dictionaries describing the status for each subcomponent of the service. For example, a status dictionary contains the following sub-dictionaries, keys, and values:

    Sub-dictionary

    Key

    Value

    IPv4

    Addresses

    The assigned IP address

    PPP

    Status

    The PPP-specific status (see Network Connection PPP Status Values for possible values)

    LastCause

    Available when the status is “Disconnected” and contains the last error associated with connecting or disconnecting.

    ConnectTime

    The time when the connection was established.

    Modem

    ConnectSpeed

    The speed of the modem connection in bits per second.

    Other dictionaries can be present for PPoE, PPTP, and L2TP.

    The status dictionary may be extended in the future to contain additional information.

    Availability

    Available in OS X v10.3 and later.

  • Returns the statistics of the specified connection.

    Declaration

    Swift

    func SCNetworkConnectionCopyStatistics(_ connection: SCNetworkConnection) -> CFDictionary?

    Objective-C

    CFDictionaryRef SCNetworkConnectionCopyStatistics ( SCNetworkConnectionRef connection );

    Parameters

    connection

    The network connection.

    Return Value

    The statistics dictionary, or NULL if an error occurred (use the SCError function to retrieve the specific error).

    Discussion

    A statistics dictionary contains specific dictionaries with statistics for each subcomponent of the service. For example, a statistics dictionary for PPP contains the following sub-dictionaries, keys, and values:

    Sub-dictionary

    Key

    Value

    PPP

    BytesIn

    The number of bytes going up into the network stack for any networking protocol without the PPP headers and trailers.

    PPP

    BytesOut

    The number of bytes coming out of the network stack for any networking protocol without the PPP headers and trailers.

    PPP

    PacketsIn

    The number of packets going up into the network stack for any networking protocol without the PPP headers and trailers.

    PPP

    PacketsOut

    The number of packets coming out of the network stack for any networking protocol without the PPP headers and trailers.

    PPP

    ErrorsIn

    The number of errors going up into the network stack for any networking protocol without the PPP headers and trailers.

    PPP

    ErrorsOut

    The number of errors coming out of the network stack for any networking protocol without the PPP headers and trailers.

    See Statistics Dictionary Keys for the keys to use in the statistics dictionary.

    Availability

    Available in OS X v10.3 and later.

  • Gets the user options used to start the specified connection.

    Declaration

    Swift

    func SCNetworkConnectionCopyUserOptions(_ connection: SCNetworkConnection) -> CFDictionary?

    Objective-C

    CFDictionaryRef SCNetworkConnectionCopyUserOptions ( SCNetworkConnectionRef connection );

    Parameters

    connection

    The network connection.

    Return Value

    The service dictionary containing the connection options (the dictionary can be empty if no user options were used), or NULL if an error occurred (use the SCError function to retrieve the specific error).

    Discussion

    A client can call this function to retrieve the user options previously passed to the SCNetworkConnectionStart function.

    Availability

    Available in OS X v10.3 and later.

  • Starts the connection process for the specified network connection.

    Declaration

    Swift

    func SCNetworkConnectionStart(_ connection: SCNetworkConnection, _ userOptions: CFDictionary?, _ linger: Bool) -> Bool

    Objective-C

    Boolean SCNetworkConnectionStart ( SCNetworkConnectionRef connection, CFDictionaryRef userOptions, Boolean linger );

    Parameters

    connection

    The network connection to start.

    userOptions

    The options with which to start the connection. If userOptions is NULL, the default settings are used. If userOptions are specified, they must be in the same format as network services stored in the system configuration preferences schema. The options override the default settings defined for the service.

    For security reasons, not all options can be overridden; the appropriate merging of all settings is done before the connection is established, and inappropriate options are ignored.

    linger

    A Boolean value indicating whether the connection can persist when the application no longer has interest in it. A typical application should pass FALSE, in which case the connection is automatically stopped when the reference is released or the application quits. If the application passes TRUE, the application can release the reference or exit and the connection is maintained until a timeout event, until a specific stop request occurs, or until an error occurs.

    Return Value

    TRUE if the connection was correctly started (the actual connection is not established yet, and the connection status needs to be periodically checked); FALSE if the connection request was not started (use the SCError function to retrieve the specific error).

    Discussion

    The connection process is asynchronous and this function returns immediately. The connection status can be obtained by polling or by callback. The connection is made with the default settings from the administrator. Some of the settings can be overridden for the duration of the connection. These are specified in an options dictionary. The options dictionary uses the same format as a network service defined in the system configuration preferences schema.

    Availability

    Available in OS X v10.3 and later.

  • Stops the connection process for the specified network connection.

    Declaration

    Swift

    func SCNetworkConnectionStop(_ connection: SCNetworkConnection, _ forceDisconnect: Bool) -> Bool

    Objective-C

    Boolean SCNetworkConnectionStop ( SCNetworkConnectionRef connection, Boolean forceDisconnect );

    Parameters

    connection

    The network connection to stop.

    forceDisconnect

    Pass TRUE to stop the connection regardless of other applications that might have interest in it.

    Return Value

    TRUE if the disconnection request succeeded; FALSE (use the SCError function to retrieve the specific error).

    Availability

    Available in OS X v10.3 and later.

  • Specifies a dispatch queue to use for the connection’s callback function and enables notifications.

    Declaration

    Swift

    func SCNetworkConnectionSetDispatchQueue(_ connection: SCNetworkConnection, _ queue: dispatch_queue_t?) -> Bool

    Objective-C

    Boolean SCNetworkConnectionSetDispatchQueue ( SCNetworkConnectionRef connection, dispatch_queue_t queue );

    Parameters

    connection

    The network connection to notify.

    queue

    The queue on which to run the connection’s callback function. Pass NULL to disable notifications and release the queue.

    Return Value

    TRUE if successful; otherwise, FALSE (use the SCError function to retrieve the specific error).

    Availability

    Available in OS X v10.6 and later.

Data Types

  • The handle to manage a connection-oriented service.

    Declaration

    Swift

    class SCNetworkConnection { }

    Objective-C

    typedef const struct __SCNetworkConnection * SCNetworkConnectionRef;

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.3 and later.

  • The type of callback function used when a status event is delivered.

    Declaration

    Swift

    typealias SCNetworkConnectionCallBack = (SCNetworkConnection, SCNetworkConnectionStatus, UnsafeMutablePointer<Void>) -> Void

    Objective-C

    typedef void (*SCNetworkConnectionCallBack) ( SCNetworkConnectionRef connection, SCNetworkConnectionStatus status, void *info );

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.3 and later.

  • A structure containing user-specified data and callbacks for a network connection.

    Declaration

    Swift

    struct SCNetworkConnectionContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: ((UnsafePointer<Void>) -> UnsafePointer<Void>)? var release: ((UnsafePointer<Void>) -> Void)? var copyDescription: ((UnsafePointer<Void>) -> Unmanaged<CFString>)? init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: ((UnsafePointer<Void>) -> UnsafePointer<Void>)?, release release: ((UnsafePointer<Void>) -> Void)?, copyDescription copyDescription: ((UnsafePointer<Void>) -> Unmanaged<CFString>)?) }

    Objective-C

    typedef struct { CFIndex version; void * info; const void *(*retain)(const void *info); void (*release)(const void *info); CFStringRef (*copyDescription)(const void *info); } SCNetworkConnectionContext;

    Fields

    version

    The version number of the structure type being passed in as a parameter to the SCNetworkConnectionCreateWithServiceID function. This structure is version 0.

    info

    A C pointer to a user-specified block of data.

    retain

    The callback used to add a retain for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL.

    release

    The calllback used to remove a retain previously added for the info field. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The value may be NULL.

    copyDescription

    The callback used to provide a description of the info field.

    Availability

    Available in OS X v10.3 and later.

Constants

  • The current status of the network connection.

    Declaration

    Swift

    enum SCNetworkConnectionStatus : Int32 { case Invalid case Disconnected case Connecting case Connected case Disconnecting }

    Objective-C

    enum { kSCNetworkConnectionInvalid = -1, kSCNetworkConnectionDisconnected = 0, kSCNetworkConnectionConnecting = 1, kSCNetworkConnectionConnected = 2, kSCNetworkConnectionDisconnecting = 3 }; typedef int32_t SCNetworkConnectionStatus;

    Constants

    • Invalid

      kSCNetworkConnectionInvalid

      The network connection refers to an invalid service.

      Available in OS X v10.3 and later.

    • Disconnected

      kSCNetworkConnectionDisconnected

      The network connection is disconnected.

      Available in OS X v10.3 and later.

    • Connecting

      kSCNetworkConnectionConnecting

      The network connection is connecting.

      Available in OS X v10.3 and later.

    • Connected

      kSCNetworkConnectionConnected

      The network connection is connected.

      Available in OS X v10.3 and later.

    • Disconnecting

      kSCNetworkConnectionDisconnecting

      The network connection is disconnecting.

      Available in OS X v10.3 and later.

    Discussion

    This status is intended to be generic and high level. An extended status, specific to the type of network connection, is also available for applications that need additonal information.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.3 and later.

  • The PPP-specific status of the network connection.

    Declaration

    Swift

    enum SCNetworkConnectionPPPStatus : Int32 { case Disconnected case Initializing case ConnectingLink case DialOnTraffic case NegotiatingLink case Authenticating case WaitingForCallBack case NegotiatingNetwork case Connected case Terminating case DisconnectingLink case HoldingLinkOff case Suspended case WaitingForRedial }

    Objective-C

    enum { kSCNetworkConnectionPPPDisconnected = 0, kSCNetworkConnectionPPPInitializing = 1, kSCNetworkConnectionPPPConnectingLink = 2, kSCNetworkConnectionPPPDialOnTraffic = 3, kSCNetworkConnectionPPPNegotiatingLink = 4, kSCNetworkConnectionPPPAuthenticating = 5, kSCNetworkConnectionPPPWaitingForCallBack = 6, kSCNetworkConnectionPPPNegotiatingNetwork = 7, kSCNetworkConnectionPPPConnected = 8, kSCNetworkConnectionPPPTerminating = 9, kSCNetworkConnectionPPPDisconnectingLink = 10, kSCNetworkConnectionPPPHoldingLinkOff = 11, kSCNetworkConnectionPPPSuspended = 12, kSCNetworkConnectionPPPWaitingForRedial = 13 }; typedef int32_t SCNetworkConnectionPPPStatus;

    Constants

    • Disconnected

      kSCNetworkConnectionPPPDisconnected

      PPP is disconnected.

      Available in OS X v10.3 and later.

    • Initializing

      kSCNetworkConnectionPPPInitializing

      PPP is initializing.

      Available in OS X v10.3 and later.

    • ConnectingLink

      kSCNetworkConnectionPPPConnectingLink

      PPP is connecting the lower connection layer (for example, the modem is dialing out).

      Available in OS X v10.3 and later.

    • DialOnTraffic

      kSCNetworkConnectionPPPDialOnTraffic

      PPP is waiting for networking traffic to automatically establish the connection.

      Available in OS X v10.3 and later.

    • NegotiatingLink

      kSCNetworkConnectionPPPNegotiatingLink

      The PPP lower layer is connected and PPP is negotiating the link layer (LCP protocol).

      Available in OS X v10.3 and later.

    • Authenticating

      kSCNetworkConnectionPPPAuthenticating

      PPP is authenticating to the server (PAP, CHAP, MS-CHAP, or EAP protocols).

      Available in OS X v10.3 and later.

    • WaitingForCallBack

      kSCNetworkConnectionPPPWaitingForCallBack

      PPP is waiting for the server to call back.

      Available in OS X v10.3 and later.

    • NegotiatingNetwork

      kSCNetworkConnectionPPPNegotiatingNetwork

      PPP is now authenticated and negotiating the networking layer (IPCP or IPv6CP protocols).

      Available in OS X v10.3 and later.

    • Connected

      kSCNetworkConnectionPPPConnected

      PPP is now fully connected for at least one networking layer. Additional networking protocol might still be negotiating.

      Available in OS X v10.3 and later.

    • Terminating

      kSCNetworkConnectionPPPTerminating

      PPP networking and link protocols are terminating.

      Available in OS X v10.3 and later.

    • DisconnectingLink

      kSCNetworkConnectionPPPDisconnectingLink

      PPP is disconnecting the lower level (for example, the modem is hanging up).

      Available in OS X v10.3 and later.

    • HoldingLinkOff

      kSCNetworkConnectionPPPHoldingLinkOff

      PPP is disconnected and maintaining the link temporarily off.

      Available in OS X v10.3 and later.

    • Suspended

      kSCNetworkConnectionPPPSuspended

      PPP is suspended as a result of the suspend command (for example, when a V.92 Modem is On Hold).

      Available in OS X v10.3 and later.

    • WaitingForRedial

      kSCNetworkConnectionPPPWaitingForRedial

      PPP has found a busy server and is waiting for redial.

      Available in OS X v10.3 and later.

    Discussion

    This status is returned as part of the extended information for a PPP service. Note that additional status might be returned in the future. Therefore, your application should be prepared to receive an unknown value.

    Import Statement

    Objective-C

    @import SystemConfiguration;

    Swift

    import SystemConfiguration

    Availability

    Available in OS X v10.3 and later.

  • Keys associated with values in the statistics dictionary.

    Declaration

    Swift

    var kSCNetworkConnectionBytesIn: String { get } var kSCNetworkConnectionBytesOut: String { get } var kSCNetworkConnectionPacketsIn: String { get } var kSCNetworkConnectionPacketsOut: String { get } var kSCNetworkConnectionErrorsIn: String { get } var kSCNetworkConnectionErrorsOut: String { get }

    Objective-C

    #define kSCNetworkConnectionBytesIn CFSTR("BytesIn") #define kSCNetworkConnectionBytesOut CFSTR("BytesOut") #define kSCNetworkConnectionPacketsIn CFSTR("PacketsIn") #define kSCNetworkConnectionPacketsOut CFSTR("PacketsOut") #define kSCNetworkConnectionErrorsIn CFSTR("ErrorsIn") #define kSCNetworkConnectionErrorsOut CFSTR("ErrorsOut")

    Constants

    • kSCNetworkConnectionBytesIn

      kSCNetworkConnectionBytesIn

      The key associated with the number of bytes going up into the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

    • kSCNetworkConnectionBytesOut

      kSCNetworkConnectionBytesOut

      The key associated with the number of bytes coming out of the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

    • kSCNetworkConnectionPacketsIn

      kSCNetworkConnectionPacketsIn

      The key associated with the number of packets going up into the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

    • kSCNetworkConnectionPacketsOut

      kSCNetworkConnectionPacketsOut

      The key associated with the number of packets coming out of the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

    • kSCNetworkConnectionErrorsIn

      kSCNetworkConnectionErrorsIn

      The key associated with the number of errors going up into the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

    • kSCNetworkConnectionErrorsOut

      kSCNetworkConnectionErrorsOut

      The key associated with the number of errors coming out of the network stack for any networking protocol without the PPP headers and trailers.

      Available in OS X v10.3 and later.

  • Keys used with the SCNetworkConnectionCopyUserPreferences selection options dictionary.

    Declaration

    Swift

    var kSCNetworkConnectionSelectionOptionOnDemandHostName: String { get } var kSCNetworkConnectionSelectionOptionOnDemandRetry: String { get }

    Objective-C

    #define kSCNetworkConnectionSelectionOptionOnDemandHostName CFSTR("OnDemandHostName") #define kSCNetworkConnectionSelectionOptionOnDemandRetry CFSTR("OnDemandRetry")

    Constants

    • kSCNetworkConnectionSelectionOptionOnDemandHostName

      kSCNetworkConnectionSelectionOptionOnDemandHostName

      The key associated with a host name used to select the "best" network connection.

      Available in OS X v10.6 and later.

    • kSCNetworkConnectionSelectionOptionOnDemandRetry

      kSCNetworkConnectionSelectionOptionOnDemandRetry

      The key associated with a Boolean value used to indicate whether a DNS query has already been issued for the specified on-demand host name.

      Available in OS X v10.6 and later.