configd-1061.40.2.tar.gz

[apple/configd.git] / SystemConfiguration.fproj / SCDynamicStoreKey.h

diff --git a/SystemConfiguration.fproj/SCDynamicStoreKey.h b/SystemConfiguration.fproj/SCDynamicStoreKey.h
index aa76284cbe47f042978a771d5c84fe957124217a..aa28274097475171bfb4d21ff730b8c542c51a88 100644 (file)
--- a/SystemConfiguration.fproj/SCDynamicStoreKey.h
+++ b/SystemConfiguration.fproj/SCDynamicStoreKey.h
@@ -1,21 +1,22 @@
 /*
 /*

- * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 2000-2002, 2004, 2005, 2008, 2015, 2018 Apple Inc. All rights reserved.

  *
  * @APPLE_LICENSE_HEADER_START@
  *
  *
  * @APPLE_LICENSE_HEADER_START@
  *

- * The contents of this file constitute Original Code as defined in and
- * are subject to the Apple Public Source License Version 1.1 (the
- * "License").  You may not use this file except in compliance with the
- * License.  Please obtain a copy of the License at
- * http://www.apple.com/publicsource and read it before using this file.
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.

  *
  *

- * This Original Code and all software distributed under the License are
- * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER

  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,

- * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
- * License for the specific language governing rights and limitations
- * under the License.
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.

  *
  * @APPLE_LICENSE_HEADER_END@
  */
  *
  * @APPLE_LICENSE_HEADER_END@
  */


@@ -23,110 +24,244 @@
 #ifndef _SCDYNAMICSTOREKEY_H
 #define _SCDYNAMICSTOREKEY_H
 
 #ifndef _SCDYNAMICSTOREKEY_H
 #define _SCDYNAMICSTOREKEY_H
 

+#include <os/availability.h>

 #include <sys/cdefs.h>
 #include <CoreFoundation/CoreFoundation.h>
 
 #include <sys/cdefs.h>
 #include <CoreFoundation/CoreFoundation.h>
 

+CF_IMPLICIT_BRIDGING_ENABLED
+CF_ASSUME_NONNULL_BEGIN

 
 /*!
        @header SCDynamicStoreKey
 
 /*!
        @header SCDynamicStoreKey

+       @discussion The SCDynamicStoreKey API provides convenience functions
+               that an application can use to create a correctly formatted
+               dynamic store key for accessing specific items in the dynamic
+               store.  An application can then use the resulting string in
+               any function that requires a dynamic store key.

  */
 
 
 __BEGIN_DECLS
 
 /*
  */
 
 
 __BEGIN_DECLS
 
 /*

- * SCDynamicStoreKeyCreate*
+ * SCDynamicStoreKeyCreate

  * - convenience routines that create a CFString key for an item in the store
  */
 
 /*!
        @function SCDynamicStoreKeyCreate
  * - convenience routines that create a CFString key for an item in the store
  */
 
 /*!
        @function SCDynamicStoreKeyCreate

-       @discussion Creates a store key using the given format.
+       @discussion Creates a dynamic store key using the given format.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @param fmt A CFStringRef describing the format for this key.
+       @result Returns a string containing the formatted key.

  */
 CFStringRef
 SCDynamicStoreKeyCreate                                (
  */
 CFStringRef
 SCDynamicStoreKeyCreate                                (

-                                               CFAllocatorRef  allocator,
-                                               CFStringRef     fmt,
+                                               CFAllocatorRef  __nullable      allocator,
+                                               CFStringRef                     fmt,

                                                ...
                                                ...

-                                               );
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateNetworkGlobalEntity
 
 /*!
        @function SCDynamicStoreKeyCreateNetworkGlobalEntity

+       @discussion Creates a dynamic store key that can be used to access
+               a specific global (as opposed to a per-service or per-interface)
+               network configuration entity.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @param domain A string specifying the desired domain, such as the
+               requested configuration (kSCDynamicStoreDomainSetup) or the
+               actual state (kSCDynamicStoreDomainState).
+       @param entity A string containing the specific global entity, such
+               as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
+       @result Returns a string containing the formatted key.
+

  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkGlobalEntity     (
  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkGlobalEntity     (

-                                               CFAllocatorRef  allocator,
-                                               CFStringRef     domain,
-                                               CFStringRef     entity
-                                               );
+                                               CFAllocatorRef  __nullable      allocator,
+                                               CFStringRef                     domain,
+                                               CFStringRef                     entity
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateNetworkInterface
 
 /*!
        @function SCDynamicStoreKeyCreateNetworkInterface

+       @discussion Creates a dynamic store key that can be used to access
+               the network interface configuration information stored in
+               the dynamic store.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @param domain A string specifying the desired domain, such as the
+               requested configuration (kSCDynamicStoreDomainSetup) or the
+               actual state (kSCDynamicStoreDomainState).
+       @result Returns a string containing the formatted key.
+

  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkInterface                (
  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkInterface                (

-                                               CFAllocatorRef  allocator,
-                                               CFStringRef     domain
-                                               );
+                                               CFAllocatorRef  __nullable      allocator,
+                                               CFStringRef                     domain
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateNetworkInterfaceEntity
 
 /*!
        @function SCDynamicStoreKeyCreateNetworkInterfaceEntity

+       @discussion Creates a dynamic store key that can be used to access
+               the per-interface network configuration information stored in
+               the dynamic store.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @param domain A string specifying the desired domain, such as the
+               requested configuration (kSCDynamicStoreDomainSetup) or the
+               actual state (kSCDynamicStoreDomainState).
+       @param ifname A string containing the interface name or a regular
+               expression pattern.
+       @param entity A string containing the specific global entity, such
+               as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
+       @result Returns a string containing the formatted key.
+

  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkInterfaceEntity  (
  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkInterfaceEntity  (

-                                               CFAllocatorRef  allocator,
-                                               CFStringRef     domain,
-                                               CFStringRef     ifname,
-                                               CFStringRef     entity
-                                               );
+                                               CFAllocatorRef  __nullable      allocator,
+                                               CFStringRef                     domain,
+                                               CFStringRef                     ifname,
+                                               CFStringRef     __nullable      entity
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateNetworkServiceEntity
 
 /*!
        @function SCDynamicStoreKeyCreateNetworkServiceEntity

+       @discussion Creates a dynamic store key that can be used to access
+               the per-service network configuration information stored in
+               the dynamic store.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @param domain A string specifying the desired domain, such as the
+               requested configuration (kSCDynamicStoreDomainSetup) or the
+               actual state (kSCDynamicStoreDomainState).
+       @param serviceID A string containing the service ID or a regular
+               expression pattern.
+       @param entity A string containing the specific global entity, such
+               as IPv4 (kSCEntNetIPv4) or DNS (kSCEntNetDNS).
+       @result Returns a string containing the formatted key.
+
+

  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkServiceEntity    (
  */
 CFStringRef
 SCDynamicStoreKeyCreateNetworkServiceEntity    (

-                                               CFAllocatorRef  allocator,
-                                               CFStringRef     domain,
-                                               CFStringRef     serviceID,
-                                               CFStringRef     entity
-                                               );
+                                               CFAllocatorRef  __nullable      allocator,
+                                               CFStringRef                     domain,
+                                               CFStringRef                     serviceID,
+                                               CFStringRef     __nullable      entity
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateComputerName
 
 /*!
        @function SCDynamicStoreKeyCreateComputerName

-       @discussion Creates a key that can be used by the SCDynamicStoreSetNotificationKeys()
-               function to receive notifications when the current
-               computer/host name changes.
-       @result A notification string for the current computer/host name.
+       @discussion Creates a key that can be used in conjuntion with
+               SCDynamicStoreSetNotificationKeys function to receive
+               notifications when the current computer name changes.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @result Returns a notification string for the current computer or
+               host name.

 */
 CFStringRef
 SCDynamicStoreKeyCreateComputerName            (
 */
 CFStringRef
 SCDynamicStoreKeyCreateComputerName            (

-                                               CFAllocatorRef          allocator
-                                               );
+                                               CFAllocatorRef  __nullable      allocator
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateConsoleUser
 
 /*!
        @function SCDynamicStoreKeyCreateConsoleUser

-       @discussion Creates a key that can be used by the SCDynamicStoreSetNotificationKeys()
-               function to receive notifications when the current "Console"
-               user changes.
-       @result A notification string for the current "Console" user.
+       @discussion Creates a key that can be used in conjunction with
+               SCDynamicStoreSetNotificationKeys function to receive
+               notifications when the current console user changes.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @result Returns a notification string for the current console user.

 */
 CFStringRef
 SCDynamicStoreKeyCreateConsoleUser             (
 */
 CFStringRef
 SCDynamicStoreKeyCreateConsoleUser             (

-                                               CFAllocatorRef          allocator
-                                               );
+                                               CFAllocatorRef  __nullable      allocator
+                                               )               API_AVAILABLE(macos(10.1)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos);
+
+/*!
+       @function SCDynamicStoreKeyCreateHostNames
+       @discussion Creates a key that can be used in conjunction with the
+               SCDynamicStoreSetNotificationKeys function to receive
+               notifications when the HostNames entity changes.  The
+               HostNames entity includes the local host name.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @result Returns a notification string for the HostNames entity.
+*/
+CFStringRef
+SCDynamicStoreKeyCreateHostNames               (
+                                               CFAllocatorRef  __nullable      allocator
+                                               )               API_AVAILABLE(macos(10.2)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));
+
+/*!
+       @function SCDynamicStoreKeyCreateLocation
+       @discussion Creates a key that can be used in conjunction with the
+               SCDynamicStoreSetNotificationKeys function to receive
+               notifications when the location identifier changes.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @result Returns a notification string for the current location
+               identifier.
+*/
+CFStringRef
+SCDynamicStoreKeyCreateLocation                        (
+                                               CFAllocatorRef  __nullable      allocator
+                                               )               API_AVAILABLE(macos(10.2)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 /*!
        @function SCDynamicStoreKeyCreateProxies
 
 /*!
        @function SCDynamicStoreKeyCreateProxies

-       @discussion Creates a key that can be used by the SCDynamicStoreSetNotificationKeys()
-               function to receive notifications when the current network proxy
-               settings (HTTP, FTP, ...) are changed.
-       @result A notification string for the current proxy settings.
+       @discussion Creates a key that can be used in conjunction with
+               the SCDynamicStoreSetNotificationKeys function to receive
+               notifications when the current network proxy settings
+               (such as HTTP or FTP) are changed.
+       @param allocator The CFAllocator that should be used to allocate
+               memory for this key.
+               This parameter may be NULL in which case the current
+               default CFAllocator is used. If this reference is not
+               a valid CFAllocator, the behavior is undefined.
+       @result Returns a notification string for the current proxy settings.

 */
 CFStringRef
 SCDynamicStoreKeyCreateProxies                 (
 */
 CFStringRef
 SCDynamicStoreKeyCreateProxies                 (

-                                               CFAllocatorRef          allocator
-                                               );
+                                               CFAllocatorRef  __nullable      allocator
+                                               )               API_AVAILABLE(macos(10.1)) SPI_AVAILABLE(ios(2.0), tvos(9.0), watchos(1.0), bridgeos(1.0));

 
 __END_DECLS
 
 
 __END_DECLS
 

-#endif /* _SCDYNAMICSTOREKEY_H */
+CF_ASSUME_NONNULL_END
+CF_IMPLICIT_BRIDGING_DISABLED
+
+#endif /* _SCDYNAMICSTOREKEY_H */