SystemConfiguration.fproj/SCDynamicStoreKey.h

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