SystemConfiguration.fproj/SCPrivate.h

   1 /*
   2  * Copyright (c) 2000-2009 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 <asl.h>
  30 #include <sys/syslog.h>
  31 #include <mach/message.h>
  32
  33 #include <CoreFoundation/CoreFoundation.h>
  34
  35 /* SCDynamicStore SPIs */
  36 #include <SystemConfiguration/SCDynamicStorePrivate.h>
  37 #include <SystemConfiguration/SCDynamicStoreCopySpecificPrivate.h>
  38 #include <SystemConfiguration/SCDynamicStoreSetSpecificPrivate.h>
  39
  40 /* SCPreferences SPIs */
  41 #include <SystemConfiguration/SCPreferencesPrivate.h>
  42 #include <SystemConfiguration/SCPreferencesGetSpecificPrivate.h>
  43 #include <SystemConfiguration/SCPreferencesSetSpecificPrivate.h>
  44
  45 /* [private] Schema Definitions (for SCDynamicStore and SCPreferences) */
  46 #include <SystemConfiguration/SCSchemaDefinitionsPrivate.h>
  47
  48 /* SCNetworkConfiguration SPIs */
  49 #include <SystemConfiguration/SCNetworkConfigurationPrivate.h>
  50
  51 /* SCNetworkConnection SPIs */
  52 #include <SystemConfiguration/SCNetworkConnectionPrivate.h>
  53
  54 /* Keychain SPIs */
  55 #include <SystemConfiguration/SCPreferencesKeychainPrivate.h>
  56
  57 /*!
  58         @header SCPrivate
  59  */
  60
  61 /* framework variables */
  62 extern int      _sc_debug;      /* non-zero if debugging enabled */
  63 extern int      _sc_verbose;    /* non-zero if verbose logging enabled */
  64 extern int      _sc_log;        /* 0 if SC messages should be written to stdout/stderr,
  65                                    1 if SC messages should be logged w/asl(3),
  66                                    2 if SC messages should be written to stdout/stderr AND logged */
  67
  68 /*!
  69         @group SCNetworkReachabilityCreateWithOptions #defines
  70         @discussion The following defines the keys and values that can
  71                 be passed to the SCNetworkReachabilityCreateWithOptions
  72                 API.
  73  */
  74
  75 /*!
  76         @constant kSCNetworkReachabilityOptionNodeName
  77         @discussion A CFString that will be passed to getaddrinfo(3).  An acceptable
  78                 value is either a valid host name or a numeric host address string
  79                 consisting of a dotted decimal IPv4 address or an IPv6 address.
  80  */
  81 #define kSCNetworkReachabilityOptionNodeName    CFSTR("nodename")
  82
  83 /*!
  84         @constant kSCNetworkReachabilityOptionServName
  85         @discussion A CFString that will be passed to getaddrinfo(3).  An acceptable
  86                 value is either a decimal port number or a service name listed in
  87                 services(5).
  88  */
  89 #define kSCNetworkReachabilityOptionServName    CFSTR("servname")
  90
  91 /*!
  92         @constant kSCNetworkReachabilityOptionHints
  93         @discussion A CFData wrapping a "struct addrinfo" that will be passed to
  94                 getaddrinfo(3).  The caller can supply any of the ai_family,
  95                 ai_socktype, ai_protocol, and ai_flags structure elements.  All
  96                 other elements must be 0 or the null pointer.
  97  */
  98 #define kSCNetworkReachabilityOptionHints       CFSTR("hints")
  99
 100 /*!
 101         @constant kSCNetworkReachabilityOptionConnectionOnDemandByPass
 102         @discussion A CFBoolean that indicates if we should bypass the VPNOnDemand
 103                 checks for this target.
 104  */
 105 #define kSCNetworkReachabilityOptionConnectionOnDemandByPass    CFSTR("ConnectionOnDemandByPass")
 106
 107 /*!
 108         @group
 109  */
 110
 111 __BEGIN_DECLS
 112
 113 /*!
 114         @function _SCErrorSet
 115         @discussion Sets the last SystemConfiguration.framework API error code.
 116         @param error The error encountered.
 117  */
 118 void            _SCErrorSet                     (int                    error);
 119
 120 /*!
 121         @function _SCSerialize
 122         @discussion Serialize a CFPropertyList object for passing
 123                 to/from configd.
 124         @param obj CFPropertyList object to serialize
 125         @param xml A pointer to a CFDataRef, NULL if data should be
 126                 vm_allocated.
 127         @param dataRef A pointer to the newly allocated/serialized data
 128         @param dataLen A pointer to the length in bytes of the newly
 129                 allocated/serialized data
 130  */
 131 Boolean         _SCSerialize                    (CFPropertyListRef      obj,
 132                                                  CFDataRef              *xml,
 133                                                  void                   **dataRef,
 134                                                  CFIndex                *dataLen);
 135
 136 /*!
 137         @function _SCUnserialize
 138         @discussion Unserialize a stream of bytes passed from/to configd
 139                 into a CFPropertyList object.
 140         @param obj A pointer to memory that will be filled with the CFPropertyList
 141                 associated with the stream of bytes.
 142         @param xml CFDataRef with the serialized data
 143         @param dataRef A pointer to the serialized data
 144         @param dataLen A pointer to the length of the serialized data
 145
 146         Specify either "xml" or "data/dataLen".
 147  */
 148 Boolean         _SCUnserialize                  (CFPropertyListRef      *obj,
 149                                                  CFDataRef              xml,
 150                                                  void                   *dataRef,
 151                                                  CFIndex                dataLen);
 152
 153 /*!
 154         @function _SCSerializeString
 155         @discussion Serialize a CFString object for passing
 156                 to/from configd.
 157         @param str CFString key to serialize
 158         @param data A pointer to a CFDataRef, NULL if storage should be
 159                 vm_allocated.
 160         @param dataRef A pointer to the newly allocated/serialized data
 161         @param dataLen A pointer to the length in bytes of the newly
 162                 allocated/serialized data
 163  */
 164 Boolean         _SCSerializeString              (CFStringRef            str,
 165                                                  CFDataRef              *data,
 166                                                  void                   **dataRef,
 167                                                  CFIndex                *dataLen);
 168
 169 /*!
 170         @function _SCUnserializeString
 171         @discussion Unserialize a stream of bytes passed from/to configd
 172                 into a CFString object.
 173         @param str A pointer to memory that will be filled with the CFString
 174                 associated with the stream of bytes.
 175         @param utf8 CFDataRef with the serialized data
 176         @param dataRef A pointer to the serialized data
 177         @param dataLen A pointer to the length of the serialized data
 178
 179         Specify either "utf8" or "data/dataLen".
 180  */
 181 Boolean         _SCUnserializeString            (CFStringRef            *str,
 182                                                  CFDataRef              utf8,
 183                                                  void                   *dataRef,
 184                                                  CFIndex                dataLen);
 185
 186 /*!
 187         @function _SCSerializeData
 188         @discussion Serialize a CFData object for passing
 189                 to/from configd.
 190         @param data CFData key to serialize
 191         @param dataRef A pointer to the newly allocated/serialized data
 192         @param dataLen A pointer to the length in bytes of the newly
 193                 allocated/serialized data
 194  */
 195 Boolean         _SCSerializeData                (CFDataRef              data,
 196                                                  void                   **dataRef,
 197                                                  CFIndex                *dataLen);
 198
 199 /*!
 200         @function _SCUnserializeData
 201         @discussion Unserialize a stream of bytes passed from/to configd
 202                 into a CFData object.
 203         @param data A pointer to memory that will be filled with the CFData
 204                 associated with the stream of bytes.
 205         @param dataRef A pointer to the serialized data
 206         @param dataLen A pointer to the length of the serialized data
 207  */
 208 Boolean         _SCUnserializeData              (CFDataRef              *data,
 209                                                  void                   *dataRef,
 210                                                  CFIndex                dataLen);
 211
 212 /*!
 213         @function _SCSerializeMultiple
 214         @discussion Convert a CFDictionary containing a set of CFPropertlyList
 215                 values into a CFDictionary containing a set of serialized CFData
 216                 values.
 217         @param dict The CFDictionary with CFPropertyList values.
 218         @result The serialized CFDictionary with CFData values
 219  */
 220 CFDictionaryRef _SCSerializeMultiple            (CFDictionaryRef        dict);
 221
 222 /*!
 223         @function _SCUnserializeMultiple
 224         @discussion Convert a CFDictionary containing a set of CFData
 225                 values into a CFDictionary containing a set of serialized
 226                 CFPropertlyList values.
 227         @param dict The CFDictionary with CFData values.
 228         @result The serialized CFDictionary with CFPropertyList values
 229  */
 230 CFDictionaryRef _SCUnserializeMultiple          (CFDictionaryRef        dict);
 231
 232 /*!
 233         @function _SC_cfstring_to_cstring
 234         @discussion Extracts a C-string from a CFString.
 235         @param cfstr The CFString to extract the data from.
 236         @param buf A user provided buffer of the specified length.  If NULL,
 237                 a new buffer will be allocated to contain the C-string.  It
 238                 is the responsiblity of the caller to free an allocated
 239                 buffer.
 240         @param bufLen The size of the user provided buffer.
 241         @param encoding The string encoding
 242         @result If the extraction (conversion) is successful then a pointer
 243                 to the user provided (or allocated) buffer is returned, NULL
 244                 if the string could not be extracted.
 245  */
 246 char *          _SC_cfstring_to_cstring         (CFStringRef            cfstr,
 247                                                  char                   *buf,
 248                                                  CFIndex                bufLen,
 249                                                  CFStringEncoding       encoding);
 250
 251 /*!
 252  *      @function _SC_sockaddr_to_string
 253  *      @discussion Formats a "struct sockaddr" for reporting
 254  *      @param address The address to format
 255  *      @param buf A user provided buffer of the specified length.
 256  *      @param bufLen The size of the user provided buffer.
 257  */
 258 void            _SC_sockaddr_to_string          (const struct sockaddr  *address,
 259                                                  char                   *buf,
 260                                                  size_t                 bufLen);
 261
 262 /*!
 263         @function _SC_sendMachMessage
 264         @discussion Sends a trivial mach message (one with just a
 265                 message ID) to the specified port.
 266         @param port The mach port.
 267         @param msg_id The message id.
 268  */
 269 void            _SC_sendMachMessage             (mach_port_t            port,
 270                                                  mach_msg_id_t          msg_id);
 271
 272
 273 /*!
 274         @function _SCCopyDescription
 275         @discussion Returns a formatted textual description of a CF object.
 276         @param cf The CFType object (a generic reference of type CFTypeRef) from
 277                 which to derive a description.
 278         @param formatOptions A dictionary containing formatting options for the object.
 279         @result A string that contains a formatted description of cf.
 280  */
 281 CFStringRef     _SCCopyDescription              (CFTypeRef              cf,
 282                                                  CFDictionaryRef        formatOptions);
 283
 284
 285 /*!
 286         @function SCLog
 287         @discussion Conditionally issue a log message.
 288         @param condition A boolean value indicating if the message should be logged
 289         @param level A syslog(3) logging priority.
 290         @param formatString The format string
 291         @result The specified message will be written to the system message
 292                 logger (See syslogd(8)).
 293  */
 294 void            SCLog                           (Boolean                condition,
 295                                                  int                    level,
 296                                                  CFStringRef            formatString,
 297                                                  ...);
 298
 299
 300 /*!
 301         @function SCLOG
 302         @discussion Issue a log message.
 303         @param asl An asl client handle to be used for logging. If NULL, a shared
 304                 handle will be used.
 305         @param msg An asl msg structure to be used for logging. If NULL, a default
 306                 asl msg will be used.
 307         @param level A asl(3) logging priority. Passing the complement of a logging
 308                 priority (e.g. ~ASL_LEVEL_NOTICE) will result in log message lines
 309                 NOT being split by a "\n".
 310         @param formatString The format string
 311         @result The specified message will be written to the system message
 312                 logger (See syslogd(8)).
 313  */
 314 void            SCLOG                           (aslclient              asl,
 315                                                  aslmsg                 msg,
 316                                                  int                    level,
 317                                                  CFStringRef            formatString,
 318                                                  ...);
 319
 320
 321 /*!
 322         @function SCPrint
 323         @discussion Conditionally issue a debug message.
 324         @param condition A boolean value indicating if the message should be written
 325         @param stream The output stream for the log message.
 326         @param formatString The format string
 327         @result The message will be written to the specified stream
 328                 stream.
 329  */
 330 void            SCPrint                         (Boolean                condition,
 331                                                  FILE                   *stream,
 332                                                  CFStringRef            formatString,
 333                                                  ...);
 334
 335 /*!
 336         @function SCTrace
 337         @discussion Conditionally issue a debug message with a time stamp.
 338         @param condition A boolean value indicating if the message should be written
 339         @param stream The output stream for the log message.
 340         @param formatString The format string
 341         @result The message will be written to the specified stream
 342                 stream.
 343  */
 344 void            SCTrace                         (Boolean                condition,
 345                                                  FILE                   *stream,
 346                                                  CFStringRef            formatString,
 347                                                  ...);
 348
 349 /*!
 350         @function SCNetworkReachabilityCopyOnDemandService
 351         @discussion For target hosts that require an OnDemand connection, returns
 352                 the SCNetworkService associated with the connection and user
 353                 options to use with SCNetworkConnectionStart.
 354         @result The SCNetworkService for the target; NULL if there is
 355                 no associated OnDemand service.
 356  */
 357 SCNetworkServiceRef
 358 SCNetworkReachabilityCopyOnDemandService        (SCNetworkReachabilityRef       target,
 359                                                  CFDictionaryRef                *userOptions);
 360
 361 /*!
 362         @function SCNetworkReachabilityCopyResolvedAddress
 363         @discussion Return the resolved addresses associated with the
 364                 target host.
 365         @result A CFArray[CFData], where each CFData is a (struct sockaddr)
 366  */
 367 CFArrayRef
 368 SCNetworkReachabilityCopyResolvedAddress        (SCNetworkReachabilityRef       target,
 369                                                  int                            *error_num);
 370
 371 /*!
 372         @function SCNetworkReachabilityCreateWithOptions
 373         @discussion Creates a reference to a specified network host.  The
 374                 options allow the caller to specify the node name and/or
 375                 the service name.  This reference can be used later to
 376                 monitor the reachability of the target host.
 377         @param allocator The CFAllocator that should be used to allocate
 378                 memory for the SCNetworkReachability object.
 379                 This parameter may be NULL in which case the current
 380                 default CFAllocator is used. If this reference is not
 381                 a valid CFAllocator, the behavior is undefined.
 382         @param options A CFDictionary containing options specifying the
 383                 network host.  The options reflect the arguments that would
 384                 be passed to getaddrinfo().
 385   */
 386 SCNetworkReachabilityRef
 387 SCNetworkReachabilityCreateWithOptions          (CFAllocatorRef         allocator,
 388                                                  CFDictionaryRef        options);
 389
 390 /*!
 391         @function _SC_checkResolverReachabilityByAddress
 392         @discussion Check the reachability of a reverse DNS query
 393  */
 394 Boolean
 395 _SC_checkResolverReachabilityByAddress          (SCDynamicStoreRef              *storeP,
 396                                                  SCNetworkReachabilityFlags     *flags,
 397                                                  Boolean                        *haveDNS,
 398                                                  struct sockaddr                *sa);
 399
 400 #if     !TARGET_OS_IPHONE
 401 /*
 402  * DOS encoding/codepage
 403  */
 404 void
 405 _SC_dos_encoding_and_codepage                   (CFStringEncoding       macEncoding,
 406                                                  UInt32                 macRegion,
 407                                                  CFStringEncoding       *dosEncoding,
 408                                                  UInt32                 *dosCodepage);
 409 #endif  // !TARGET_OS_IPHONE
 410
 411 /*
 412  * object / CFRunLoop  management
 413  */
 414 void
 415 _SC_signalRunLoop                               (CFTypeRef              obj,
 416                                                  CFRunLoopSourceRef     rls,
 417                                                  CFArrayRef             rlList);
 418
 419 Boolean
 420 _SC_isScheduled                                 (CFTypeRef              obj,
 421                                                  CFRunLoopRef           runLoop,
 422                                                  CFStringRef            runLoopMode,
 423                                                  CFMutableArrayRef      rlList);
 424
 425 void
 426 _SC_schedule                                    (CFTypeRef              obj,
 427                                                  CFRunLoopRef           runLoop,
 428                                                  CFStringRef            runLoopMode,
 429                                                  CFMutableArrayRef      rlList);
 430
 431 Boolean
 432 _SC_unschedule                                  (CFTypeRef              obj,
 433                                                  CFRunLoopRef           runLoop,
 434                                                  CFStringRef            runLoopMode,
 435                                                  CFMutableArrayRef      rlList,
 436                                                  Boolean                all);
 437
 438 /*
 439  * bundle access
 440  */
 441 CFBundleRef
 442 _SC_CFBundleGet                                 (void);
 443
 444 CFStringRef
 445 _SC_CFBundleCopyNonLocalizedString              (CFBundleRef            bundle,
 446                                                  CFStringRef            key,
 447                                                  CFStringRef            value,
 448                                                  CFStringRef            tableName);
 449
 450 /*
 451  * misc
 452  */
 453 static __inline__ Boolean
 454 _SC_CFEqual(CFTypeRef val1, CFTypeRef val2)
 455 {
 456         if (val1 == val2) {
 457             return TRUE;
 458         }
 459         if (val1 != NULL && val2 != NULL) {
 460                 return CFEqual(val1, val2);
 461         }
 462         return FALSE;
 463 }
 464
 465 /*
 466  * debugging
 467  */
 468
 469 #ifdef  DEBUG_MACH_PORT_ALLOCATIONS
 470         #define __MACH_PORT_DEBUG(cond, str, port)              \
 471         do {                                                    \
 472                 if (cond) _SC_logMachPortReferences(str, port); \
 473         } while (0)
 474 #else   // DEBUG_MACH_PORT_ALLOCATIONS
 475         #define __MACH_PORT_DEBUG(cond, str, port)
 476 #endif  // DEBUG_MACH_PORT_ALLOCATIONS
 477
 478 void
 479 _SC_logMachPortStatus                           (void);
 480
 481 void
 482 _SC_logMachPortReferences                       (const char             *str,
 483                                                  mach_port_t            port);
 484
 485 CFStringRef
 486 _SC_copyBacktrace                               (void);
 487
 488 __END_DECLS
 489
 490 #endif  /* _SCPRIVATE_H */