1/* 2 * Copyright (c) 2003-2006, 2008-2010 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24#ifndef _SCNETWORKCONNECTION_H 25#ifdef USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS 26#include <SystemConfiguration/_SCNetworkConnection.h> 27#else /* USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS */ 28#define _SCNETWORKCONNECTION_H 29 30#include <Availability.h> 31#include <TargetConditionals.h> 32#include <sys/cdefs.h> 33#include <dispatch/dispatch.h> 34#include <sys/types.h> 35#include <sys/socket.h> 36#include <CoreFoundation/CoreFoundation.h> 37#include <SystemConfiguration/SystemConfiguration.h> 38 39 40/*! 41 @header SCNetworkConnection 42 @discussion The SCNetworkConnection API contains functions that allow 43 an application to control connection-oriented services defined 44 in the system and get connection-status information. 45 46 The functions in the SCNetworkConnection API allow you to 47 control and get information about existing services only. 48 If you need to create, change, or remove services, you 49 should use the SCNetworkConfiguration API instead. 50 51 Note: Currently, only PPP services can be controlled. 52 */ 53 54 55/*! 56 @typedef SCNetworkConnectionRef 57 @discussion This is the handle to manage a connection-oriented service. 58 */ 59typedef const struct __SCNetworkConnection * SCNetworkConnectionRef; 60 61 62/*! 63 @typedef SCNetworkConnectionContext 64 @discussion Structure containing user-specified data and callbacks 65 for a SCNetworkConnection. 66 @field version The version number of the structure type being passed 67 in as a parameter to the SCNetworkConnectionCreateWithServiceID 68 function. This structure is version 0. 69 @field info A C pointer to a user-specified block of data. 70 @field retain The callback used to add a retain for the info field. 71 If this parameter is not a pointer to a function of the correct 72 prototype, the behavior is undefined. The value may be NULL. 73 @field release The calllback used to remove a retain previously added 74 for the info field. If this parameter is not a pointer to a 75 function of the correct prototype, the behavior is undefined. 76 The value may be NULL. 77 @field copyDescription The callback used to provide a description of 78 the info field. 79 */ 80typedef struct { 81 CFIndex version; 82 void * info; 83 const void *(*retain)(const void *info); 84 void (*release)(const void *info); 85 CFStringRef (*copyDescription)(const void *info); 86} SCNetworkConnectionContext; 87 88 89 90/*! 91 @enum SCNetworkConnectionStatus 92 @discussion Status of the network connection. 93 This status is intended to be generic and high level. 94 An extended status, specific to the type of network 95 connection is also available for applications that 96 need additonal information. 97 @constant kSCNetworkConnectionInvalid 98 The network connection refers to an invalid service. 99 @constant kSCNetworkConnectionDisconnected 100 The network connection is disconnected. 101 @constant kSCNetworkConnectionConnecting 102 The network connection is connecting. 103 @constant kSCNetworkConnectionConnected 104 The network connection is connected. 105 @constant kSCNetworkConnectionDisconnecting 106 The network connection is disconnecting. 107 */ 108enum { 109 kSCNetworkConnectionInvalid = -1, 110 kSCNetworkConnectionDisconnected = 0, 111 kSCNetworkConnectionConnecting = 1, 112 kSCNetworkConnectionConnected = 2, 113 kSCNetworkConnectionDisconnecting = 3 114}; 115typedef int32_t SCNetworkConnectionStatus; 116 117 118/*! 119 @enum SCNetworkConnectionPPPStatus 120 @discussion PPP-specific status of the network connection. 121 This status is returned as part of the extended information 122 for a PPP service. 123 Note: additional status might be returned in the future. 124 Your application should be prepared to receive an unknown value. 125 @constant kSCNetworkConnectionPPPDisconnected 126 PPP is disconnected. 127 @constant kSCNetworkConnectionPPPInitializing 128 PPP is initializing. 129 @constant kSCNetworkConnectionPPPConnectingLink 130 PPP is connecting the lower connection layer (for example, 131 the modem is dialing out). 132 @constant kSCNetworkConnectionPPPDialOnTraffic 133 PPP is waiting for networking traffic to automatically 134 establish the connection. 135 @constant kSCNetworkConnectionPPPNegotiatingLink 136 The PPP lower layer is connected and PPP is negotiating the 137 link layer (LCP protocol). 138 @constant kSCNetworkConnectionPPPAuthenticating 139 PPP is authenticating to the server (PAP, CHAP, MS-CHAP or 140 EAP protocols). 141 @constant kSCNetworkConnectionPPPWaitingForCallBack 142 PPP is waiting for the server to call back. 143 @constant kSCNetworkConnectionPPPNegotiatingNetwork 144 PPP is now authenticated and negotiating the networking 145 layer (IPCP or IPv6CP protocols) 146 @constant kSCNetworkConnectionPPPConnected 147 PPP is now fully connected for at least one networking layer. 148 Additional networking protocol might still be negotiating. 149 @constant kSCNetworkConnectionPPPTerminating 150 PPP networking and link protocols are terminating. 151 @constant kSCNetworkConnectionPPPDisconnectingLink 152 PPP is disconnecting the lower level (for example, the modem 153 is hanging up). 154 @constant kSCNetworkConnectionPPPHoldingLinkOff 155 PPP is disconnected and maintaining the link temporarily off. 156 @constant kSCNetworkConnectionPPPSuspended 157 PPP is suspended as a result of the suspend command (for 158 example, when a V.92 Modem is On Hold). 159 @constant kSCNetworkConnectionPPPWaitingForRedial 160 PPP has found a busy server and is waiting for redial. 161 */ 162enum { 163 kSCNetworkConnectionPPPDisconnected = 0, 164 kSCNetworkConnectionPPPInitializing = 1, 165 kSCNetworkConnectionPPPConnectingLink = 2, 166 kSCNetworkConnectionPPPDialOnTraffic = 3, 167 kSCNetworkConnectionPPPNegotiatingLink = 4, 168 kSCNetworkConnectionPPPAuthenticating = 5, 169 kSCNetworkConnectionPPPWaitingForCallBack = 6, 170 kSCNetworkConnectionPPPNegotiatingNetwork = 7, 171 kSCNetworkConnectionPPPConnected = 8, 172 kSCNetworkConnectionPPPTerminating = 9, 173 kSCNetworkConnectionPPPDisconnectingLink = 10, 174 kSCNetworkConnectionPPPHoldingLinkOff = 11, 175 kSCNetworkConnectionPPPSuspended = 12, 176 kSCNetworkConnectionPPPWaitingForRedial = 13 177}; 178typedef int32_t SCNetworkConnectionPPPStatus; 179 180 181/*! 182 @typedef SCNetworkConnectionCallBack 183 @discussion Type of the callback function used when a 184 status event is delivered. 185 @param status The connection status. 186 @param connection The connection reference. 187 @param info Application-specific information. 188 */ 189typedef void (*SCNetworkConnectionCallBack) ( 190 SCNetworkConnectionRef connection, 191 SCNetworkConnectionStatus status, 192 void *info 193 ); 194 195 196 197/* 198 Keys for the statistics dictionary 199*/ 200 201#define kSCNetworkConnectionBytesIn CFSTR("BytesIn") /* CFNumber */ 202#define kSCNetworkConnectionBytesOut CFSTR("BytesOut") /* CFNumber */ 203#define kSCNetworkConnectionPacketsIn CFSTR("PacketsIn") /* CFNumber */ 204#define kSCNetworkConnectionPacketsOut CFSTR("PacketsOut") /* CFNumber */ 205#define kSCNetworkConnectionErrorsIn CFSTR("ErrorsIn") /* CFNumber */ 206#define kSCNetworkConnectionErrorsOut CFSTR("ErrorsOut") /* CFNumber */ 207 208 209/* 210 Keys for the SCNetworkConnectionCopyUserPreferences() "selectionOptions" 211 dictionary 212 */ 213 214/*! 215 @define kSCNetworkConnectionSelectionOptionOnDemandHostName 216 @discussion A host name that will be used to select the 217 "best" SCNetworkConnection. 218 */ 219#define kSCNetworkConnectionSelectionOptionOnDemandHostName CFSTR("OnDemandHostName") // CFString 220 // __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_3_0/*SPI*/) 221 222/*! 223 @define kSCNetworkConnectionSelectionOptionOnDemandRetry 224 @discussion A boolean value used to indicate whether a DNS query has 225 already been issued for the specified OnDemand host name. 226 */ 227#define kSCNetworkConnectionSelectionOptionOnDemandRetry CFSTR("OnDemandRetry") // CFBoolean 228 // __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_3_0/*SPI*/) 229 230__BEGIN_DECLS 231 232/*! 233 @function SCNetworkConnectionGetTypeID 234 @discussion Returns the type identifier of all SCNetworkConnection 235 instances. 236 */ 237CFTypeID 238SCNetworkConnectionGetTypeID (void) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 239 240 241/*! 242 @function SCNetworkConnectionCopyUserPreferences 243 @discussion Provides the default service ID and a dictionary of user 244 options for the connection. Applications can use the 245 returned serviceID and userOptions values to open a 246 connection on the fly. 247 @param selectionOptions Currently unimplemented. Pass NULL for this 248 version. 249 @param serviceID Reference to the default serviceID for starting 250 connections, this value will be returned by the function. 251 @param userOptions Reference to default userOptions for starting 252 connections, this will be returned by the function. 253 @result Returns TRUE if there is a valid service to dial; 254 FALSE if the function was unable to retrieve a service to dial. 255 */ 256Boolean 257SCNetworkConnectionCopyUserPreferences ( 258 CFDictionaryRef selectionOptions, 259 CFStringRef *serviceID, 260 CFDictionaryRef *userOptions 261 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 262 263 264/*! 265 @function SCNetworkConnectionCreateWithServiceID 266 @discussion Creates a new connection reference to use for getting 267 the status or for connecting or disconnecting the associated 268 service. 269 @param allocator The CFAllocator that should be used to allocate 270 memory for the connection structure. This parameter may be 271 NULL in which case the current default CFAllocator is used. 272 If this reference is not a valid CFAllocator, the behavior 273 is undefined. 274 @param serviceID A string that defines the service identifier 275 of the connection. Service identifiers uniquely identify 276 services in the system configuration database. 277 @param callout The function to be called when the status 278 of the connection changes. If this parameter is NULL, the 279 application will not receive notifications of status change 280 and will need to poll for updates. 281 @param context The SCNetworkConnectionContext associated with the 282 callout. 283 @result Returns a reference to the new SCNetworkConnection. 284 */ 285SCNetworkConnectionRef 286SCNetworkConnectionCreateWithServiceID ( 287 CFAllocatorRef allocator, 288 CFStringRef serviceID, 289 SCNetworkConnectionCallBack callout, 290 SCNetworkConnectionContext *context 291 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 292 293 294/*! 295 @function SCNetworkConnectionCopyServiceID 296 @discussion Returns the service ID associated with the SCNetworkConnection. 297 @param connection The SCNetworkConnection to obtain status from. 298 @result Returns the service ID associated with the SCNetworkConnection. 299 */ 300CFStringRef 301SCNetworkConnectionCopyServiceID ( 302 SCNetworkConnectionRef connection 303 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 304 305 306/*! 307 @function SCNetworkConnectionGetStatus 308 @discussion Returns the status of the SCNetworkConnection. 309 A status is one of the following values: 310<pre> 311@textblock 312  313 kSCNetworkConnectionInvalid 314 kSCNetworkConnectionDisconnected 315 kSCNetworkConnectionConnecting 316 kSCNetworkConnectionDisconnecting 317 kSCNetworkConnectionConnected 318@/textblock 319</pre> 320 @param connection The SCNetworkConnection to obtain status from. 321 @result Returns the status value. 322*/ 323SCNetworkConnectionStatus 324SCNetworkConnectionGetStatus ( 325 SCNetworkConnectionRef connection 326 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 327 328 329/*! 330 @function SCNetworkConnectionCopyExtendedStatus 331 @discussion Returns the extended status of the connection. 332 An extended status dictionary contains specific dictionaries 333 describing the status for each subcomponent of the service. 334 335 For example, a status dictionary will contain the following 336 sub-dictionaries, keys, and values: 337<pre> 338@textblock 339  340 IPv4 : Addresses : the assigned IP address. 341  342 PPP : Status : the PPP-specific status of type 343 SCNetworkConnectionPPPStatus. 344  345 LastCause : Available when the status is "Disconnected" 346 and contains the last error associated with 347 connecting or disconnecting. 348  349 ConnectTime : the time when the connection was 350 established. 351  352 Modem : ConnectSpeed : the speed of the modem connection 353 in bits/second. 354  355 IPSec : Status : the IPSec-specific status of type 356 SCNetworkConnectionIPSecStatus 357  358 ConnectTime : the time when the connection was 359 established. 360 361@/textblock 362</pre> 363 Other dictionaries could be present for PPPoE, PPTP, and L2TP. 364 365 The status dictionary may be extended in the future to contain 366 additional information. 367 @param connection The SCNetworkConnection to obtain status from. 368 @result Returns the status dictionary. 369 If NULL is returned, the error can be retrieved using the SCError function. 370 */ 371CFDictionaryRef 372SCNetworkConnectionCopyExtendedStatus ( 373 SCNetworkConnectionRef connection 374 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 375 376 377/*! 378 @function SCNetworkConnectionCopyStatistics 379 @discussion Returns the statistics of the SCNetworkConnection. 380 A statistic dictionary contains specific dictionaries 381 with statistics for each subcomponent of the service. 382 383 For example, a statistics dictionary will contain the following 384 sub-dictionaries, keys, and values: 385<pre> 386@textblock 387  388 PPP : BytesIn : 389 PPP : BytesOut : Contains the number of bytes going up into 390 (or coming out of) the network stack for 391 any networking protocol without the PPP 392 headers and trailers. 393  394 PPP : PacketsIn : 395 PPP : PacketsOut : Contains the number of packets going up into 396 (or coming out of) the network stack for 397 any networking protocol without the PPP 398 headers and trailers. 399  400 PPP : ErrorsIn : 401 PPP : ErrorsOut : Contains the number of errors going up into 402 (or coming out of) the network stack for 403 any networking protocol without the PPP 404 headers and trailers. 405@/textblock 406</pre> 407 The statistics dictionary may be extended in the future to 408 contain additional information. 409 @param connection The SCNetworkConnection to obtained statistics from. 410 @result Returns the statistics dictionary. 411 If NULL is returned, the error can be retrieved using the SCError function. 412 */ 413CFDictionaryRef 414SCNetworkConnectionCopyStatistics ( 415 SCNetworkConnectionRef connection 416 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 417 418 419/*! 420 @function SCNetworkConnectionStart 421 @discussion Starts the connection for the SCNetworkConnection. 422 The connection process is asynchronous and the function will 423 return immediately. The connection status can be obtained 424 by polling or by callback. The connection is made with the 425 default settings from the administrator. Some of the settings 426 can be overridden for the duration of the connection. These 427 are specified in an options dictionary. The options dictionary 428 uses the same format as a network service defined in the system 429 configuration preferences schema. 430 431 Note: Starting and stopping of connections is implicitly 432 arbitrated. Calling SCNetworkConnectionStart on a connection 433 already started will indicate that the application has 434 interest in the connection and it shouldn't be stopped by 435 anyone else. 436 @param connection The SCNetworkConnection to start. 437 @param userOptions The options dictionary to start the connection with. 438 If userOptions is NULL, the default settings will be used. 439 If userOptions are specified, they must be in the same format 440 as network services stored in the system configuration 441 preferences schema. The options will override the default 442 settings defined for the service. 443 444 For security reasons, not all options can be overridden; the 445 appropriate merging of all settings will be done before the 446 connection is established, and inappropriate options will be 447 ignored. 448 @param linger This parameter indicates whether or not the connection 449 can stay around when the application no longer has interest 450 in it. A typical application should pass FALSE, and the 451 connection will be automatically stopped when the reference 452 is released or if the application quits. If the application 453 passes TRUE, the application can release the reference or 454 exit and the connection will be maintained until a timeout 455 event, until a specific stop request occurs, or until an 456 error is encountered. 457 @result Returns TRUE if the connection was correctly started (the 458 actual connection is not established yet, and the connection 459 status needs to be periodically checked); FALSE if the 460 connection request was not started. The error must be 461 retrieved from the SCError function. 462 */ 463Boolean 464SCNetworkConnectionStart ( 465 SCNetworkConnectionRef connection, 466 CFDictionaryRef userOptions, 467 Boolean linger 468 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 469 470 471/*! 472 @function SCNetworkConnectionStop 473 @discussion Stops the connection for the SCNetworkConnection. 474 The disconnection process is asynchronous and the function 475 will return immediately. The connection status can be 476 obtained by polling or by callback. This function performs 477 an arbitrated stop of the connection. If several applications 478 have marked their interest in the connection, by calling 479 SCNetworkConnectionStart, the call will succeed but the 480 actual connection will be maintained until the last interested 481 application calls SCNetworkConnectionStop. 482 483 In certain cases, you might want to stop the connection anyway. 484 In these cases, you set the forceDisconnect argument to TRUE. 485 @param connection The SCNetworkConnection to stop. 486 @result Returns TRUE if the disconnection request succeeded; 487 FALSE if the disconnection request failed. 488 The error must be retrieved from the SCError function. 489 */ 490Boolean 491SCNetworkConnectionStop ( 492 SCNetworkConnectionRef connection, 493 Boolean forceDisconnect 494 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 495 496 497/*! 498 @function SCNetworkConnectionCopyUserOptions 499 @discussion Copies the user options used to start the connection. 500 This is a mechanism a client can use to retrieve the user options 501 previously passed to the SCNetworkConnectionStart function. 502 @param connection The SCNetworkConnection to obtain options from. 503 @result Returns the service dictionary containing the connection options. 504 The dictionary can be empty if no user options were used. 505 If NULL is returned, the error can be retrieved using the SCError function. 506 */ 507CFDictionaryRef 508SCNetworkConnectionCopyUserOptions ( 509 SCNetworkConnectionRef connection 510 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 511 512 513/*! 514 @function SCNetworkConnectionScheduleWithRunLoop 515 @discussion Schedules a connection with the run loop. 516 @param connection The SCNetworkConnection to schedule. 517 @param runLoop The run loop to schedule with. 518 @param runLoopMode The run loop mode. 519 @result Returns TRUE if the connection is scheduled successfully; 520 FALSE if the scheduling failed. 521 The error can be retrieved using the SCError function. 522 */ 523Boolean 524SCNetworkConnectionScheduleWithRunLoop ( 525 SCNetworkConnectionRef connection, 526 CFRunLoopRef runLoop, 527 CFStringRef runLoopMode 528 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 529 530 531/*! 532 @function SCNetworkConnectionUnscheduleFromRunLoop 533 @discussion Unschedules a connection from the run loop. 534 @param connection The SCNetworkConnection to unschedule. 535 @param runLoop The run loop to unschedule from. 536 @param runLoopMode The run loop mode. 537 @result Returns TRUE if the connection is unscheduled successfully; 538 FALSE if the unscheduling failed. 539 The error can be retrieved using the SCError function. 540 */ 541Boolean 542SCNetworkConnectionUnscheduleFromRunLoop ( 543 SCNetworkConnectionRef connection, 544 CFRunLoopRef runLoop, 545 CFStringRef runLoopMode 546 ) __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_2_0/*SPI*/); 547 548 549/*! 550 @function SCNetworkConnectionSetDispatchQueue 551 @discussion Caller provides a dispatch queue on which the callback contained in connection will run. 552 @param connection The SCNetworkConnection to notify. 553 @param queue The libdispatch queue to run the callback on. 554 Pass NULL to disable notifications, and release queue. 555 @result Returns TRUE if the notifications have been enabled/disabled as desired; 556 FALSE if not. 557 The error can be retrieved using the SCError function. 558 */ 559Boolean 560SCNetworkConnectionSetDispatchQueue ( 561 SCNetworkConnectionRef connection, 562 dispatch_queue_t queue 563 ) __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0/*SPI*/); 564 565__END_DECLS 566 567#endif /* USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS */ 568#endif /* _SCNETWORKCONNECTION_H */ 569