CF-196 - 10.0 “Cheetah”#

The following came from the ADC release notes page.

API Changes Since Mac OS X Public Beta Summary#

New Header Files#

  • CFPlugInCOM.h

New Functions#

  • CFBundle.h: CFBundleGetDataPointerForName

  • CFBundle.h: CFBundleGetDataPointersForNames

  • CFMachPort.h: CFMachPortGetInvalidationCallBack

  • CFMachPort.h: CFMachPortSetInvalidationCallBack

  • CFMessagePort.h: CFMessagePortInvalidationCallBack

  • CFMessagePort.h: CFMessagePortSetInvalidationCallBack

  • CFRunLoop.h: CFRunLoopAddCommonMode

  • CFURL.h: CFURLCreateStringByAddingPercentEscapes

  • CFUserNotification.h: CFUserNotificationUpdate

  • CFXMLParser.h: CFXMLParserGetTypeID (previously missing from header)

New Types#

  • CFMachPort.h: CFMachPortInvalidationCallBack (function type)

  • CFMessagePort.h: CFMessagePortInvalidationCallBack (function type)

New Constants#

  • CFMessagePort.h: kCFMessagePortIsInvalid (error code)

  • CFMessagePort.h: kCFMessagePortTransportError (error code)

  • CFRunLoop.h: kCFRunLoopCommonModes (special mode indicator)

  • CFSocket.h: kCFSocketConnectCallBack (option)

  • CFUserNotification.h: kCFUserNotificationNoDefaultButtonFlag (option flag)

  • CFUserNotification.h: kCFUserNotificationPopUpTitlesKey (dictionary key)

Modified API#

The macros CFUserNotificationCheckBoxChecked, CFUserNotificationSecureTextField, and CFUserNotificationPopUpSelection in CFUserNotification.h have been converted to inline functions.

Removed API#

  • CFMachPort.h: CFMachPortInvalidateAll (function)

  • CFRunLoop.h: kCFRunLoopAnyMode (special mode indicator)

  • CFSocket.h: INVALID_SOCKET (macro)

CFBundle#

CFBundle has new API for looking up data symbols (as opposed to function pointers):

void *CFBundleGetDataPointerForName(CFBundleRef bundle,
                CFStringRef symbolName);
void CFBundleGetDataPointersForNames(CFBundleRef bundle,
                CFArrayRef symbolNames,
                void *stbl[]);

CFPlugIn COM definitions#

A number of convenience definitions of various COM-related items (HRESULT, STDMETHODCALLTYPE, IUnknown, etc.) have been moved out of CFPlugIn.h into a new header, CFPlugInCOM.h, to avoid collisions in contexts that include CoreFoundation.h but do not require these definitions. In situations requiring these definitions, it will be necessary to include CFPlugInCOM.h explicitly. To do so in a way that will work on systems both before and after these changes, use:

#if COREFOUNDATION_CFPLUGINCOM_SEPARATE
#include <CoreFoundation/CFPlugInCOM.h>
#endif

The User’s Localization Preference#

The user’s preference order for localizations is stored in the AppleLanguages user default. The value for this should be an array of strings. In the past, the strings in this array have typically been language names (“English”, “French”, etc.). However, the preferred forms for the strings in this array, and the forms in which they are likely to appear in future, are either as language abbreviations (“en”, “fr”, etc.) or as locale abbreviations (“en_US”, “fr_CA”, etc.). Anyone using the value of this default directly must be prepared to accept any of these forms. Direct use of the default is discouraged; in most cases, NSBundle or CFBundle APIs should suffice. See the CFBundle documentation for more details on languages, locales, and localizations.

Invalidation API Added to CFMachPort and CFMessagePort#

New function types and two new functions each have been added to the CFMachPort and CFMessagePort APIs, to get and set an invalidation callback function on instances of CFMachPort and CFMessagePort. This callback is called when the CFMachPort or CFMessagePort becomes invalid, either explicitly (because the CF*Invalidate() function has been called on it) or implicitly (the instance is about to be destroyed, or the resources underlying have become invalid).

You should not do anything in the invalidation callback which could create a new reference to the instance being invalidated. For example, you should be careful about passing the instance ref into any function, unless you own that function, because the function may take a reference to the instance. If the instance is about to be destroyed, there is no way to stop that; in particular, retaining the instance will not stop its destruction.

CFRunLoop Common Modes#

CFRunLoop now defines a facility for identifying a run loop mode as a “common mode”. A common mode is a mode that is normal for an app to be running in, and which should be “public”, in the sense that it is OK for arbitrary code to put run loop sources, timers, and observers into it. A “private” mode, on the other hand, would not be made a common mode, and would usually be used to briefly monitor one or two particular input source until something happened with them.

To mark a run loop mode as a common mode for a particular run loop, use the CFRunLoopAddCommonMode() function. This operation is not reversible.

To an an input source to a run loop, so that it is monitored whenever the run loop is being monitored in one of the common modes, pass the new constant kCFRunLoopCommonModes as the mode argument.

An old constant kCFRunLoopAnyMode has been removed from the CFRunLoop API. It was going to define a facility similar to the common modes facility, but was never implemented.

CFSocket#

CFSocket now contains provisions for allowing connections to proceed in the background. See CFSocket.h for further details.

CFURL#

CFURL is no longer be tolerant of malformed strings or byte sequences, so that the functions CFURLCreateWithString() and CFURLCreateWithBytes() will now return NULL if called with a string or byte sequence that does not satisfy the definition of an URL, according to RFC 2396. This was done to avoid later failures, so that clients may be assured that any valid CFURL instance represents a valid URL. Clients should be sure to check for NULL returns from these functions and gracefully handle the failure.

Note that clients using CFURL merely to wrap file system paths should not be affected by this change; whenever creating a CFURL for a file system path, use one of the creation functions with the term “FileSystem” in their names. These functions will properly map file system paths to their URL equivalent. Likewise, whenever extracting a file system path, be sure to use “FileSystem” named functions to perform the extraction. File system paths and URL paths are subtly different, and are not exchangable.

There is new API to help clients that wish to be tolerant of bad URL strings, particularly strings that contain high-bit or other problematic characters:

CFStringRef CFURLCreateStringByAddingPercentEscapes(
        CFAllocatorRef allocator,
        CFStringRef originalString,
        CFStringRef charactersToLeaveUnescaped,
        CFStringRef legalURLCharactersToBeEscaped,
        CFStringEncoding encoding);

Typical clients will call this as CFURLCreateStringByAddingPercentEscapes(NULL, origString, NULL, NULL, kCFStringEncodingUTF8) to produce the new URL string; this will replace all syntactically insignificant characters needing percent escapes in origString with the equivalent percent escape sequence(s). If a URL cannot be created from the resulting string, this means there is a syntactic problem with the string provided (probably a malformed percent escape sequence - a percent sign not followed by 2 hex digits, or a percent sequence or series of percent sequences that doesn’t represent a valid UTF8 character). For further details, see the comment preceding the function prototype in CFURL.h.

Property Lists#

Old style property lists have been deprecated and should not be used any longer. For compatibility reasons, in existing files, slashed characters (\nnn) will continue to be interpreted as an octal number representing a character in the old NextStep encoding. Characters above 127 should not be included in old style property lists.

CFString#

Empty String Handling#

CFStringFindWithOptions() and all routines based on it (such as CFStringHasPrefix()) now fail (that is, return NO, or whatever indicates “not found”) in the case where the string argument being searched for is the empty string (zero length). Previously the result of this operation was undefined.

High-bit Characters in CFSTR()#

CFSTR() used to interpret its contents using the default system encoding, which made it’s behavior rather unpredictable. It now always uses MacRoman, but also spits out a log warning against using non 7-bit characters in CFSTR(). In the future we are looking at enabling UTF-8 as the only allowed encoding in CFSTR().

Mutating Mutable Strings#

Mutating a mutable string with a string argument that is itself might not work correctly in all cases.

Reordering Arguments to Format Specs#

CFStringCreateWithFormat() does not work properly when missing a reordering (n$) argument. If you are going to use reordering arguments, you should use them on all of the %-specs, and there should be as many arguments in the function as there are % specs.

kCFCompareNonliteral#

The kCFCompareNonliteral flag to CFStringCompareWithOptions() and CFStringFindWithOptions() now works as expected. That is, two equivalent strings, one non-decomposed and one canonical, will be evaluated to be equal.

Yen Character in the MacJapanese Encoding#

The kCFStringEncodingMacJapanese encoding converter now uses the official mapping. It maps backslash (0x5C) to yen sign (U+00A5) and 0x80 to backslash (U+005C) and vice versa.

Non-lossy Unicode Character Formatting#

Where used, the kCFStringEncodingNonLossyASCII option now creates hex representations of Unicode characters (\u++++ format) in all lower case. This was a bug that it should be all lowercase (the initial ‘u’ was for a long time) to be compatible with the industry de-facto standard (Microsoft software & Java). The decoder now understands any lower/uppercase combination.