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 25c96a75081718355bf1f37877962fd7e7d63c71..aa28274097475171bfb4d21ff730b8c542c51a88 100644 (file)
--- a/SystemConfiguration.fproj/SCDynamicStoreKey.h
+++ b/SystemConfiguration.fproj/SCDynamicStoreKey.h
@@ -1,17 +1,15 @@
 /*
 /*

- * Copyright (c) 2000-2002 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@

- * 
- * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
- * 
+ *

  * 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 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.

- * 
+ *

  * 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,
  * 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,


@@ -19,142 +17,251 @@
  * 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.
  * 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@
  */
 
 #ifndef _SCDYNAMICSTOREKEY_H
 #define _SCDYNAMICSTOREKEY_H
 
  * @APPLE_LICENSE_HEADER_END@
  */
 
 #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
 
 /*!
        @function SCDynamicStoreKeyCreateHostNames

-       @discussion Creates a key that can be used in conjunction with
-               SCDynamicStoreSetNotificationKeys() to receive
+       @discussion Creates a key that can be used in conjunction with the
+               SCDynamicStoreSetNotificationKeys function to receive

                notifications when the HostNames entity changes.  The
                notifications when the HostNames entity changes.  The

-               HostNames entity contains the LocalHostName.
-       @result A notification string for the HostNames entity.
+               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               (
 */
 CFStringRef
 SCDynamicStoreKeyCreateHostNames               (

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

 
 /*!
        @function SCDynamicStoreKeyCreateLocation
 
 /*!
        @function SCDynamicStoreKeyCreateLocation

-       @discussion Creates a key that can be used in conjunction with
-               SCDynamicStoreSetNotificationKeys() to receive
-               notifications when the "location" identifier changes.
-       @result A notification string for the current "location" identifier.
+       @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                        (
 */
 CFStringRef
 SCDynamicStoreKeyCreateLocation                        (

-                                               CFAllocatorRef          allocator
-                                               );
+                                               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 */