X-Git-Url: https://git.saurik.com/apple/configd.git/blobdiff_plain/0fae82ee9e32dcee00597b75650c675a75eab32e..d94708881e41bd90afd74b1a1dd0524d039ba3f7:/SystemConfiguration.fproj/SCDynamicStoreKey.h?ds=inline diff --git a/SystemConfiguration.fproj/SCDynamicStoreKey.h b/SystemConfiguration.fproj/SCDynamicStoreKey.h index aa76284..aa28274 100644 --- 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@ * - * 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, - * 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@ */ @@ -23,110 +24,244 @@ #ifndef _SCDYNAMICSTOREKEY_H #define _SCDYNAMICSTOREKEY_H +#include #include #include +CF_IMPLICIT_BRIDGING_ENABLED +CF_ASSUME_NONNULL_BEGIN /*! @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 /* - * SCDynamicStoreKeyCreate* + * 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 ( - 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 + @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 ( - 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 + @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 ( - 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 + @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 ( - 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 + @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 ( - 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 - @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 ( - 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 - @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 ( - 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 - @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 ( - 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 -#endif /* _SCDYNAMICSTOREKEY_H */ +CF_ASSUME_NONNULL_END +CF_IMPLICIT_BRIDGING_DISABLED + +#endif /* _SCDYNAMICSTOREKEY_H */