SystemConfiguration.fproj/SCDynamicStoreKey.h

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