libs-corebase — CoreFoundation gaps for WebKit Sub-plan

Overview

WebKit functions called

• CFNotificationCenterGetLocalCenter() — by far the most common; used in nearly every observer registration
• CFNotificationCenterAddObserver() — registers a C callback for a named notification
• CFNotificationCenterRemoveObserver() — deregisters an observer
• CFNotificationCenterRemoveEveryObserver() — bulk removal
• CFNotificationCenterPostNotification() — fires a notification with optional userInfo dictionary
• CFNotificationCenterGetDistributedCenter() — less critical; used for cross-process notifications (not required for the minimal build but trivial to add)

Implementation strategy

Wrap NSNotificationCenter from gnustep-base. The CF notification center is a thin veneer over the Objective-C notification system. The local center maps 1:1 to [NSNotificationCenter defaultCenter]. The distributed center maps to [NSDistributedNotificationCenter defaultCenter], which gnustep-base already implements.

The tricky part is adapting the C callback signature. CF observers use the signature:

typedef void (*CFNotificationCallback)(
    CFNotificationCenterRef center,
    void *observer,
    CFNotificationName name,
    const void *object,
    CFDictionaryRef userInfo
);

Each registered observer must be wrapped in an Objective-C block or NSObject shim that bridges NSNotification to the CF callback. The shim holds the CF callback pointer, the observer pointer, and the suspension behavior. Use a global CFMutableDictionaryRef (keyed by observer+name+center triplet) to track shims for removal.

Key constants to define

/* Suspension behavior when app is in background */
typedef CF_ENUM(CFIndex, CFNotificationSuspensionBehavior) {
    CFNotificationSuspensionBehaviorDrop                = 1,
    CFNotificationSuspensionBehaviorCoalesce            = 2,
    CFNotificationSuspensionBehaviorHold                = 3,
    CFNotificationSuspensionBehaviorDeliverImmediately  = 4
};

/* Options for CFNotificationCenterPostNotification */
typedef CF_OPTIONS(CFOptionFlags, CFNotificationPostOptions) {
    kCFNotificationPostToAllSessions = (1 << 0)
};

Complete function signatures to implement

/* CFNotificationCenter.h */

CF_EXPORT CFTypeID CFNotificationCenterGetTypeID(void);

CF_EXPORT CFNotificationCenterRef CFNotificationCenterGetLocalCenter(void);
CF_EXPORT CFNotificationCenterRef CFNotificationCenterGetDistributedCenter(void);
CF_EXPORT CFNotificationCenterRef CFNotificationCenterGetDarwinNotifyCenter(void);

CF_EXPORT void CFNotificationCenterAddObserver(
    CFNotificationCenterRef center,
    const void *observer,
    CFNotificationCallback callBack,
    CFStringRef name,
    const void *object,
    CFNotificationSuspensionBehavior suspensionBehavior
);

CF_EXPORT void CFNotificationCenterRemoveObserver(
    CFNotificationCenterRef center,
    const void *observer,
    CFNotificationName name,
    const void *object
);

CF_EXPORT void CFNotificationCenterRemoveEveryObserver(
    CFNotificationCenterRef center,
    const void *observer
);

CF_EXPORT void CFNotificationCenterPostNotification(
    CFNotificationCenterRef center,
    CFNotificationName name,
    const void *object,
    CFDictionaryRef userInfo,
    Boolean deliverImmediately
);

CF_EXPORT void CFNotificationCenterPostNotificationWithOptions(
    CFNotificationCenterRef center,
    CFNotificationName name,
    const void *object,
    CFDictionaryRef userInfo,
    CFOptionFlags options
);

Key implementation sketch (CFNotificationCenter.c)

#import <Foundation/NSNotificationCenter.h>
#import <Foundation/NSDistributedNotificationCenter.h>
#import <Foundation/NSDictionary.h>
#import <Foundation/NSString.h>
#include "CFNotificationCenter.h"
#include "CFInternal.h"

/* Observer shim: bridges NSNotification -> CF callback */
@interface _CFNotificationObserver : NSObject {
@public
    CFNotificationCallback  _callback;
    void                   *_observer;
    CFNotificationCenterRef _center;
}
- (void)handleNotification:(NSNotification *)note;
@end

static CFNotificationCenterRef __localCenter    = NULL;
static CFNotificationCenterRef __distCenter     = NULL;
static pthread_mutex_t         __centerLock     = PTHREAD_MUTEX_INITIALIZER;

/* Global map: (observer ptr, name string) -> _CFNotificationObserver */
static CFMutableDictionaryRef  __observerMap    = NULL;

CFNotificationCenterRef CFNotificationCenterGetLocalCenter(void)
{
    pthread_mutex_lock(&__centerLock);
    if (!__localCenter) {
        /* Allocate a CF runtime instance wrapping [NSNotificationCenter defaultCenter] */
        __localCenter = _CFNotificationCenterCreate(kCFNotificationCenterLocal);
    }
    pthread_mutex_unlock(&__centerLock);
    return __localCenter;
}

CFNotificationCenterRef CFNotificationCenterGetDistributedCenter(void)
{
    pthread_mutex_lock(&__centerLock);
    if (!__distCenter) {
        __distCenter = _CFNotificationCenterCreate(kCFNotificationCenterDistributed);
    }
    pthread_mutex_unlock(&__centerLock);
    return __distCenter;
}

void CFNotificationCenterAddObserver(
    CFNotificationCenterRef center,
    const void *observer,
    CFNotificationCallback callBack,
    CFStringRef name,
    const void *object,
    CFNotificationSuspensionBehavior suspensionBehavior)
{
    _CFNotificationObserver *shim = [[_CFNotificationObserver alloc] init];
    shim->_callback = callBack;
    shim->_observer = (void *)observer;
    shim->_center   = center;

    NSString *nsName = name ? (NSString *)name : nil;
    NSNotificationCenter *nc = _CFNotificationCenterGetNSCenter(center);
    [nc addObserver:shim
           selector:@selector(handleNotification:)
               name:nsName
             object:nil];

    /* Store shim for later removal */
    _CFNotificationMapStore(center, observer, name, shim);
}

void CFNotificationCenterPostNotification(
    CFNotificationCenterRef center,
    CFNotificationName name,
    const void *object,
    CFDictionaryRef userInfo,
    Boolean deliverImmediately)
{
    NSNotificationCenter *nc = _CFNotificationCenterGetNSCenter(center);
    NSString *nsName = (NSString *)name;
    NSDictionary *nsInfo = (NSDictionary *)userInfo;
    [nc postNotificationName:nsName object:nil userInfo:nsInfo];
}

Overview

WebKit functions called

• CFPreferencesCopyAppValue(key, appID) — read a value for the current app (most common)
• CFPreferencesGetAppBooleanValue(key, appID, keyExistsAndHasValidFormat) — typed boolean read
• CFPreferencesGetAppIntegerValue(key, appID, keyExistsAndHasValidFormat) — typed integer read
• CFPreferencesSetAppValue(key, value, appID) — write a value
• CFPreferencesAppSynchronize(appID) — flush to disk
• CFPreferencesCopyValue(key, appID, user, host) — multi-domain read (less common)
• CFPreferencesSetValue(key, value, appID, user, host) — multi-domain write
• CFPreferencesSynchronize(appID, user, host) — flush multi-domain
• CFPreferencesCopyKeyList(appID, user, host) — enumerate keys
• CFPreferencesCopyMultiple(keysToFetch, appID, user, host) — bulk read

Implementation strategy

Wrap NSUserDefaults. The mapping is direct and complete:

• kCFPreferencesCurrentApplication → [NSUserDefaults standardUserDefaults]
• kCFPreferencesAnyApplication → the NSGlobalDomain (accessed via -persistentDomainForName:NSGlobalDomain)
• kCFPreferencesCurrentUser / kCFPreferencesAnyUser → irrelevant on non-macOS; map to the standard defaults
• kCFPreferencesCurrentHost / kCFPreferencesAnyHost → map to the standard defaults (host-level prefs are a macOS-specific concept)

The appID parameter in most calls is a bundle identifier string (kCFPreferencesCurrentApplication is a sentinel). When the sentinel is passed, use [NSUserDefaults standardUserDefaults] directly. When a real bundle ID is passed, use [[NSUserDefaults alloc] initWithSuiteName:bundleID].

Key constants to define

/* Sentinel strings — defined as extern CFStringRef, initialized to static values */
CF_EXPORT const CFStringRef kCFPreferencesAnyApplication;
CF_EXPORT const CFStringRef kCFPreferencesCurrentApplication;
CF_EXPORT const CFStringRef kCFPreferencesAnyHost;
CF_EXPORT const CFStringRef kCFPreferencesCurrentHost;
CF_EXPORT const CFStringRef kCFPreferencesAnyUser;
CF_EXPORT const CFStringRef kCFPreferencesCurrentUser;

Complete function signatures to implement

/* CFPreferences.h */

/* Per-app read/write (most common in WebKit) */
CF_EXPORT CFTypeRef CFPreferencesCopyAppValue(
    CFStringRef key,
    CFStringRef applicationID
);

CF_EXPORT Boolean CFPreferencesGetAppBooleanValue(
    CFStringRef key,
    CFStringRef applicationID,
    Boolean *keyExistsAndHasValidFormat   /* may be NULL */
);

CF_EXPORT CFIndex CFPreferencesGetAppIntegerValue(
    CFStringRef key,
    CFStringRef applicationID,
    Boolean *keyExistsAndHasValidFormat   /* may be NULL */
);

CF_EXPORT void CFPreferencesSetAppValue(
    CFStringRef key,
    CFTypeRef value,                      /* pass NULL to remove */
    CFStringRef applicationID
);

CF_EXPORT Boolean CFPreferencesAppSynchronize(
    CFStringRef applicationID
);

CF_EXPORT Boolean CFPreferencesAppValueIsForced(
    CFStringRef key,
    CFStringRef applicationID
);

/* Multi-domain read/write */
CF_EXPORT CFTypeRef CFPreferencesCopyValue(
    CFStringRef key,
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT void CFPreferencesSetValue(
    CFStringRef key,
    CFTypeRef value,
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT Boolean CFPreferencesSynchronize(
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT CFArrayRef CFPreferencesCopyApplicationList(
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT CFDictionaryRef CFPreferencesCopyMultiple(
    CFArrayRef keysToFetch,               /* pass NULL for all keys */
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT void CFPreferencesSetMultiple(
    CFDictionaryRef keysToSet,
    CFArrayRef keysToRemove,
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

CF_EXPORT CFArrayRef CFPreferencesCopyKeyList(
    CFStringRef applicationID,
    CFStringRef userName,
    CFStringRef hostName
);

Key implementation sketch (CFPreferences.c)

#import <Foundation/NSUserDefaults.h>
#import <Foundation/NSString.h>
#import <Foundation/NSNumber.h>
#include "CFPreferences.h"
#include "CFString.h"

const CFStringRef kCFPreferencesCurrentApplication =
    (CFStringRef)@"kCFPreferencesCurrentApplication";
const CFStringRef kCFPreferencesAnyApplication =
    (CFStringRef)@"kCFPreferencesAnyApplication";
const CFStringRef kCFPreferencesCurrentUser =
    (CFStringRef)@"kCFPreferencesCurrentUser";
const CFStringRef kCFPreferencesAnyUser =
    (CFStringRef)@"kCFPreferencesAnyUser";
const CFStringRef kCFPreferencesCurrentHost =
    (CFStringRef)@"kCFPreferencesCurrentHost";
const CFStringRef kCFPreferencesAnyHost =
    (CFStringRef)@"kCFPreferencesAnyHost";

static NSUserDefaults *_defaultsForAppID(CFStringRef applicationID)
{
    if (applicationID == kCFPreferencesCurrentApplication
        || [(NSString *)applicationID isEqualToString:
               (NSString *)kCFPreferencesCurrentApplication])
        return [NSUserDefaults standardUserDefaults];

    /* Named suite — note: NSUserDefaults initWithSuiteName: is available
       in gnustep-base and behaves like a per-bundle defaults domain. */
    return [[[NSUserDefaults alloc]
               initWithSuiteName:(NSString *)applicationID] autorelease];
}

CFTypeRef CFPreferencesCopyAppValue(CFStringRef key, CFStringRef applicationID)
{
    NSUserDefaults *ud = _defaultsForAppID(applicationID);
    id value = [ud objectForKey:(NSString *)key];
    if (!value) return NULL;
    CFRetain((CFTypeRef)value);
    return (CFTypeRef)value;
}

Boolean CFPreferencesGetAppBooleanValue(
    CFStringRef key, CFStringRef applicationID, Boolean *keyExists)
{
    NSUserDefaults *ud = _defaultsForAppID(applicationID);
    id value = [ud objectForKey:(NSString *)key];
    if (!value) {
        if (keyExists) *keyExists = false;
        return false;
    }
    if (keyExists) *keyExists = true;
    return [ud boolForKey:(NSString *)key];
}

CFIndex CFPreferencesGetAppIntegerValue(
    CFStringRef key, CFStringRef applicationID, Boolean *keyExists)
{
    NSUserDefaults *ud = _defaultsForAppID(applicationID);
    id value = [ud objectForKey:(NSString *)key];
    if (!value) {
        if (keyExists) *keyExists = false;
        return 0;
    }
    if (keyExists) *keyExists = true;
    return (CFIndex)[ud integerForKey:(NSString *)key];
}

void CFPreferencesSetAppValue(
    CFStringRef key, CFTypeRef value, CFStringRef applicationID)
{
    NSUserDefaults *ud = _defaultsForAppID(applicationID);
    if (value)
        [ud setObject:(id)value forKey:(NSString *)key];
    else
        [ud removeObjectForKey:(NSString *)key];
}

Boolean CFPreferencesAppSynchronize(CFStringRef applicationID)
{
    NSUserDefaults *ud = _defaultsForAppID(applicationID);
    [ud synchronize];
    return true;
}

Overview

WebKit functions called

• CFStringTokenizerCreate(allocator, string, range, unit, locale) — construct a tokenizer for a string
• CFStringTokenizerSetString(tokenizer, string, range) — replace the string being tokenized
• CFStringTokenizerAdvanceToNextToken(tokenizer) — move to the next token; returns token type flags
• CFStringTokenizerGoToTokenAtIndex(tokenizer, index) — seek to the token at a character index
• CFStringTokenizerGetCurrentTokenRange(tokenizer) — returns CFRange of the current token
• CFStringTokenizerCopyCurrentTokenAttribute(tokenizer, attribute) — returns language, script, or stem data for the token

ICU mapping

ICU's UBreakIterator API, available in <unicode/ubrk.h>, implements exactly the same concept. The unit constants map as follows:

ICU uses UTF-16 internally, matching CoreFoundation's native encoding. The string passed to the tokenizer must be extracted as a UTF-16 buffer (CFStringGetCharactersPtr or CFStringGetCharacters) and held for the lifetime of the iterator.

Key constants and types to define

typedef CF_OPTIONS(CFOptionFlags, CFStringTokenizerTokenType) {
    kCFStringTokenizerTokenNone                 = 0,
    kCFStringTokenizerTokenNormal               = 1UL << 0,
    kCFStringTokenizerTokenHasSubTokensMask     = 1UL << 1,
    kCFStringTokenizerTokenHasDerivedSubTokensMask = 1UL << 2,
    kCFStringTokenizerTokenHasHasNumbersMask    = 1UL << 3,
    kCFStringTokenizerTokenHasNonLettersMask    = 1UL << 4,
    kCFStringTokenizerTokenIsCJWordMask         = 1UL << 5
};

/* Unit options for CFStringTokenizerCreate */
typedef CF_OPTIONS(CFOptionFlags, CFStringTokenizerUnit) {
    kCFStringTokenizerUnitWord          = 0,
    kCFStringTokenizerUnitSentence      = 1,
    kCFStringTokenizerUnitParagraph     = 2,
    kCFStringTokenizerUnitLineBreak     = 3,
    kCFStringTokenizerUnitWordBoundary  = (1UL << 4) | kCFStringTokenizerUnitWord
};

/* Attribute keys for CFStringTokenizerCopyCurrentTokenAttribute */
CF_EXPORT const CFStringRef kCFStringTokenizerAttributeLatinTranscription;
CF_EXPORT const CFStringRef kCFStringTokenizerAttributeLanguage;

Complete function signatures to implement

/* CFStringTokenizer.h */

CF_EXPORT CFTypeID CFStringTokenizerGetTypeID(void);

CF_EXPORT CFStringTokenizerRef CFStringTokenizerCreate(
    CFAllocatorRef alloc,
    CFStringRef string,
    CFRange range,
    CFOptionFlags unit,
    CFLocaleRef locale
);

CF_EXPORT void CFStringTokenizerSetString(
    CFStringTokenizerRef tokenizer,
    CFStringRef string,
    CFRange range
);

CF_EXPORT CFStringTokenizerTokenType CFStringTokenizerAdvanceToNextToken(
    CFStringTokenizerRef tokenizer
);

CF_EXPORT CFStringTokenizerTokenType CFStringTokenizerGoToTokenAtIndex(
    CFStringTokenizerRef tokenizer,
    CFIndex index
);

CF_EXPORT CFRange CFStringTokenizerGetCurrentTokenRange(
    CFStringTokenizerRef tokenizer
);

CF_EXPORT CFTypeRef CFStringTokenizerCopyCurrentTokenAttribute(
    CFStringTokenizerRef tokenizer,
    CFOptionFlags attribute
);

CF_EXPORT CFIndex CFStringTokenizerGetCurrentSubTokens(
    CFStringTokenizerRef tokenizer,
    CFRange *ranges,
    CFIndex maxRangeLength,
    CFMutableArrayRef derivedSubTokens   /* may be NULL */
);

Key implementation sketch (CFStringTokenizer.c)

#include <unicode/ubrk.h>
#include <unicode/uloc.h>
#include "CFStringTokenizer.h"
#include "CFRuntime.h"
#include "CFString.h"
#include "CFLocale.h"

typedef struct __CFStringTokenizer {
    CFRuntimeBase      _base;
    UBreakIterator    *_brk;          /* ICU break iterator          */
    UniChar           *_buf;          /* UTF-16 copy of the string   */
    CFIndex            _bufLen;
    CFRange            _range;        /* subrange within the string  */
    CFOptionFlags      _unit;
    int32_t            _current;      /* current break position      */
    int32_t            _tokenEnd;     /* end of current token        */
} __CFStringTokenizer;

static UBreakIteratorType _unitToICU(CFOptionFlags unit)
{
    switch (unit & 0xF) {
        case kCFStringTokenizerUnitSentence:    return UBRK_SENTENCE;
        case kCFStringTokenizerUnitParagraph:   return UBRK_LINE;
        case kCFStringTokenizerUnitLineBreak:   return UBRK_LINE;
        default:                                return UBRK_WORD;
    }
}

CFStringTokenizerRef CFStringTokenizerCreate(
    CFAllocatorRef alloc, CFStringRef string,
    CFRange range, CFOptionFlags unit, CFLocaleRef locale)
{
    __CFStringTokenizer *t = (__CFStringTokenizer *)_CFRuntimeCreateInstance(
        alloc, CFStringTokenizerGetTypeID(),
        sizeof(__CFStringTokenizer) - sizeof(CFRuntimeBase), NULL);
    if (!t) return NULL;

    /* Extract UTF-16 buffer */
    CFIndex len = range.length;
    t->_buf    = (UniChar *)CFAllocatorAllocate(alloc, len * sizeof(UniChar), 0);
    t->_bufLen = len;
    CFStringGetCharacters(string, range, t->_buf);

    /* Locale string for ICU */
    const char *locStr = "en";
    if (locale) {
        CFStringRef locID = CFLocaleGetIdentifier(locale);
        char tmp[64];
        if (CFStringGetCString(locID, tmp, sizeof(tmp), kCFStringEncodingUTF8))
            locStr = tmp;  /* safe: ICU copies it */
    }

    UErrorCode err = U_ZERO_ERROR;
    t->_brk = ubrk_openUChars(_unitToICU(unit),
                               locStr,
                               (UChar *)t->_buf, (int32_t)len,
                               &err);
    t->_unit    = unit;
    t->_range   = range;
    t->_current = 0;
    t->_tokenEnd = 0;
    return (CFStringTokenizerRef)t;
}

CFStringTokenizerTokenType CFStringTokenizerAdvanceToNextToken(
    CFStringTokenizerRef tokenizer)
{
    __CFStringTokenizer *t = (__CFStringTokenizer *)tokenizer;
    if (!t->_brk) return kCFStringTokenizerTokenNone;

    int32_t start = t->_tokenEnd;
    int32_t end   = ubrk_nextBoundary(t->_brk);
    if (end == UBRK_DONE) {
        t->_current  = (int32_t)t->_bufLen;
        t->_tokenEnd = (int32_t)t->_bufLen;
        return kCFStringTokenizerTokenNone;
    }
    t->_current  = start;
    t->_tokenEnd = end;
    return kCFStringTokenizerTokenNormal;
}

CFRange CFStringTokenizerGetCurrentTokenRange(CFStringTokenizerRef tokenizer)
{
    __CFStringTokenizer *t = (__CFStringTokenizer *)tokenizer;
    if (t->_current == t->_tokenEnd)
        return CFRangeMake(kCFNotFound, 0);
    return CFRangeMake(
        t->_range.location + t->_current,
        t->_tokenEnd - t->_current);
}

CFStringTokenizerTokenType CFStringTokenizerGoToTokenAtIndex(
    CFStringTokenizerRef tokenizer, CFIndex index)
{
    __CFStringTokenizer *t = (__CFStringTokenizer *)tokenizer;
    if (!t->_brk) return kCFStringTokenizerTokenNone;

    /* Seek ICU iterator */
    int32_t pos = (int32_t)(index - t->_range.location);
    if (pos < 0 || pos >= (int32_t)t->_bufLen)
        return kCFStringTokenizerTokenNone;

    ubrk_isBoundary(t->_brk, pos);   /* positions the iterator */
    int32_t start = ubrk_previous(t->_brk);
    if (start == UBRK_DONE) start = 0;
    int32_t end   = ubrk_nextBoundary(t->_brk);
    if (end == UBRK_DONE) return kCFStringTokenizerTokenNone;

    t->_current  = start;
    t->_tokenEnd = end;
    return kCFStringTokenizerTokenNormal;
}