Using Private APIs Getting Started with
 Making macOS Utility App Yoshimasa Niwa 9/8/2019 — TIME SHARING ࢛୩
 macOS native symposium #05

@niw
 Yoshimasa Niwa

Do you like it? Touch Bar

A simple utility application to trigger haptic feedback when tapping Touch Bar Haptic Key

github.com/niw/HapticKey

Today’s presentation Topics 1. We have no windows 2. We launch app when login 3. We watches Touch Bar events 4. We use track pad actuator

No, no, we don’t need ! No windows

No content

No content

statusItemWithLength: NSStatusBarItem • applicationDidFinishLaunching: is still application entry point • Create NSStatusBarItem from NSStatusBar • Use NSStatusItemBehaviorRemovalAllowed to let users to arrange items in status bar.
 The position is persistent in NSUserDefaults

No content

LSUIElement is YES Hide dock icon • In Info.plist, set Application is agent (UIElement) to YES • That’s it

A few additional things Caveats • Provide a way to quit app, or user can’t quit app • Status bar menu is the main user interface to communicate with users. Provide simple, intuitive menu items • Status bar icon may represent application state, such as enabled, disabled

But we have status bar item and menu No main window • Use NSStatusBar and NSStatusBarItem • Set LSUIElement to YES • Status bar menu is the main user interface

Login item, you’re so… ☹ Launch app when login

You might see this Start on Login

You might know this preference Login Items

You might find this API SMLoginItemSetEnabled • Enable a helper application located in the main application bundle’s “Contents/Library/LoginItems” directory

No content

Useless, unless you need to put your app in App Store SMLoginItemSetEnabled • It never work if you have two copy of application bundles that have same bundle identifier … and you will always have the two or more of them in the derived data and the archives • This is not adding Login Item to the account preferences. Completely different logic and more similar to /Library/LaunchAgents

☹

This is the one you need LSSharedFileList • Deprecated but still supported • You can add, remove Login Item • You can observe Login Item changes

☺

Example code seems working LSSharedFileList LSSharedFileListRef fileList = LSSharedFileListCreate(NULL,
 kLSSharedFileListSessionLoginItems, NULL); LSSharedFileListAddObserver(fileList, ..., callback, ...); void callback(LSSharedFileListRef fileList, void *context) { NSArray *snapshot = (__bridge NSArray *)
 LSSharedFileListCopySnapshot(fileList, ...); 
 for (item in snapshot) { CFURLRef url; LSSharedFileListItemResolve(item, ..., &url); if ([(__bridge NSURL *)url isEqualTo:applicationBundlerURL]) { // changed! } } }

No content

NSDistributedNotificationCenter stops working LSUIElement app is always inactive • LSSharedFileList is using NSDistributedNotificationCenter • LSUIElement app is always inactive • NSDistributedNotificationCenter will not deliver any notifications if app is inactive

NSNotificationSuspensionBehaviorDeliverImmediately Listen com.apple.private.BackgroundItemsChang • LSSharedFileList listens com.apple.private.BackgroundItemsChan geNotification • If the application process listens that notification as well with NSNotificationSuspensionBehaviorDeliv erImmediately option, LSSharedFileList can also listen it

https://github.com/niw/HapticKey/blob/master/ HapticKey/Classes/HTKLoginItem.m

• SMLoginItemSetEnabled is not what we want • LSSharedFileList is the one • LSUIElement app also need to listen com.apple.private.BackgroundItemsChan geNotification LSSharedFileList is the one but requires some tricks Launch app when login

We’re watching you Touch Bar events

No content

No content

https://docs.google.com/presentation/d/ 1nEaiPUduh1vjks0rDVRTcJaEULbSWWh1tVdG2HF_XSU/edit?usp=sharing

Overview ● macOS provides several APIs for event observing. ○ [NSView keyDown] ○ [NSApplication sendEvent] ○ CGEventTapCreate, [NSEvent addGlobalMonitorForEvents] ○ IOHIDQueueRegisterValueAvailableCallback ○ etc. ● macOS Catalina (10.15) will require a user approval of input monitoring for security. (Congratulation!) https://docs.google.com/presentation/d/1nEaiPUduh1vjks0rDVRTcJaEULbSWWh1tVdG2HF_XSU/edit?usp=sharing

We can listen system event • CGEventTapCreate with event masks to listen specific events • We can listen keyboard events such as Fn keys • We can listen gesture events, which includes taps on Touch Bar CGEventTap

Listener Feedback Key event, Tap event, … Haptic, Sound, Screen, … Event ✔

Don’t hide it or we will find it Private API

API is a set of functions that many application can use What is API? • macOS API is provided in shared libraries • In form of C or Objective-C or Swift • Newer API may not be implemented in Objective-C • Application are using shared libraries through dyld(1)

Public API is pubic because it is public Why public API is public? • Public API is public because it is documented • Public API is public because its name is visible • Public API is public because it is allowed to access from the application

Private API is private because it’s not public Why private API is private? • Private API is private because it is not documented • Private API is private because its name is not visible • Private API is private because it is not allowed to access from the application

Private API is private because it’s not public Why private API is private? • Private API is private because it is not documented • Private API is private because its name is not visible • Private API is private because it is not allowed to access from the application

A container contains all related resources Framework Bundle • API is in shared library, which is lay outed in .framework bundle format • Public one is in /System/Library/Frameworks • Private our is in /System/Library/ PrivateFrameworks

/System/Library/PrivateFrameworks/MultitouchSupport.framework Use MultitouchSupport • A private framework that provides multitouch track pad related functions on macOS • This framework also provides track pad vibration

Well, I was too lazy to make slides… Hands-on

Command line tools Hands-on tools • Use nm -m dylib to find exported function names • Use otool -t -V -p function dylib to disassemble function • Use clang -iframework /System/ Library/PrivateFrameworks -framework framework to link private framework

Example code @import Foundation; @import IOKit; CF_EXPORT CFTypeRef MTActuatorCreateFromDeviceID(UInt64 deviceID); CF_EXPORT IOReturn MTActuatorOpen(CFTypeRef actuatorRef); CF_EXPORT IOReturn MTActuatorClose(CFTypeRef actuatorRef); CF_EXPORT IOReturn MTActuatorActuate(CFTypeRef actuatorRef, SInt32 actuationID, UInt32 unknown1, Float32 unknown2, Float32 unknown3); int main() { IOReturn error; CFTypeRef actuatorRef = MTActuatorCreateFromDeviceID(0x200000001000000 );
 if (!actuatorRef) {
 return -1;
 } error = MTActuatorOpen(actuatorRef);
 if (error != kIOReturnSuccess) {
 CFRelease(actuatorRef);
 return -1;
 } error = MTActuatorActuate(actuatorRef, 6, 0, 0, 0.2); error = MTActuatorClose(actuatorRef); CFRelease(actuatorRef);
 actuatorRef = NULL; return 0; } Hands-on sample

https://github.com/niw/HapticKey/blob/master/ HapticKey/Classes/HTKMultitouchActuator.m

Disassembling, researching and guessing. Private API • nm, otool, and also lldb • Hopper Disassembler is the tool helps your research • Always guess how API is designed and works

Questions? Q&A