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