SystemConfiguration.fproj/SCNetworkConnection.h

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