SystemConfiguration.fproj/SCDynamicStoreKey.h

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