SystemConfiguration.fproj/SCNetworkConnection.h

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