Core What?

Core What?
Chris Adamson • @invalidname
CocoaConf
Mar 17, 2012 • Chicago, IL

Monday, March 19, 12

Core Foundation


Core Foundation

“Core Foundation is a library with a set of
programming interfaces conceptually derived
from the Objective-C-based Foundation
framework but implemented in the C language.”


CF Concepts
• Opaque Types

• Naming Conventions

• Memory-management conventions

• Relationship to Foundation ("toll free
bridging")


Opaque Types
• References (pointers) to structs you cannot
directly access

• Not a “class”, per se. Gives you
implementation hiding but not (much)
polymorphism

• Individual instances are still “objects”


Naming Conventions
• Opaque type references end in "Ref":
CFArrayRef, CFStringRef, etc.

• Functions that take a type start with that
type's name: CFStringGetLength(),
CFArrayGetObjectAtIndex()

• Functions take target object as ﬁrst parameter
(sometimes second, as in Create functions)


Memory Management
• You own or co-own an object by getting a reference
to it by any function with Create or Copy in its name,
or by explicitly calling CFRetain()

• You don't own objects you obtain by calling
functions without these words (e.g., "Get")

• You CFRelease() objects you own and are done with

• Some objects have different cleanup:
AudioQueueDispose(), CGPDFDocumentRelease()


Toll-Free Bridging
• Many CF opaque types are identical to NS equivalents in
Foundation, and can be cast at zero cost

CFStringRef myCFString = (CFStringRef) myNSString;

NSString *myNSString = (NSString*) myCFString;

• With ARC, use

• __bridge_transfer to give ARC ownership

• __bridge_retained to relieve ARC of ownership

• __bridge to keep ARC out of it.


TF-Bridged Types
NSArray = CFArray
NSMutableArray = CFMutableArray
NSCalendar = CFCalendar
NSCharacterSet = CFCharacterSet
NSMutableCharacterSet = CFMutableCharacterSet
NSData = CFData
NSMutableData = CFMutableData
NSDate = CFDate
NSDictionary = CFDictionary
NSMutableDictionary = CFMutableDictionary
NSNumber = CFNumber
NSTimer = CFRunLoopTimer
NSSet = CFSet
NSMutableSet = CFMutableSet
NSString = CFString
NSMutableString = CFMutableString
NSURL = CFURL
NSTimeZone = CFTimeZone
NSInputStream = CFReadStream
NSOutputStream = CFWriteStream
NSAttributedString = CFAttributedString
NSMutableAttributedString = CFMutableAttributedString

From cocoadev.com

So, anyways…


/** Get the list of presets for the AUiPodEQ unit as a
CFArrayRef / NSArray of AUPreset structs (note: these
are structs, not NSObjects/ids... use
CFArrayGetValueAtIndex()).
*/
-(CFArrayRef) iPodEQPresets;


UInt32 size = sizeof(iPodEQPresets);
OSStatus presetsErr = AudioUnitGetProperty(
iPodEQUnit,
kAudioUnitProperty_FactoryPresets,
kAudioUnitScope_Global,
0,
&iPodEQPresets,
&size);


Wait, what?


objectAtIndex:
Returns the object located at index.

- (id)objectAtIndex:(NSUInteger)index

CFArrayGetValueAtIndex
Retrieves a value at a given index.

const void * CFArrayGetValueAtIndex (
CFArrayRef theArray,
CFIndex idx
);


Fun with strings


// perform substitutions - strip anything that can't be in an
// XML attribute (note for future: if highlights are disappearing,
// this is probably why... they'll generate a parsing error and
// get thrown away, possibly nuking the whole notes file)

[cleanedUpString replaceOccurrencesOfString:@"—"
withString:@"--"
! ! ! ! ! ! ! ! ! options:0
range:NSMakeRange(0,
[cleanedUpString length])];

[cleanedUpString replaceOccurrencesOfString:@"“"
withString:@"""
! ! ! ! ! ! ! ! ! options:0
range:NSMakeRange(0,
[cleanedUpString length])];


CFStringTransform
Perform in-place transliteration on a mutable string.

Boolean CFStringTransform (
CFMutableStringRef string,
CFRange *range,
CFStringRef transform,
Boolean reverse
);


Transform Identiﬁers for CFStringTransform
Constants that identify transforms used with CFStringTransform.

const CFStringRef kCFStringTransformStripCombiningMarks;
const CFStringRef kCFStringTransformToLatin;
const CFStringRef kCFStringTransformFullwidthHalfwidth;
const CFStringRef kCFStringTransformLatinKatakana;
const CFStringRef kCFStringTransformLatinHiragana;
const CFStringRef kCFStringTransformHiraganaKatakana;
const CFStringRef kCFStringTransformMandarinLatin;
const CFStringRef kCFStringTransformLatinHangul;
const CFStringRef kCFStringTransformLatinArabic;
const CFStringRef kCFStringTransformLatinHebrew;
const CFStringRef kCFStringTransformLatinThai;
const CFStringRef kCFStringTransformLatinCyrillic;
const CFStringRef kCFStringTransformLatinGreek;
const CFStringRef kCFStringTransformToXMLHex;
const CFStringRef kCFStringTransformToUnicodeName;
const CFStringRef kCFStringTransformStripDiacritics;


ICU Transforms
• Any-Remove • Any-Hex

• Any-Lower, Any-Upper, • Any-Hex/XML
Any-Title
• Any-Accents
• Any-NFD, Any-NFC,
Any-NFKD, Any-NFKC • Any-Publishing

• Any-Name • Fullwidth-Halfwidth

Or a custom transform following the ICU syntax, see
http://userguide.icu-project.org/transforms/general

ICU Transforms


Weird CF Collections
• CFBag — Unordered collection that allows
duplicates (compare to CFSet)

• CFBitVector — Ordered collection of bit values

• CFBinaryHeap — Mutable collection sorted by
a binary search function you provide

• CFTree — Mutable tree-structure collection


Unique IDs


UUID
• “Universally Unique Identiﬁer”

• 128-bit / 16 bytes

• Usually written as hex pattern 8-4-4-12

• Standardized as RFC 4122, et. al.

• Early versions used MAC address and date; newer
versions are based on huge random numbers


CFUUID
Creating CFUUID Objects
CFUUIDCreate
CFUUIDCreateFromString
CFUUIDCreateFromUUIDBytes
CFUUIDCreateWithBytes

Getting Information About CFUUID Objects
CFUUIDCreateString
CFUUIDGetConstantUUIDWithBytes
CFUUIDGetUUIDBytes


UUID strength
• 340,282,366,920,938,463,463,374,607,431,768
,211,456 possible UUIDs (16 to the 32nd
power)

• 50% chance of a duplicate UUID if:

• Everyone on Earth had 600 million UUIDs, or

• You generated 1 billion UUIDs every second
for the next 100 years


UUID and You

• -[UIDevice uniqueIdentiﬁer] is deprecated in
iOS 5

• Guidance from Apple is for apps to use a
CFUUID to uniquely identify an installed
instance.


Network Stuff


CFNetwork
• Non-blocking socket-level APIs (CFSocket,
CFStream)

• Host name resolution

• HTTP/HTTPS/FTP, with authentication

• Bonjour


Reachability

• Check SCNetworkReachabilityFlags()
to determine if you can reach a given host,
check to see if it's wiﬁ or cellular
(kSCNetworkReachabilityFlagsIsWWAN)

• Register for callbacks with
SCNetworkReachabilitySetCallback()


Captive Network
• App registers SSIDs of known-friendly wiﬁ
networks with CNSetSupportedSSIDs()

• Login/TOS web sheet will be suppressed for
these wiﬁ hotspots

• App indicates authentication success/failure
with CNMarkPortalOnline()/
CNMarkPortalOffline()


Hypothetical CN Use


Core Telephony
• Obj-C framework to be notiﬁed of changes in call states

• CTCallStateDialing,
CTCallStateIncoming,
CTCallStateConnected,
CTCallStateDisconnected

• CTCarrier lets you inspect carrier ID, country code,
whether it allows VoIP on its network

• No access to call numbers, call audio, etc.


Dead Ends


CFPlugIn
• API for discovering and implementing
executable code modules at runtime

• Plugin code is packaged as bundles

• iPhone OS 3 had a custom Audio Unit API
based on CFPlugIn

• But it was removed in iOS 4. Uh oh…


PDF
Abandon all hope ye who parse here…


Portable Document
Format (PDF)
• Open format, ISO standard

• 9 versions since 1.0 in 1993

• Basically an extensible container format, a
subset of PostScript, and a font-bundling/
replacement system


CGPDF
• Core Graphics API for:

• Rendering PDF content in Quartz

• Providing a PDF context for Quartz drawing
commands

• Parsing PDF contents


CGPDFDocument…

• Open PDF doc with URL, then get metadata
with CGPDFDocumentGetVersion,
CGPDFDocumentGetInfo,
CGPDFDocumentGetID,
CGPDFDocumentAllowsPrinting, etc

NSURL *pdfURL = [NSURL fileURLWithPath:pdfPath];
self.pdfDocument = CGPDFDocumentCreateWithURL(
(__bridge CFURLRef) pdfURL);


CGPDFPage
• From CGPDFDocumentGetPage()

• CGPDFPageGetBoxRect() — gets
rectangles describing important spaces like
physical media area (kCGPDFMediaBox) or
meaningful content (kCGPDFArtBox)

• Metadata in CGPDFPageGetDictionary()


Drawing a page
if (NULL != _currentPDFPage) {
! CGContextRef context = UIGraphicsGetCurrentContext();

! // background
! CGContextSetFillColorWithColor(context,
! ! ! ! ! ! ! ! ! [UIColor grayColor].CGColor);
! CGContextFillRect(context, self.bounds);

! // draw pdf page
! ! ! ! ! ! ! ! ! [UIColor whiteColor].CGColor);
! CGContextDrawPDFPage(context, _currentPDFPage);
}


Oops.


PDF coordinate system

• PDF coordinate system puts (0,0) at upper
left; increasing Y values go down (similar to
UIKit)

• Need to scale Y by -1.0 and translate prior to
drawing


-(void) resetTransform {
! CGAffineTransform centerToOrigin =
! ! CGAffineTransformMakeTranslation(
! ! ! ! ! ! ! ! ! ! self.bounds.size.width / 2.0,
! ! ! ! ! ! ! ! ! ! self.bounds.size.height / -2.0);
! CGAffineTransform flip = CGAffineTransformMakeScale(
! ! ! ! ! ! ! ! ! ! 1.0, -1.0);
! CGAffineTransform originToCenter =
! ! CGAffineTransformInvert(centerToOrigin);
! self.pdfTransform = CGAffineTransformConcat(
! ! ! ! ! ! ! ! ! ! centerToOrigin, flip);
! self.pdfTransform = CGAffineTransformConcat(
! ! ! ! ! ! ! ! ! self.pdfTransform, originToCenter);
! [self setNeedsDisplay];
}


Draw with transform
if (NULL != _currentPDFPage) {
! CGContextRef context = UIGraphicsGetCurrentContext();

! // background
! ! ! ! ! ! ! ! ! [UIColor grayColor].CGColor);

! // draw pdf page
! CGContextSaveGState (context);
! CGContextConcatCTM(context, self.pdfTransform);
! ! ! ! ! ! ! ! ! [UIColor whiteColor].CGColor);
! CGContextDrawPDFPage(context, _currentPDFPage);
! CGContextRestoreGState(context);
}

PDF Drawing Demo


Drawing into PDF
• Create a PDF drawing context with
CGPDFContextCreateWithURL()

• Start each page with CGContextStartPage()

• Draw with Quartz as usual

• End pages with CGContextEndPage()

• CFContextRelease() to ﬁnish writing to ﬁle


Create PDF Context
CFMutableDictionaryRef pdfDict =
! CFDictionaryCreateMutable(NULL, 0,
! ! &kCFTypeDictionaryKeyCallBacks,
! ! &kCFTypeDictionaryValueCallBacks);
CFDictionarySetValue(pdfDict, kCGPDFContextTitle,
! ! ! ! ! ! ! ! CFSTR("Exported PDF"));
CFDictionarySetValue(pdfDict, kCGPDFContextCreator,
! ! ! ! ! ! ! ! CFSTR("CocoaConf demo app"));

CGRect *pageRect = malloc (sizeof (CGRect));
// TODO: use a box
*pageRect = CGRectMake (0.0, 0.0, 612.0, 792.0);
CGContextRef pdfContext = CGPDFContextCreateWithURL(
! ! ! ! ! ! ! ! url, pageRect, pdfDict);


Draw into PDF context
CGContextBeginPage (pdfContext, pageRect);
CGContextDrawPDFPage(pdfContext,
! ! ! ! ! ! self.pdfView.currentPDFPage);
NSString *watermarkString = [NSString
! stringWithFormat:@"Created at CocoaConf at %@",
! ! [NSDate date]];
const char* watermarkCString = [watermarkString
UTF8String];
NSInteger watermarkLength = [watermarkString length];
CGContextSelectFont(pdfContext, PDF_EXPORT_FONT_NAME,
! ! PDF_EXPORT_FONT_SIZE, kCGEncodingMacRoman);
CGContextRotateCTM(pdfContext, 0.25 * M_PI);
CGContextSetFillColorWithColor(pdfContext,
! ! ! ! ! ! [UIColor redColor].CGColor);
CGContextShowTextAtPoint(pdfContext, 300.0, 150.0,
! ! ! ! ! ! watermarkCString, watermarkLength);
CGContextEndPage(pdfContext);

Exporting PDF Demo


Accessing PDF
Contents

• It can't be that hard, can it?


Parsing PDFs is Hard
• Document and pages have metadata
dictionary

• One dictionary item is "Contents", value is a
content stream

• Content stream may be contents, or an array
of content streams


Content streams
• Content streams contain everything you see
on the page: fonts, graphics, text

• Stream is literally that: a start to end stream of
data and drawing instructions

• Generally no representation of the structure of
the content (paragraphs, lines, words)


Trivial example: ABC
BT
/F13 12 Tf
288 720 Td
(ABC) Tj
ET

1. Select Helvetica font (/F13)

2. Move to coordinates (288, 720)

3. Stroke characters "ABC"


Text Operators
• Text state: Tf (font), Tfs (font size), Tc
(character spacing), Tw (word spacing)…

• Text position: Tm (matrix for new position), TD/
Td (next line with offset matrix), …

• Text showing: Tj (show string), TJ (show array
of glyphs)


Handling the Operators

• Set up a CGPDFScanner with a given content
stream

• Register callback functions for the operators
you want to deal with

• Call CGPDFScannerScan()


void scanContentStream (CGPDFContentStreamRef stream) {
! NSLog (@"scanContentStream()");
! CGPDFOperatorTableRef operatorTable =
! ! ! ! ! ! CGPDFOperatorTableCreate();
! CGPDFOperatorTableSetCallback(operatorTable, "TJ",
! ! ! ! ! ! contentStreamTJOperatorCallback);
! CGPDFOperatorTableSetCallback(operatorTable, "Tj",
! ! ! ! ! ! contentStreamTjOperatorCallback);
! CGPDFOperatorTableSetCallback(operatorTable, "Td",
! ! ! ! ! ! contentStreamTdOperatorCallback);
! CGPDFOperatorTableSetCallback(operatorTable, "TD",
! ! ! ! ! ! contentStreamTDOperatorCallback);
! CGPDFOperatorTableSetCallback(operatorTable, "Tm",
! ! ! ! ! ! contentStreamTmOperatorCallback);
! CGPDFOperatorTableSetCallback(operatorTable, "T*",
! ! ! ! ! ! contentStreamTStarOperatorCallback);
! CGPDFScannerRef streamScanner = CGPDFScannerCreate(stream,
! ! ! ! ! ! operatorTable, NULL);
! NSLog (@"created scanner");
! bool scanned = CGPDFScannerScan(streamScanner);
! NSLog (@"scan result: %@", scanned ? @"true" : @"false");
! CGPDFScannerRelease(streamScanner);
}

A simple(!) Tj operator
callback
void contentStreamTjOperatorCallback (CGPDFScannerRef scanner,
! ! ! ! ! ! ! ! ! ! ! ! ! void *info) {
! CGPDFStringRef pdfStringToShow;
! bool popped = CGPDFScannerPopString(
! ! ! ! ! ! ! scanner, &pdfStringToShow);
! while (popped) {
! ! CFStringRef stringToShow =
! ! ! ! CGPDFStringCopyTextString(pdfStringToShow);
! ! NSLog (@"contentStreamTjOperatorCallback()[%ld]: %@",
! ! ! ! CFStringGetLength(stringToShow), stringToShow);
! ! [pageText appendString:stringToShow];
! ! CFRelease (stringToShow);
! ! popped = CGPDFScannerPopString(scanner,
! ! ! ! ! ! ! &pdfStringToShow);
! }
}


It gets worse!
• You'd think it would be enough to grab content
streams, scan for Tj operators, build up a string.
But…

• The streams and their contents are not
guaranteed to be in reading order (and often
aren't)

• Need to process all the text moving, styling, font
operators just to ﬁnd where stuff is on the page


Word to the wise: bail!
• Many third-party PDF frameworks available
(licenses and capabilities vary)

• PSPDFKit

• FastPDFKit

• Foxit

• PDFTron

• etc…


Or you can plan on
dealing with
• Multiple font types (Type 1, Type 3, TrueType),
composite fonts, CJKV issues, Unicode
mappings, glyphs, glyph metrics…

• Color-space conversions, halftone screens,
transparency/translucency…

• Images, graphics commands (ﬁlls, strokes,
etc.)…


You know, I've learned
something today…


Takeaways
• C-based frameworks in iOS have a lot of neat
stuff that doesn't exist in Foundation or Cocoa
Touch

• Granted, it also has duplication and dead-
end Carbon legacies

• Look around docs and headers, ask
questions, ﬁnd stuff


Questions?

invalidname@gmail.com
@invalidname
http://www.subfurther.com/blog


Core What?

More Related Content

What's hot (19)

Similar to Core What? (20)

More from Chris Adamson (20)

Recently uploaded (20)

Core What?