SystemConfiguration.fproj/SCPrivate.h

   1 /*
   2  * Copyright (c) 2000-2011 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SCPRIVATE_H
  25 #define _SCPRIVATE_H
  26
  27 #include <sys/cdefs.h>
  28 #include <sys/socket.h>
  29 #include <sys/stat.h>
  30 #include <asl.h>
  31 #include <sys/syslog.h>
  32 #include <mach/message.h>
  33
  34 #include <CoreFoundation/CoreFoundation.h>
  35
  36 /* SCDynamicStore SPIs */
  37 #include <SystemConfiguration/SCDynamicStorePrivate.h>
  38 #include <SystemConfiguration/SCDynamicStoreCopySpecificPrivate.h>
  39 #include <SystemConfiguration/SCDynamicStoreSetSpecificPrivate.h>
  40
  41 /* SCPreferences SPIs */
  42 #include <SystemConfiguration/SCPreferencesPrivate.h>
  43 #include <SystemConfiguration/SCPreferencesGetSpecificPrivate.h>
  44 #include <SystemConfiguration/SCPreferencesSetSpecificPrivate.h>
  45
  46 /* [private] Schema Definitions (for SCDynamicStore and SCPreferences) */
  47 #include <SystemConfiguration/SCSchemaDefinitionsPrivate.h>
  48
  49 /* SCNetworkConfiguration SPIs */
  50 #include <SystemConfiguration/SCNetworkConfigurationPrivate.h>
  51
  52 /* SCNetworkConnection SPIs */
  53 #include <SystemConfiguration/SCNetworkConnectionPrivate.h>
  54
  55 /* Keychain SPIs */
  56 #include <SystemConfiguration/SCPreferencesKeychainPrivate.h>
  57
  58 /*!
  59         @header SCPrivate
  60  */
  61
  62 /* framework variables */
  63 extern int      _sc_debug;      /* non-zero if debugging enabled */
  64 extern int      _sc_verbose;    /* non-zero if verbose logging enabled */
  65 extern int      _sc_log;        /* 0 if SC messages should be written to stdout/stderr,
  66                                    1 if SC messages should be logged w/asl(3),
  67                                    2 if SC messages should be written to stdout/stderr AND logged */
  68
  69 /*!
  70         @group SCNetworkReachabilityCreateWithOptions #defines
  71         @discussion The following defines the keys and values that can
  72                 be passed to the SCNetworkReachabilityCreateWithOptions
  73                 API.
  74  */
  75
  76 /*!
  77         @constant kSCNetworkReachabilityOptionNodeName
  78         @discussion A CFString that will be passed to getaddrinfo(3).  An acceptable
  79                 value is either a valid host name or a numeric host address string
  80                 consisting of a dotted decimal IPv4 address or an IPv6 address.
  81  */
  82 #define kSCNetworkReachabilityOptionNodeName                    CFSTR("nodename")
  83
  84 /*!
  85         @constant kSCNetworkReachabilityOptionLocalAddress
  86         @discussion A CFData wrapping a "struct sockaddr" that represents
  87                 local address associated with a network connection.
  88  */
  89 #define kSCNetworkReachabilityOptionLocalAddress                CFSTR("local-address")
  90
  91 /*!
  92         @constant kSCNetworkReachabilityOptionRemoteAddress
  93         @discussion A CFData wrapping a "struct sockaddr" that represents
  94                 remote address associated with a network connection.
  95  */
  96 #define kSCNetworkReachabilityOptionRemoteAddress               CFSTR("remote-address")
  97
  98 /*!
  99         @constant kSCNetworkReachabilityOptionServName
 100         @discussion A CFString that will be passed to getaddrinfo(3).  An acceptable
 101                 value is either a decimal port number or a service name listed in
 102                 services(5).
 103  */
 104 #define kSCNetworkReachabilityOptionServName                    CFSTR("servname")
 105
 106 /*!
 107         @constant kSCNetworkReachabilityOptionHints
 108         @discussion A CFData wrapping a "struct addrinfo" that will be passed to
 109                 getaddrinfo(3).  The caller can supply any of the ai_family,
 110                 ai_socktype, ai_protocol, and ai_flags structure elements.  All
 111                 other elements must be 0 or the null pointer.
 112  */
 113 #define kSCNetworkReachabilityOptionHints                       CFSTR("hints")
 114
 115 /*!
 116         @constant kSCNetworkReachabilityOptionInterface
 117         @discussion A CFString specifying that the reachability query should be
 118                 limited to the provided network interface (e.g. "en0", "en1", ...).
 119  */
 120 #define kSCNetworkReachabilityOptionInterface                   CFSTR("interface")
 121
 122
 123 /*!
 124         @constant kSCNetworkReachabilityOptionConnectionOnDemandByPass
 125         @discussion A CFBoolean that indicates if we should bypass the VPNOnDemand
 126                 checks for this target.
 127  */
 128 #define kSCNetworkReachabilityOptionConnectionOnDemandByPass    CFSTR("ConnectionOnDemandByPass")
 129
 130
 131 /*!
 132         @group
 133  */
 134
 135 __BEGIN_DECLS
 136
 137
 138 #pragma mark -
 139 #pragma mark SCError()
 140
 141
 142 /*!
 143         @function _SCErrorSet
 144         @discussion Sets the last SystemConfiguration.framework API error code.
 145         @param error The error encountered.
 146  */
 147 void            _SCErrorSet                     (int                    error);
 148
 149
 150 #pragma mark -
 151 #pragma mark Serialization/Unserialization
 152
 153
 154 /*!
 155         @function _SCSerialize
 156         @discussion Serialize a CFPropertyList object for passing
 157                 to/from configd.
 158         @param obj CFPropertyList object to serialize
 159         @param xml A pointer to a CFDataRef, NULL if data should be
 160                 vm_allocated.
 161         @param dataRef A pointer to the newly allocated/serialized data
 162         @param dataLen A pointer to the length in bytes of the newly
 163                 allocated/serialized data
 164  */
 165 Boolean         _SCSerialize                    (CFPropertyListRef      obj,
 166                                                  CFDataRef              *xml,
 167                                                  void                   **dataRef,
 168                                                  CFIndex                *dataLen);
 169
 170 /*!
 171         @function _SCUnserialize
 172         @discussion Unserialize a stream of bytes passed from/to configd
 173                 into a CFPropertyList object.
 174         @param obj A pointer to memory that will be filled with the CFPropertyList
 175                 associated with the stream of bytes.
 176         @param xml CFDataRef with the serialized data
 177         @param dataRef A pointer to the serialized data
 178         @param dataLen A pointer to the length of the serialized data
 179
 180         Specify either "xml" or "data/dataLen".
 181  */
 182 Boolean         _SCUnserialize                  (CFPropertyListRef      *obj,
 183                                                  CFDataRef              xml,
 184                                                  void                   *dataRef,
 185                                                  CFIndex                dataLen);
 186
 187 /*!
 188         @function _SCSerializeString
 189         @discussion Serialize a CFString object for passing
 190                 to/from configd.
 191         @param str CFString key to serialize
 192         @param data A pointer to a CFDataRef, NULL if storage should be
 193                 vm_allocated.
 194         @param dataRef A pointer to the newly allocated/serialized data
 195         @param dataLen A pointer to the length in bytes of the newly
 196                 allocated/serialized data
 197  */
 198 Boolean         _SCSerializeString              (CFStringRef            str,
 199                                                  CFDataRef              *data,
 200                                                  void                   **dataRef,
 201                                                  CFIndex                *dataLen);
 202
 203 /*!
 204         @function _SCUnserializeString
 205         @discussion Unserialize a stream of bytes passed from/to configd
 206                 into a CFString object.
 207         @param str A pointer to memory that will be filled with the CFString
 208                 associated with the stream of bytes.
 209         @param utf8 CFDataRef with the serialized data
 210         @param dataRef A pointer to the serialized data
 211         @param dataLen A pointer to the length of the serialized data
 212
 213         Specify either "utf8" or "data/dataLen".
 214  */
 215 Boolean         _SCUnserializeString            (CFStringRef            *str,
 216                                                  CFDataRef              utf8,
 217                                                  void                   *dataRef,
 218                                                  CFIndex                dataLen);
 219
 220 /*!
 221         @function _SCSerializeData
 222         @discussion Serialize a CFData object for passing
 223                 to/from configd.
 224         @param data CFData key to serialize
 225         @param dataRef A pointer to the newly allocated/serialized data
 226         @param dataLen A pointer to the length in bytes of the newly
 227                 allocated/serialized data
 228  */
 229 Boolean         _SCSerializeData                (CFDataRef              data,
 230                                                  void                   **dataRef,
 231                                                  CFIndex                *dataLen);
 232
 233 /*!
 234         @function _SCUnserializeData
 235         @discussion Unserialize a stream of bytes passed from/to configd
 236                 into a CFData object.
 237         @param data A pointer to memory that will be filled with the CFData
 238                 associated with the stream of bytes.
 239         @param dataRef A pointer to the serialized data
 240         @param dataLen A pointer to the length of the serialized data
 241  */
 242 Boolean         _SCUnserializeData              (CFDataRef              *data,
 243                                                  void                   *dataRef,
 244                                                  CFIndex                dataLen);
 245
 246 /*!
 247         @function _SCSerializeMultiple
 248         @discussion Convert a CFDictionary containing a set of CFPropertlyList
 249                 values into a CFDictionary containing a set of serialized CFData
 250                 values.
 251         @param dict The CFDictionary with CFPropertyList values.
 252         @result The serialized CFDictionary with CFData values
 253  */
 254 CFDictionaryRef _SCSerializeMultiple            (CFDictionaryRef        dict);
 255
 256 /*!
 257         @function _SCUnserializeMultiple
 258         @discussion Convert a CFDictionary containing a set of CFData
 259                 values into a CFDictionary containing a set of serialized
 260                 CFPropertlyList values.
 261         @param dict The CFDictionary with CFData values.
 262         @result The serialized CFDictionary with CFPropertyList values
 263  */
 264 CFDictionaryRef _SCUnserializeMultiple          (CFDictionaryRef        dict);
 265
 266
 267 #pragma mark -
 268 #pragma mark String conversion
 269
 270
 271 /*!
 272         @function _SC_cfstring_to_cstring
 273         @discussion Extracts a C-string from a CFString.
 274         @param cfstr The CFString to extract the data from.
 275         @param buf A user provided buffer of the specified length.  If NULL,
 276                 a new buffer will be allocated to contain the C-string.  It
 277                 is the responsiblity of the caller to free an allocated
 278                 buffer.
 279         @param bufLen The size of the user provided buffer.
 280         @param encoding The string encoding
 281         @result If the extraction (conversion) is successful then a pointer
 282                 to the user provided (or allocated) buffer is returned, NULL
 283                 if the string could not be extracted.
 284  */
 285 char *          _SC_cfstring_to_cstring         (CFStringRef            cfstr,
 286                                                  char                   *buf,
 287                                                  CFIndex                bufLen,
 288                                                  CFStringEncoding       encoding);
 289
 290 /*!
 291  *      @function _SC_sockaddr_to_string
 292  *      @discussion Formats a "struct sockaddr" for reporting
 293  *      @param address The address to format
 294  *      @param buf A user provided buffer of the specified length.
 295  *      @param bufLen The size of the user provided buffer.
 296  */
 297 void            _SC_sockaddr_to_string          (const struct sockaddr  *address,
 298                                                  char                   *buf,
 299                                                  size_t                 bufLen);
 300
 301
 302 /*!
 303  *      @function _SC_trimDomain
 304  *      @discussion Trims leading and trailing "."s from a domain or host name
 305  *      @param domain The domain name to trim
 306  *      @result The trimmed domain name.
 307  */
 308 CFStringRef     _SC_trimDomain                  (CFStringRef            domain);
 309
 310
 311 #pragma mark -
 312 #pragma mark Mach IPC
 313
 314
 315 /*!
 316         @function _SC_sendMachMessage
 317         @discussion Sends a trivial mach message (one with just a
 318                 message ID) to the specified port.
 319         @param port The mach port.
 320         @param msg_id The message id.
 321  */
 322 void            _SC_sendMachMessage             (mach_port_t            port,
 323                                                  mach_msg_id_t          msg_id);
 324
 325
 326 #pragma mark -
 327 #pragma mark Logging
 328
 329
 330 /*!
 331         @function _SCCopyDescription
 332         @discussion Returns a formatted textual description of a CF object.
 333         @param cf The CFType object (a generic reference of type CFTypeRef) from
 334                 which to derive a description.
 335         @param formatOptions A dictionary containing formatting options for the object.
 336         @result A string that contains a formatted description of cf.
 337  */
 338 CFStringRef     _SCCopyDescription              (CFTypeRef              cf,
 339                                                  CFDictionaryRef        formatOptions);
 340
 341
 342 /*!
 343         @function SCLog
 344         @discussion Conditionally issue a log message.
 345         @param condition A boolean value indicating if the message should be logged
 346         @param level A syslog(3) logging priority.
 347         @param formatString The format string
 348         @result The specified message will be written to the system message
 349                 logger (See syslogd(8)).
 350  */
 351 void            SCLog                           (Boolean                condition,
 352                                                  int                    level,
 353                                                  CFStringRef            formatString,
 354                                                  ...);
 355
 356
 357 /*!
 358         @function SCLOG
 359         @discussion Issue a log message.
 360         @param asl An asl client handle to be used for logging. If NULL, a shared
 361                 handle will be used.
 362         @param msg An asl msg structure to be used for logging. If NULL, a default
 363                 asl msg will be used.
 364         @param level A asl(3) logging priority. Passing the complement of a logging
 365                 priority (e.g. ~ASL_LEVEL_NOTICE) will result in log message lines
 366                 NOT being split by a "\n".
 367         @param formatString The format string
 368         @result The specified message will be written to the system message
 369                 logger (See syslogd(8)).
 370  */
 371 void            SCLOG                           (aslclient              asl,
 372                                                  aslmsg                 msg,
 373                                                  int                    level,
 374                                                  CFStringRef            formatString,
 375                                                  ...);
 376
 377
 378 /*!
 379         @function SCPrint
 380         @discussion Conditionally issue a debug message.
 381         @param condition A boolean value indicating if the message should be written
 382         @param stream The output stream for the log message.
 383         @param formatString The format string
 384         @result The message will be written to the specified stream
 385                 stream.
 386  */
 387 void            SCPrint                         (Boolean                condition,
 388                                                  FILE                   *stream,
 389                                                  CFStringRef            formatString,
 390                                                  ...);
 391
 392 /*!
 393         @function SCTrace
 394         @discussion Conditionally issue a debug message with a time stamp.
 395         @param condition A boolean value indicating if the message should be written
 396         @param stream The output stream for the log message.
 397         @param formatString The format string
 398         @result The message will be written to the specified stream
 399                 stream.
 400  */
 401 void            SCTrace                         (Boolean                condition,
 402                                                  FILE                   *stream,
 403                                                  CFStringRef            formatString,
 404                                                  ...);
 405
 406 #pragma mark -
 407 #pragma mark Proxies
 408
 409
 410 /*!
 411         @function SCNetworkProxiesCopyMatching
 412         @discussion
 413         @param globalConfiguration the proxy dictionary currently returned
 414                 by SCDynamicStoreCopyProxies().
 415         @param server A CFString specying the hostname of interest; NULL if
 416                 no specific hostname should be used in selecting the proxy
 417                 configurations.
 418         @param interface A CFString specifying that the proxy configuration
 419                 for the provided network interface (e.g. "en0", "en1", ...)
 420                 should be returned; NULL if proxy usage will not be scoped
 421                 to an interface.
 422         @result A CFArray containing the proxy configurations associated
 423                 with the requested server and/or network interface.
 424
 425  */
 426 CFArrayRef
 427 SCNetworkProxiesCopyMatching                    (CFDictionaryRef        globalConfiguration,
 428                                                  CFStringRef            server,
 429                                                  CFStringRef            interface)      __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0/*SPI*/);
 430
 431 #pragma mark -
 432 #pragma mark Reachability
 433
 434
 435 /*!
 436         @function SCNetworkReachabilityCopyOnDemandService
 437         @discussion For target hosts that require an OnDemand connection, returns
 438                 the SCNetworkService associated with the connection and user
 439                 options to use with SCNetworkConnectionStart.
 440         @result The SCNetworkService for the target; NULL if there is
 441                 no associated OnDemand service.
 442  */
 443 SCNetworkServiceRef
 444 SCNetworkReachabilityCopyOnDemandService        (SCNetworkReachabilityRef       target,
 445                                                  CFDictionaryRef                *userOptions);
 446
 447 /*!
 448         @function SCNetworkReachabilityCopyResolvedAddress
 449         @discussion Return the resolved addresses associated with the
 450                 target host.
 451         @result A CFArray[CFData], where each CFData is a (struct sockaddr)
 452  */
 453 CFArrayRef
 454 SCNetworkReachabilityCopyResolvedAddress        (SCNetworkReachabilityRef       target,
 455                                                  int                            *error_num);
 456
 457 /*!
 458         @function SCNetworkReachabilityCreateWithOptions
 459         @discussion Creates a reference to a specified network host.  The
 460                 options allow the caller to specify the node name and/or
 461                 the service name.  This reference can be used later to
 462                 monitor the reachability of the target host.
 463         @param allocator The CFAllocator that should be used to allocate
 464                 memory for the SCNetworkReachability object.
 465                 This parameter may be NULL in which case the current
 466                 default CFAllocator is used. If this reference is not
 467                 a valid CFAllocator, the behavior is undefined.
 468         @param options A CFDictionary containing options specifying the
 469                 network host.  The options reflect the arguments that would
 470                 be passed to getaddrinfo().
 471   */
 472 SCNetworkReachabilityRef
 473 SCNetworkReachabilityCreateWithOptions          (CFAllocatorRef         allocator,
 474                                                  CFDictionaryRef        options);
 475
 476 /*!
 477         @function _SC_checkResolverReachabilityByAddress
 478         @discussion Check the reachability of a reverse DNS query
 479  */
 480 Boolean
 481 _SC_checkResolverReachabilityByAddress          (SCDynamicStoreRef              *storeP,
 482                                                  SCNetworkReachabilityFlags     *flags,
 483                                                  Boolean                        *haveDNS,
 484                                                  struct sockaddr                *sa);
 485
 486 #pragma mark -
 487 #pragma mark NetBIOS
 488
 489
 490 #if     !TARGET_OS_IPHONE
 491 /*
 492  * DOS encoding/codepage
 493  */
 494 void
 495 _SC_dos_encoding_and_codepage                   (CFStringEncoding       macEncoding,
 496                                                  UInt32                 macRegion,
 497                                                  CFStringEncoding       *dosEncoding,
 498                                                  UInt32                 *dosCodepage);
 499 #endif  // !TARGET_OS_IPHONE
 500
 501 #pragma mark -
 502 #pragma mark ScheduleWithRunLoop/UnscheduleFromRunLoop
 503
 504
 505 /*
 506  * object / CFRunLoop  management
 507  */
 508 void
 509 _SC_signalRunLoop                               (CFTypeRef              obj,
 510                                                  CFRunLoopSourceRef     rls,
 511                                                  CFArrayRef             rlList);
 512
 513 Boolean
 514 _SC_isScheduled                                 (CFTypeRef              obj,
 515                                                  CFRunLoopRef           runLoop,
 516                                                  CFStringRef            runLoopMode,
 517                                                  CFMutableArrayRef      rlList);
 518
 519 void
 520 _SC_schedule                                    (CFTypeRef              obj,
 521                                                  CFRunLoopRef           runLoop,
 522                                                  CFStringRef            runLoopMode,
 523                                                  CFMutableArrayRef      rlList);
 524
 525 Boolean
 526 _SC_unschedule                                  (CFTypeRef              obj,
 527                                                  CFRunLoopRef           runLoop,
 528                                                  CFStringRef            runLoopMode,
 529                                                  CFMutableArrayRef      rlList,
 530                                                  Boolean                all);
 531
 532 #pragma mark -
 533 #pragma mark Bundle
 534
 535
 536 /*
 537  * bundle access
 538  */
 539 CFBundleRef
 540 _SC_CFBundleGet                                 (void);
 541
 542 CFStringRef
 543 _SC_CFBundleCopyNonLocalizedString              (CFBundleRef            bundle,
 544                                                  CFStringRef            key,
 545                                                  CFStringRef            value,
 546                                                  CFStringRef            tableName);
 547
 548 #pragma mark -
 549 #pragma mark Misc
 550
 551
 552 /*
 553  * mach port access
 554  */
 555 CFMachPortRef
 556 _SC_CFMachPortCreateWithPort                    (const char *           portDescription,
 557                                                  mach_port_t            portNum,
 558                                                  CFMachPortCallBack     callout,
 559                                                  CFMachPortContext      *context);
 560
 561 /*
 562  * misc
 563  */
 564 static __inline__ Boolean
 565 _SC_CFEqual(CFTypeRef val1, CFTypeRef val2)
 566 {
 567         if (val1 == val2) {
 568             return TRUE;
 569         }
 570         if (val1 != NULL && val2 != NULL) {
 571                 return CFEqual(val1, val2);
 572         }
 573         return FALSE;
 574 }
 575
 576 static __inline__ Boolean
 577 _SC_isAppleInternal()
 578 {
 579         static int isInternal   = 0;
 580
 581         if (isInternal == 0) {
 582                 int             ret;
 583                 struct stat     statbuf;
 584
 585                 ret = stat("/AppleInternal", &statbuf);
 586                 isInternal = (ret == 0) ? 1 : 2;
 587         }
 588
 589         return (isInternal == 1);
 590 }
 591
 592 /*
 593  * debugging
 594  */
 595
 596 #ifdef  DEBUG_MACH_PORT_ALLOCATIONS
 597         #define __MACH_PORT_DEBUG(cond, str, port)              \
 598         do {                                                    \
 599                 if (cond) _SC_logMachPortReferences(str, port); \
 600         } while (0)
 601 #else   // DEBUG_MACH_PORT_ALLOCATIONS
 602         #define __MACH_PORT_DEBUG(cond, str, port)
 603 #endif  // DEBUG_MACH_PORT_ALLOCATIONS
 604
 605 void
 606 _SC_logMachPortStatus                           (void);
 607
 608 void
 609 _SC_logMachPortReferences                       (const char             *str,
 610                                                  mach_port_t            port);
 611
 612 CFStringRef
 613 _SC_copyBacktrace                               (void);
 614
 615 void
 616 _SC_crash                                       (const char             *crash_info,
 617                                                  CFStringRef            notifyHeader,
 618                                                  CFStringRef            notifyMessage);
 619
 620 __END_DECLS
 621
 622 #endif  /* _SCPRIVATE_H */