SCNetworkConnection Reference

Framework	SystemConfiguration
Declared in	SCNetworkConnection.h

Overview

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 by Task

Getting Connection-Status Information

Starting and Stopping a Connection

Scheduling a Connection Reference on a Run Loop

Creating a Connection Reference

Specifying a Dispatch Queue and Enabling Notifications

Functions

SCNetworkConnectionCopyExtendedStatus

Returns the extended status of the connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCopyServiceID

Returns the service ID associated with the specified network connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCopyStatistics

Returns the statistics of the specified connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCopyUserOptions

Gets the user options used to start the specified connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCopyUserPreferences

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

Boolean SCNetworkConnectionCopyUserPreferences (
   CFDictionaryRef selectionOptions,
   CFStringRef *serviceID,
   CFDictionaryRef *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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCreateWithServiceID

Creates a new connection reference to use for getting the status or for connecting or disconnecting the associated service.

SCNetworkConnectionRef SCNetworkConnectionCreateWithServiceID (
   CFAllocatorRef allocator,
   CFStringRef serviceID,
   SCNetworkConnectionCallBack callout,
   SCNetworkConnectionContext *context
);

Parameters

allocator: The allocator that should be used to allocate memory for the connection structure. This parameter may be NULL, in which case the current default allocator is used. If this reference is not a valid allocator, the behavior is undefined.
serviceID: The service identifier of the connection. This value uniquely identifies service in the system configuration database.
callout: The function to be called when the status of the connection changes. If this parameter is NULL, the application receives notifications of status change and will need to poll for updates.
context: User-specified data associated with the connection.

Return Value

A reference to a new network connection.

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

SCNetworkConnectionGetStatus

Returns the status of the specified network connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionGetTypeID

Returns the type identifier of all SCNetworkConnection instances.

CFTypeID SCNetworkConnectionGetTypeID (
   void
);

Return Value

The type identifier of all SCNetworkConnection instances.

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

SCNetworkConnectionScheduleWithRunLoop

Schedules the specified connection with the specified run loop.

Boolean SCNetworkConnectionScheduleWithRunLoop (
   SCNetworkConnectionRef connection,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

Parameters

connection: The network connection to schedule.
runLoop: The run loop with which to schedule the network connection.
runLoopMode: The run loop mode.

Return Value

TRUE if the connection is scheduled successfully; FALSE (use the SCError function to retrieve the specific error).

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

SCNetworkConnectionSetDispatchQueue

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

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionStart

Starts the connection process for the specified network connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionStop

Stops the connection process for the specified network connection.

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.

Declared In

SCNetworkConnection.h

SCNetworkConnectionUnscheduleFromRunLoop

Unschedules the specified connection from the specified run loop.

Boolean SCNetworkConnectionUnscheduleFromRunLoop (
   SCNetworkConnectionRef connection,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode
);

Parameters

connection: The network connection to unschedule.
runLoop: The run loop from which to unschedule the network connection.
runLoopMode: The run loop mode.

Return Value

TRUE if the connection is unscheduled successfully; FALSE (use the SCError function to retrieve the specific error).

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

Data Types

SCNetworkConnectionRef

The handle to manage a connection-oriented service.

typedef const struct __SCNetworkConnection * SCNetworkConnectionRef;

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

SCNetworkConnectionCallBack

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

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

Fields

connection: The network connection.
status: The connection status.
info: Application-specific information.

Availability

Available in OS X v10.3 and later.

Declared In

SCNetworkConnection.h

SCNetworkConnectionContext

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

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.

Declared In

SCNetworkConnection.h

Constants

Network Connection Status Values

The current status of the network connection.

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

Constants

kSCNetworkConnectionInvalid

The network connection refers to an invalid service.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionDisconnected

The network connection is disconnected.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionConnecting

The network connection is connecting.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionConnected

The network connection is connected.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionDisconnecting

The network connection is disconnecting.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

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.

Network Connection PPP Status Values

The PPP-specific status of the network connection.

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

kSCNetworkConnectionPPPDisconnected

PPP is disconnected.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPInitializing

PPP is initializing.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPConnectingLink

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPDialOnTraffic

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPNegotiatingLink

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPAuthenticating

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPWaitingForCallBack

PPP is waiting for the server to call back.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPNegotiatingNetwork

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPTerminating

PPP networking and link protocols are terminating.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPDisconnectingLink

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPHoldingLinkOff

PPP is disconnected and maintaining the link temporarily off.

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

kSCNetworkConnectionPPPWaitingForRedial

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

Available in OS X v10.3 and later.

Declared in SCNetworkConnection.h.

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.

Statistics Dictionary Keys

Keys associated with values in the statistics dictionary.

#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

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.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

Selection Options Dictionary Keys

Keys used with the SCNetworkConnectionCopyUserPreferences selection options dictionary.

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

Constants

kSCNetworkConnectionSelectionOptionOnDemandHostName

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

Available in OS X v10.6 and later.

Declared in SCNetworkConnection.h.

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.

Declared in SCNetworkConnection.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.