X-Git-Url: https://git.saurik.com/apple/configd.git/blobdiff_plain/32d96e3d77d900203b7faba2d7937f8b3472f4d7..009ee3c6fe2929a4c90ae5c9eb1925573e17956b:/SystemConfiguration.fproj/SCNetworkConnection.h?ds=sidebyside diff --git a/SystemConfiguration.fproj/SCNetworkConnection.h b/SystemConfiguration.fproj/SCNetworkConnection.h new file mode 100644 index 0000000..53357bc --- /dev/null +++ b/SystemConfiguration.fproj/SCNetworkConnection.h @@ -0,0 +1,477 @@ +/* + * Copyright (c) 2002-2003 Apple Computer, Inc. All rights reserved. + * + * @APPLE_LICENSE_HEADER_START@ + * + * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved. + * + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this + * file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, + * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. + * + * @APPLE_LICENSE_HEADER_END@ + */ + +#ifndef _SCNETWORKCONNECTION_H +#define _SCNETWORKCONNECTION_H + +#include +#include +#include +#include +#include +#include + + +/*! + @header SCNetworkConnection + The SCNetworkConnectionXXX() APIs allow an application to + control connection oriented services defined in the system. + + This is a set of control APIs only. Using these APIs, an + application will be able to control existing services. + To create, change, or remove services, SCPreferences APIs + must be used. + + Note: Currently only PPP services can be controlled. + */ + + +/*! + @typedef SCNetworkConnectionRef + @discussion This is the handle to manage a connection oriented service. + */ +typedef const struct __SCNetworkConnection * SCNetworkConnectionRef AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @typedef SCNetworkConnectionContext + */ +typedef struct { + CFIndex version; + void * info; + const void *(*retain)(const void *info); + void (*release)(const void *info); + CFStringRef (*copyDescription)(const void *info); +} SCNetworkConnectionContext AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + + +/*! + @enum SCNetworkConnectionStatus + @discussion Status of the network connection. + 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. + + @constant kSCNetworkConnectionInvalid + The network connection refers to an invalid service. + + @constant kSCNetworkConnectionDisconnected + The network connection is disconnected. + + @constant kSCNetworkConnectionConnecting + The network connection is connecting. + + @constant kSCNetworkConnectionConnected + The network connection is connected. + + @constant kSCNetworkConnectionDisconnecting + The network connection is disconnecting. + */ +enum { + kSCNetworkConnectionInvalid = -1, + kSCNetworkConnectionDisconnected = 0, + kSCNetworkConnectionConnecting = 1, + kSCNetworkConnectionConnected = 2, + kSCNetworkConnectionDisconnecting = 3 +}; +typedef int32_t SCNetworkConnectionStatus AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @enum SCNetworkConnectionPPPStatus + @discussion PPP specific status of the network connection. + This status is PPP specific and returned as part of the extended information + for a PPP service. + Note: additional status might be returned in the future, and the application should + be prepared to receive an unknown value. + + @constant kSCNetworkConnectionPPPDisconnected + PPP is disconnected. + + @constant kSCNetworkConnectionPPPInitializing + PPP is initializing. + + @constant kSCNetworkConnectionPPPConnectingLink + PPP is connecting the lower connection layer (for example, the modem is dialing out). + + @constant kSCNetworkConnectionPPPDialOnTraffic + PPP is waiting for networking traffic to automatically establish the connection. + + @constant kSCNetworkConnectionPPPNegotiatingLink + PPP lower layer is connected and PPP is negotiating the link layer (LCP protocol). + + @constant kSCNetworkConnectionPPPAuthenticating + PPP is authenticating to the server (PAP, CHAP, MS-CHAP or EAP protocols). + + @constant kSCNetworkConnectionPPPWaitingForCallBack + PPP is waiting for server to call back. + + @constant kSCNetworkConnectionPPPNegotiatingNetwork + PPP is now authenticated and negotiating the networking layer (IPCP or IPv6CP protocols) + + @constant kSCNetworkConnectionPPPConnected + PPP is now fully connected for at least one of the networking layer. + Additional networking protocol might still be negotiating. + + @constant kSCNetworkConnectionPPPTerminating + PPP networking and link protocols are terminating. + + @constant kSCNetworkConnectionPPPDisconnectingLink + PPP is disconnecting the lower level (for example, the modem is hanging up). + + @constant kSCNetworkConnectionPPPHoldingLinkOff + PPP is disconnected and maintaining the link temporarily off. + + @constant kSCNetworkConnectionPPPSuspended + PPP is suspended as a result of the suspend command (for example, when a V92 Modem is On Hold). + + @constant kSCNetworkConnectionPPPWaitingForRedial + PPP has found a busy server and is waiting for redial. + */ +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 AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @typedef SCNetworkConnectionCallBack + @discussion Type of the callback function used when a + status event is delivered. + @param status The connection status. + @param connection The connection reference. + @param info .... + */ +typedef void (*SCNetworkConnectionCallBack) ( + SCNetworkConnectionRef connection, + SCNetworkConnectionStatus status, + void *info + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + + +/* + Keys for the statistics dictionary +*/ + +#define kSCNetworkConnectionBytesIn CFSTR("BytesIn") /* CFNumber */ +#define kSCNetworkConnectionBytesOut CFSTR("BytesOut") /* CFNumber */ +#define kSCNetworkConnectionPacketsIn CFSTR("PacketsIn") /* CFNumber */ +#define kSCNetworkConnectionPacketsOut CFSTR("PacketsOut") /* CFNumber */ +#define kSCNetworkConnectionErrorsIn CFSTR("ErrorsIn") /* CFNumber */ +#define kSCNetworkConnectionErrorsOut CFSTR("ErrorsOut") /* CFNumber */ + + +__BEGIN_DECLS + +/*! + @function SCDynamicStoreGetTypeID + Returns the type identifier of all SCNetworkConnection instances. + */ +CF_EXPORT +CFTypeID SCNetworkConnectionGetTypeID (void) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCopyUserPreferences + @discussion Provides the default serviceID and a userOptions dictionary for the connection. + Applications can use the serviceID and userOptions returned to open a connection on the fly. + @param selectionOptions Currently unimplemented. Pass NULL for this version. + @param serviceID Reference to the default serviceID for starting connections, + this value will be returned by the function. + @param userOptions Reference to default userOptions for starting connections, + this will be returned by the function. + @result TRUE if there is a valid service to dial. + FALSE if function was unable to retrieve a service to dial. + */ +Boolean SCNetworkConnectionCopyUserPreferences ( + CFDictionaryRef selectionOptions, + CFStringRef *serviceID, + CFDictionaryRef *userOptions + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCreateWithServiceID + @discussion Creates a new connection reference to use for getting the status, + for connecting or for disconnecting the associated service. + @param allocator The CFAllocator which should be used to allocate + memory for the connection structure. + This parameter may be NULL in which case the current + default CFAllocator is used. If this reference is not + a valid CFAllocator, the behavior is undefined. + @param serviceID A string that defines the service identifier + of the connection. Service identifiers uniquely identify + services in the system configuration database. + @param callout The function to be called when the status + of the connection changes. + If this parameter is NULL, the application will not receive + change of status notifications and will need to poll for updates. + @param context The SCNetworkConnectionContext associated with the callout. + @result A reference to the new SCNetworkConnection. + */ +SCNetworkConnectionRef +SCNetworkConnectionCreateWithServiceID ( + CFAllocatorRef allocator, + CFStringRef serviceID, + SCNetworkConnectionCallBack callout, + SCNetworkConnectionContext *context + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCopyService + @discussion Returns the service ID associated with the SCNetworkConnection. + @param connection The SCNetworkConnection to obtained status from. + Returns the service ID associated with the SCNetworkConnection. + */ +CFStringRef +SCNetworkConnectionCopyServiceID ( + SCNetworkConnectionRef connection + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionGetStatus + @discussion Returns the status of the SCNetworkConnection. + A status is one of the following values : + kSCNetworkConnectionInvalid + kSCNetworkConnectionDisconnected + kSCNetworkConnectionConnecting + kSCNetworkConnectionDisconnecting + kSCNetworkConnectionConnected + + @param connection The SCNetworkConnection to obtain status from. + @result The status value. +*/ +SCNetworkConnectionStatus +SCNetworkConnectionGetStatus ( + SCNetworkConnectionRef connection + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCopyExtendedStatus + @discussion Returns the extended status of the connection. + An extended status dictionary contains specific dictionaries + describing the status for each subcomponent of the service. + + For example, a status dictionary will contain the following dictionaries: + + IPv4: + IPaddress: IP address used. + + PPP: + Status: PPP specific status of type SCNetworkConnectionPPPStatus. + LastCause: Available when status is Disconnected. + Contains the last error of disconnection. + ConnectTime: time when the connection happened + MaxTime: maximum time for this connection + + Modem: + ConnectionSpeed: Speed of the modem connection in bits/s + + Other dictionaries could be present for PPPoE, PPTP and L2TP. + + The status dictionary can be extended as needed in the future + to contain additional information. + + @param connection The SCNetworkConnection to obtain status from. + @result The status dictionary. + If NULL is returned, the error can be retrieved with SCError(). + */ +CFDictionaryRef +SCNetworkConnectionCopyExtendedStatus ( + SCNetworkConnectionRef connection + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCopyStatistics + @discussion Returns the statistics of the SCNetworkConnection. + A statistic dictionary contains specific dictionaries + with statistics for each subcomponents of the service. + + For example, a statistic dictionary will contain the following dictionaries: + + PPP: {Bytes,Packets,Errors}{In,Out}: + Statistics at the Network level. + Contains the number of bytes, packets, and errors on the PPP interface. + For example, BytesIn contains the number of bytes going up + into the network stack, for any networking protocol, + without the PPP headers and trailers. + + The statistic dictionary can be extended as needed in the future + to contain additional information. + + @param connection The SCNetworkConnection to obtained statistics from. + @result The statistics dictionary. + If NULL is returned, the error can be retrieved with SCError(). + */ +CFDictionaryRef +SCNetworkConnectionCopyStatistics ( + SCNetworkConnectionRef connection + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionStart + @discussion Start the connection for the SCNetworkConnection. + The connection process is asynchronous and the function will + return immediately. The connection status can be obtain by polling or + by callback. + The connection is done with the default settings from the administrator. + Some of the settings can be overridden for the duration of + the connection. They are given in an option dictionary. + The options dictionary is in the format of a Network Service + as described in SystemConfiguration. + + Note: Starting and stopping of connections is implicitely arbitrated. + Calling Start on a connection already started will indicate + that the application has interest in the connection and it shouldn't + be stopped by anyone else. + + @param connection The SCNetworkConnection to start. + @param userOptions The options dictionary to start the connection with. + If userOptions is NULL, the default settings will be used. + If userOptions are specified, they must be in the SystemConfiguration format. + The options will override the default settings defined for the service. + + For security reasons, not all the options can be overridden, the appropriate merging + of all the settings will be done before the connection is established, + and inappropriate options will be ignored. + + @param linger This parameter indicates whether or not the connection can stay around + when the application no longer has interest in it. + Typical application should pass FALSE, and the Stop function will + automatically be called when the reference is released or if the application quits. + If the application passes TRUE, the application can release the reference + or exit and the Stop function will not be called. + + @result 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 didn't start. Error must be taken + from SCError(). + */ +Boolean +SCNetworkConnectionStart ( + SCNetworkConnectionRef connection, + CFDictionaryRef userOptions, + Boolean linger + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionStop + @discussion Stop the connection for the SCNetworkConnection. + The disconnection process is asynchronous and the function will + return immediately. The connection status can be obtain by polling or + by callback. + This function performs an arbitrated stop of the connection. + If several applications have marked their interest in the connection, + by calling SCNetworkConnectionStart, the call will succeed but the the actual + connection will be maintained until the last interested application calls stop. + + In certain cases, you might want to stop the connection anyway, and + SCNetworkConnectionStop with forceDisconnect argument can be used. + + @param connection The SCNetworkConnection to stop. + @result TRUE if the disconnection request succeeded. + FALSE if the disconnection request failed. Error must be taken from SCError(). + */ +Boolean +SCNetworkConnectionStop ( + SCNetworkConnectionRef connection, + Boolean forceDisconnect + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionCopyCurrentOptions + @discussion Copy the user options used to start the connection. + This is a mechanism for a client to retrieve the user options + previously passed to the SCNetworkConnectionStart function. + @param connection The SCNetworkConnection to obtain options from. + @result The service dictionary containing the connection options. + The dictionary can be empty if no user options were used. + If NULL is returned, the error can be retrieved with SCError(). + */ +CFDictionaryRef +SCNetworkConnectionCopyUserOptions ( + SCNetworkConnectionRef connection + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionScheduleWithRunLoop + @discussion Schedule a connection with the Run Loop. + @param connection The SCNetworkConnection to schedule. + @param runLoop The runloop to schedule with. + @param runLoopMode The runloop mode. + @result TRUE if success. + FALSE if failed. The error can be retrieved with SCError(). + */ +Boolean +SCNetworkConnectionScheduleWithRunLoop ( + SCNetworkConnectionRef connection, + CFRunLoopRef runLoop, + CFStringRef runLoopMode + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + + +/*! + @function SCNetworkConnectionUnscheduleFromRunLoop + @discussion Unschedule a connection from the Run Loop. + @param connection The SCNetworkConnection to unschedule. + @param runLoop The runloop to unschedule from. + @param runLoopMode The runloop mode. + @result TRUE if success. + FALSE if failed. The error can be retrieved with SCError(). + */ +Boolean +SCNetworkConnectionUnscheduleFromRunLoop ( + SCNetworkConnectionRef connection, + CFRunLoopRef runLoop, + CFStringRef runLoopMode + ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; + +__END_DECLS + +#endif /* _SCNETWORKCONNECTION_H */