SystemConfiguration.fproj/SCDynamicStoreKey.h

   1 /*
   2  * Copyright (c) 2000-2002, 2004, 2005, 2008, 2015 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 _SCDYNAMICSTOREKEY_H
  25 #ifdef  USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS
  26 #include <SystemConfiguration/_SCDynamicStoreKey.h>
  27 #else   /* USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS */
  28 #define _SCDYNAMICSTOREKEY_H
  29
  30 #include <Availability.h>
  31 #include <sys/cdefs.h>
  32 #include <CoreFoundation/CoreFoundation.h>
  33
  34 CF_IMPLICIT_BRIDGING_ENABLED
  35 CF_ASSUME_NONNULL_BEGIN
  36
  37 /*!
  38         @header SCDynamicStoreKey
  39         @discussion The SCDynamicStoreKey API provides convenience functions
  40                 that an application can use to create a correctly formatted
  41                 dynamic store key for accessing specific items in the dynamic
  42                 store.  An application can then use the resulting string in
  43                 any function that requires a dynamic store key.
  44  */
  45
  46
  47 __BEGIN_DECLS
  48
  49 /*
  50  * SCDynamicStoreKeyCreate
  51  * - convenience routines that create a CFString key for an item in the store
  52  */
  53
  54 /*!
  55         @function SCDynamicStoreKeyCreate
  56         @discussion Creates a dynamic store key using the given format.
  57         @param allocator The CFAllocator that should be used to allocate
  58                 memory for this key.
  59                 This parameter may be NULL in which case the current
  60                 default CFAllocator is used. If this reference is not
  61                 a valid CFAllocator, the behavior is undefined.
  62         @param fmt A CFStringRef describing the format for this key.
  63         @result Returns a string containing the formatted key.
  64  */
  65 CFStringRef
  66 SCDynamicStoreKeyCreate                         (
  67                                                 CFAllocatorRef  __nullable      allocator,
  68                                                 CFStringRef                     fmt,
  69                                                 ...
  70                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
  71
  72 /*!
  73         @function SCDynamicStoreKeyCreateNetworkGlobalEntity
  74         @discussion Creates a dynamic store key that can be used to access
  75                 a specific global (as opposed to a per-service or per-interface)
  76                 network configuration entity.
  77         @param allocator The CFAllocator that should be used to allocate
  78                 memory for this key.
  79                 This parameter may be NULL in which case the current
  80                 default CFAllocator is used. If this reference is not
  81                 a valid CFAllocator, the behavior is undefined.
  82         @param domain A string specifying the desired domain, such as the
  83                 requested configuration (kSCDynamicStoreDomainSetup) or the
  84                 actual state (kSCDynamicStoreDomainState).
  85         @param entity A string containing the specific global entity, such
  86                 as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
  87         @result Returns a string containing the formatted key.
  88
  89  */
  90 CFStringRef
  91 SCDynamicStoreKeyCreateNetworkGlobalEntity      (
  92                                                 CFAllocatorRef  __nullable      allocator,
  93                                                 CFStringRef                     domain,
  94                                                 CFStringRef                     entity
  95                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
  96
  97 /*!
  98         @function SCDynamicStoreKeyCreateNetworkInterface
  99         @discussion Creates a dynamic store key that can be used to access
 100                 the network interface configuration information stored in
 101                 the dynamic store.
 102         @param allocator The CFAllocator that should be used to allocate
 103                 memory for this key.
 104                 This parameter may be NULL in which case the current
 105                 default CFAllocator is used. If this reference is not
 106                 a valid CFAllocator, the behavior is undefined.
 107         @param domain A string specifying the desired domain, such as the
 108                 requested configuration (kSCDynamicStoreDomainSetup) or the
 109                 actual state (kSCDynamicStoreDomainState).
 110         @result Returns a string containing the formatted key.
 111
 112  */
 113 CFStringRef
 114 SCDynamicStoreKeyCreateNetworkInterface         (
 115                                                 CFAllocatorRef  __nullable      allocator,
 116                                                 CFStringRef                     domain
 117                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
 118
 119 /*!
 120         @function SCDynamicStoreKeyCreateNetworkInterfaceEntity
 121         @discussion Creates a dynamic store key that can be used to access
 122                 the per-interface network configuration information stored in
 123                 the dynamic store.
 124         @param allocator The CFAllocator that should be used to allocate
 125                 memory for this key.
 126                 This parameter may be NULL in which case the current
 127                 default CFAllocator is used. If this reference is not
 128                 a valid CFAllocator, the behavior is undefined.
 129         @param domain A string specifying the desired domain, such as the
 130                 requested configuration (kSCDynamicStoreDomainSetup) or the
 131                 actual state (kSCDynamicStoreDomainState).
 132         @param ifname A string containing the interface name or a regular
 133                 expression pattern.
 134         @param entity A string containing the specific global entity, such
 135                 as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
 136         @result Returns a string containing the formatted key.
 137
 138  */
 139 CFStringRef
 140 SCDynamicStoreKeyCreateNetworkInterfaceEntity   (
 141                                                 CFAllocatorRef  __nullable      allocator,
 142                                                 CFStringRef                     domain,
 143                                                 CFStringRef                     ifname,
 144                                                 CFStringRef     __nullable      entity
 145                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
 146
 147 /*!
 148         @function SCDynamicStoreKeyCreateNetworkServiceEntity
 149         @discussion Creates a dynamic store key that can be used to access
 150                 the per-service network configuration information stored in
 151                 the dynamic store.
 152         @param allocator The CFAllocator that should be used to allocate
 153                 memory for this key.
 154                 This parameter may be NULL in which case the current
 155                 default CFAllocator is used. If this reference is not
 156                 a valid CFAllocator, the behavior is undefined.
 157         @param domain A string specifying the desired domain, such as the
 158                 requested configuration (kSCDynamicStoreDomainSetup) or the
 159                 actual state (kSCDynamicStoreDomainState).
 160         @param serviceID A string containing the service ID or a regular
 161                 expression pattern.
 162         @param entity A string containing the specific global entity, such
 163                 as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
 164         @result Returns a string containing the formatted key.
 165
 166
 167  */
 168 CFStringRef
 169 SCDynamicStoreKeyCreateNetworkServiceEntity     (
 170                                                 CFAllocatorRef  __nullable      allocator,
 171                                                 CFStringRef                     domain,
 172                                                 CFStringRef                     serviceID,
 173                                                 CFStringRef     __nullable      entity
 174                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
 175
 176 /*!
 177         @function SCDynamicStoreKeyCreateComputerName
 178         @discussion Creates a key that can be used in conjuntion with
 179                 SCDynamicStoreSetNotificationKeys function to receive
 180                 notifications when the current computer name changes.
 181         @param allocator The CFAllocator that should be used to allocate
 182                 memory for this key.
 183                 This parameter may be NULL in which case the current
 184                 default CFAllocator is used. If this reference is not
 185                 a valid CFAllocator, the behavior is undefined.
 186         @result Returns a notification string for the current computer or
 187                 host name.
 188 */
 189 CFStringRef
 190 SCDynamicStoreKeyCreateComputerName             (
 191                                                 CFAllocatorRef  __nullable      allocator
 192                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
 193
 194 /*!
 195         @function SCDynamicStoreKeyCreateConsoleUser
 196         @discussion Creates a key that can be used in conjunction with
 197                 SCDynamicStoreSetNotificationKeys function to receive
 198                 notifications when the current console user changes.
 199         @param allocator The CFAllocator that should be used to allocate
 200                 memory for this key.
 201                 This parameter may be NULL in which case the current
 202                 default CFAllocator is used. If this reference is not
 203                 a valid CFAllocator, the behavior is undefined.
 204         @result Returns a notification string for the current console user.
 205 */
 206 CFStringRef
 207 SCDynamicStoreKeyCreateConsoleUser              (
 208                                                 CFAllocatorRef  __nullable      allocator
 209                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_NA);
 210
 211 /*!
 212         @function SCDynamicStoreKeyCreateHostNames
 213         @discussion Creates a key that can be used in conjunction with the
 214                 SCDynamicStoreSetNotificationKeys function to receive
 215                 notifications when the HostNames entity changes.  The
 216                 HostNames entity includes the local host name.
 217         @param allocator The CFAllocator that should be used to allocate
 218                 memory for this key.
 219                 This parameter may be NULL in which case the current
 220                 default CFAllocator is used. If this reference is not
 221                 a valid CFAllocator, the behavior is undefined.
 222         @result Returns a notification string for the HostNames entity.
 223 */
 224 CFStringRef
 225 SCDynamicStoreKeyCreateHostNames                (
 226                                                 CFAllocatorRef  __nullable      allocator
 227                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0/*SPI*/);
 228
 229 /*!
 230         @function SCDynamicStoreKeyCreateLocation
 231         @discussion Creates a key that can be used in conjunction with the
 232                 SCDynamicStoreSetNotificationKeys function to receive
 233                 notifications when the location identifier changes.
 234         @param allocator The CFAllocator that should be used to allocate
 235                 memory for this key.
 236                 This parameter may be NULL in which case the current
 237                 default CFAllocator is used. If this reference is not
 238                 a valid CFAllocator, the behavior is undefined.
 239         @result Returns a notification string for the current location
 240                 identifier.
 241 */
 242 CFStringRef
 243 SCDynamicStoreKeyCreateLocation                 (
 244                                                 CFAllocatorRef  __nullable      allocator
 245                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0/*SPI*/);
 246
 247 /*!
 248         @function SCDynamicStoreKeyCreateProxies
 249         @discussion Creates a key that can be used in conjunction with
 250                 the SCDynamicStoreSetNotificationKeys function to receive
 251                 notifications when the current network proxy settings
 252                 (such as HTTP or FTP) are changed.
 253         @param allocator The CFAllocator that should be used to allocate
 254                 memory for this key.
 255                 This parameter may be NULL in which case the current
 256                 default CFAllocator is used. If this reference is not
 257                 a valid CFAllocator, the behavior is undefined.
 258         @result Returns a notification string for the current proxy settings.
 259 */
 260 CFStringRef
 261 SCDynamicStoreKeyCreateProxies                  (
 262                                                 CFAllocatorRef  __nullable      allocator
 263                                                 )               __OSX_AVAILABLE_STARTING(__MAC_10_1,__IPHONE_2_0/*SPI*/);
 264
 265 __END_DECLS
 266
 267 CF_ASSUME_NONNULL_END
 268 CF_IMPLICIT_BRIDGING_DISABLED
 269
 270 #endif  /* USE_SYSTEMCONFIGURATION_PRIVATE_HEADERS */
 271 #endif  /* _SCDYNAMICSTOREKEY_H */