SystemConfiguration.fproj/SCNetworkConnection.h

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